setup

<Purpose> Setup is the complete installation and configuration wizard for SuperClaw. It systematically checks all prerequisites, configures services, builds MCP servers, sets up integrations (Telegram, heartbeat, memory), and validates the entire installation end-to-end. This is the single entry point for first-time setup, reconfiguration, and troubleshooting connectivity issues. </​Purpose>

<Use_When>

• User says "setup", "configure", "설정" and wants to reconfigure SuperClaw
• Reconfiguring Telegram, gateway, or other components after initial install
• User reports connectivity issues with gateway, Telegram, or memory
• After upgrading SuperClaw to a new version
• NOTE: First-time setup is handled by npm run setup in the terminal, NOT this skill. If superclaw.json doesn't exist, tell the user to run cd ~/​superclaw && npm run setup first. </​Use_When>

<Do_Not_Use_When>

• SuperClaw is already fully configured and working (use sc-status command instead)
• User wants to configure a single component (direct them to the specific skill)
• User is asking about a specific component setup only (direct them to the specific skill)
• The issue is not setup-related (use analyze skill for debugging) </​Do_Not_Use_When>

<Why_This_Exists> SuperClaw depends on multiple external systems (Peekaboo, Node.js, SQLite) and internal services (MCP bridge servers, Telegram bot, memory database). Getting all of these configured correctly is error-prone when done manually. Missing a single step (forgetting to build, wrong bot token) causes silent failures that are hard to diagnose. Setup automates the entire process into a single wizard that checks, configures, builds, and validates everything in the correct order. </​Why_This_Exists>

<Execution_Policy>

• Run ALL prerequisite checks before starting any configuration
• Never skip a failed prerequisite -- report it clearly with install instructions
• Use AskUserQuestion for interactive configuration (bot tokens, preferences)
• Build MCP servers before testing connectivity (stale builds cause phantom failures)
• Test each component individually before running the full integration test
• Save configuration to ~/​superclaw/​superclaw.json
• Display a final status dashboard showing all component states
• Log setup completion to memory for session continuity </​Execution_Policy>

<Steps> 1. **Check prerequisites**: Verify all required software is installed and meets minimum versions.

For each missing prerequisite, display the install command and stop. Do not proceed with a partial setup.

1. Check/​create superclaw.json config: Look for existing configuration at ~/​superclaw/​superclaw.json. If it does not exist, create it from the template:

   {
     "version": "1.0.0",
     "telegram": {
       "enabled": false,
       "bot_token": "",
       "chat_id": "",
       "channel": "telegram"
     },
     "heartbeat": {
       "enabled": true,
       "interval_minutes": 30,
       "collectors": ["system", "dev"],
       "thresholds": {
         "cpu": 80,
         "memory": 85,
         "disk": 90
       },
       "alert_channel": "telegram"
     },
     "memory": {
       "db_path": "data/​memory.db",
       "auto_compact": true,
       "max_entries": 10000
     },
     "peekaboo": {
       "enabled": true,
       "screenshot_dir": "data/​screenshots"
     },
     "pipelines": {
       "store_dir": "data/​pipelines"
     }
   }
   

2. Install dependencies and build: Run npm install and build the MCP server bridges.

   cd ~/​superclaw
   npm install
   npm run build
   

   Verify build output exists:

   • bridge/​sc-bridge.cjs -- Telegram + messaging bridge
   • bridge/​sc-peekaboo.cjs -- Peekaboo (macOS automation) bridge
   • bridge/​sc-memory.cjs -- Memory bridge

3. Configure Telegram (optional): Ask the user if they want Telegram integration.

   AskUserQuestion(
     question: "Do you want to set up Telegram integration for remote notifications?",
     options: ["Yes, I have a bot token", "Yes, help me create one", "Skip for now"]
   )
   

   If yes with token:

   AskUserQuestion(
     question: "Please enter your Telegram bot token (from @BotFather):",
     type: "text"
   )
   

   Then ask for the chat ID:

   AskUserQuestion(
     question: "Enter your Telegram chat ID (send /​start to @userinfobot to find it):",
     type: "text"
   )
   

   If yes without token, provide step-by-step instructions:

   1. Open Telegram and search for @BotFather
   2. Send /​newbot and follow the prompts
   3. Copy the bot token (looks like 123456789:ABCdef...)
   4. Start a chat with your new bot
   5. Send /​start to @userinfobot to get your chat ID

   Save the token and chat ID to superclaw.json.

4. Test each MCP server: Verify each bridge server responds correctly.

   sc-bridge (Telegram):

   sc_telegram_status()  -- Should return { connected: true }
   

   sc-memory (knowledge):

   sc_memory_stats()  -- Should return { entities: N, size_kb: N }
   

   sc-peekaboo (macOS automation):

   sc_screenshot({ display: 1 })  -- Should capture and return a file path
   

   If any server fails, check:

   • Build output exists (step 4)
   • .mcp.json references correct paths
   • Required system services are running

5. Initialize memory database: If ~/​superclaw/​data/​memory.db does not exist or is empty, initialize it:

   sc_memory_store({
     content: "SuperClaw initialized successfully",
     category: "system",
     confidence: 1.0,
     metadata: { event: "setup_complete", timestamp: "now" }
   })
   

   Verify with sc_memory_stats().

6. Create data directories: Ensure all required data directories exist:

   mkdir -p ~/​superclaw/​data/​heartbeats
   mkdir -p ~/​superclaw/​data/​pipelines
   mkdir -p ~/​superclaw/​data/​screenshots
   mkdir -p ~/​superclaw/​data/​skill_metrics
   

7. Run setup-validator agent: Delegate final validation to a dedicated agent:

   Task(subagent_type="superclaw:setup-validator", model="haiku", prompt="
     Validate SuperClaw installation:
     1. Check all bridge files exist in ~/​superclaw/​bridge/
     2. Verify .mcp.json has all 3 server entries
     3. Test sc_telegram_status returns connected
     4. Test sc_memory_stats returns valid stats
     5. Check superclaw.json exists and is valid JSON
     6. Verify data directories exist
     Report pass/​fail for each check.
   ")
   

8. Display status dashboard: Show the final installation status:

   ============================================
    SuperClaw Setup Complete
   ============================================
   
   | Component      | Status      | Details          |
   |----------------|-------------|------------------|
   | Node.js        | OK          | v22.0.0          |
   | sc-bridge      | OK          | Built, responding |
   | sc-memory      | OK          | 42 entities, 48KB |
   | sc-peekaboo    | OK          | Peekaboo found   |
   | Telegram       | Configured  | Bot @mybot       |
   | Heartbeat      | Enabled     | Every 30 min     |
   | Memory DB      | OK          | data/​memory.db   |
   | Data Dirs      | OK          | All created       |
   
   SuperClaw is ready! Try:
   - "take a screenshot and send to telegram"
   - "schedule a heartbeat every 30 minutes"
   - "remember this architecture decision"
   ============================================
   

9. Log setup to memory: Store setup completion for future reference:

   sc_memory_store({
     content: "SuperClaw setup completed successfully. All components verified.",
     category: "system",
     confidence: 1.0,
     metadata: { event: "setup_complete", version: "1.0.0" }
   })
   

</​Steps>

<Tool_Usage>

• Bash -- Run prerequisite checks (node --version, which peekaboo, etc.), build commands (npm install, npm run build), create directories.
• sc_telegram_status -- Test Telegram Bot API connectivity and status.
• sc_memory_stats -- Verify memory database is initialized and responding.
• sc_memory_store -- Initialize memory with setup event, store configuration history.
• sc_screenshot -- Test Peekaboo integration by taking a test screenshot.
• sc_send_message -- Test Telegram integration by sending a test message.
• Read -- Read existing superclaw.json configuration.
• Write -- Create or update superclaw.json configuration file.
• AskUserQuestion -- Interactive prompts for Telegram bot token, preferences, and confirmations.
• Glob -- Find build output files and verify directory structure.
• Grep -- Search configuration files for specific settings. </​Tool_Usage>

<Examples> <Good> Fresh installation on a new machine: 1. Check prerequisites: Node.js v22 OK, npm v10 OK, Peekaboo found, SQLite3 OK 2. Config: superclaw.json not found -> create from template 3. Build: npm install -> 168 packages, npm run build -> 3 bridge files generated 4. Telegram: User provides bot token and chat ID -> saved to config 5. Test Telegram: sc_telegram_status -> { connected: true } 6. Test memory: sc_memory_stats -> { entities: 0, size_kb: 49 } 7. Test Peekaboo: sc_screenshot -> /​tmp/​screenshot-123.png saved 8. Validator: all 6 checks passed 9. Dashboard displayed with all green status

Why good: Every step checked, clear error messages, interactive config, comprehensive verification. </​Good>

<Good> Reconfiguration after Telegram token change: 1. Prerequisites: all OK (skip detailed check since already installed) 2. Config: existing superclaw.json found, read current values 3. User provides new bot token via AskUserQuestion 4. Update superclaw.json with new token 5. Test: sc_send_message("Test from SuperClaw") -> delivered 6. Dashboard: Telegram status updated to new bot

Why good: Minimal disruption, only reconfigures what changed, verifies the change works. </​Good>

<Bad> Setup proceeds despite Node.js not being installed, tries to run npm install, fails with cryptic error.

Why bad: Must check ALL prerequisites before starting configuration. Never skip failed prerequisites. </​Bad>

<Bad> Setup completes but does not run npm run build. User tries to use SuperClaw and gets "bridge file not found" errors.

Why bad: Build step is critical. Stale or missing builds cause phantom failures that are hard to diagnose. </​Bad> </​Examples>

<Escalation_And_Stop_Conditions>

• If any prerequisite is missing, STOP and show install instructions. Do not proceed with partial setup.
• If npm install fails, check for Node.js version compatibility and suggest nvm use 18 or higher
• If npm run build fails, show the build error output and suggest checking tsconfig.json
• If Telegram test message fails, verify bot token format and chat ID. Suggest the user check @BotFather.
• If memory database is corrupted (sc_memory_stats returns error), back up the existing file and create a fresh one
• If the setup-validator agent reports failures, show which specific checks failed and suggest fixes
• Stop if user explicitly cancels setup at any point </​Escalation_And_Stop_Conditions>

<Final_Checklist>

• All prerequisites met (Node.js, npm, Peekaboo, SQLite3)
• superclaw.json configuration file exists and is valid
• npm install completed without errors
• npm run build completed, all 3 bridge files exist
• Telegram configured (or explicitly skipped by user)
• Telegram connectivity test passed
• Each MCP server tested individually
• Memory database initialized and responding
• All data directories created
• Setup-validator agent reports all checks passed
• Status dashboard displayed to user
• Setup completion logged to memory </​Final_Checklist>

<Advanced> ## Full Prerequisite List

Configuration File Template (superclaw.json)

{
  "version": "1.0.0",
  "telegram": {
    "enabled": false,
    "bot_token": "",
    "chat_id": "",
    "channel": "telegram",
    "parse_mode": "Markdown"
  },
  "heartbeat": {
    "enabled": true,
    "interval_minutes": 30,
    "collectors": ["system", "dev"],
    "thresholds": { "cpu": 80, "memory": 85, "disk": 90 },
    "alert_channel": "telegram"
  },
  "memory": {
    "db_path": "data/​memory.db",
    "auto_compact": true,
    "max_entries": 10000,
    "backup_interval_hours": 24
  },
  "peekaboo": {
    "enabled": true,
    "screenshot_dir": "data/​screenshots",
    "default_display": 1
  },
  "pipelines": {
    "store_dir": "data/​pipelines",
    "max_concurrent": 3
  },
  "cron": {
    "default_timezone": "Asia/​Seoul",
    "health_check_interval": "0 */​6 * * *"
  }
}

Manual Setup Steps

If the wizard fails, here is the manual process:

1. cd ~/​superclaw && npm install
2. npm run build
3. Copy the config template above to superclaw.json and fill in values
4. Test: Open Claude Code in the superclaw directory, try sc_telegram_status

Troubleshooting

Uninstall Instructions

To completely remove SuperClaw:

# Remove cron jobs (if using system crontab)
crontab -l  # note all SuperClaw jobs
crontab -e  # remove SuperClaw entries

# Remove files
rm -rf ~/​superclaw/​node_modules
rm -rf ~/​superclaw/​bridge/​*.cjs
rm ~/​superclaw/​superclaw.json
rm ~/​superclaw/​data/​memory.db

# Optionally remove the entire directory
rm -rf ~/​superclaw

Upgrade Guide

When upgrading to a new SuperClaw version:

1. cd ~/​superclaw && git pull (or download new version)
2. npm install (update dependencies)
3. npm run build (rebuild bridges)
4. Run setup wizard again -- it will detect existing config and only update what is new
5. Verify with /​sc-status command

The setup wizard preserves existing configuration values and only adds new fields from the updated template. </​Advanced>