ClaudeClaw Customization

This skill helps users add capabilities or modify behavior. Use AskUserQuestion to understand what they want before making changes.

Mode Detection

Check if

.claude-plugin/plugin.json

cat .claude-plugin/plugin.json 2>/dev/null | grep '"name": "claudeclaw"' && echo "DEVELOPER_MODE" || echo "PLUGIN_MODE"

If plugin mode, offer the user a choice via AskUserQuestion:

• Fork to developer mode (Recommended) — Clone the repo into a new directory, copy state, full self-improvement and customization
• Continue in plugin mode — Limited to channel setup and config changes (no code editing)

If "Fork to developer mode" is chosen, run the migration flow below. Otherwise, proceed with the normal workflow (limited to invoking existing skills like

/add-slack

/add-telegram

Migration: Plugin → Developer Mode

1. AskUserQuestion: "To customize ClaudeClaw fully, you need your own fork. First, fork sbusso/claudeclaw on GitHub. What's your GitHub username?"
2. AskUserQuestion: "Where should I clone the repo?" (default:

   ~/Code/claudeclaw

   )

Service name: Derived from the directory name:

com.claudeclaw.<dirname>

(macOS) /

claudeclaw-<dirname>

(Linux). For example, if cwd is

my-assistant

, the service is

com.claudeclaw.my-assistant

. Determine the correct service name before running service commands below.

3. Stop running service (service name derived from current directory name):
   • macOS:

     launchctl unload ~/Library/LaunchAgents/com.claudeclaw.<dirname>.plist

   • Linux:

     systemctl --user stop claudeclaw-<dirname>

4. Clone:

   git clone https://github.com/<username>/claudeclaw.git <clone-path>

5. Copy state from current data directory:

   cp -r store groups .env <clone-path>/

6. AskUserQuestion: "Copy logs too?" If yes:

   cp -r logs <clone-path>/

7. Clear stale sessions:

   sqlite3 <clone-path>/store/messages.db "DELETE FROM sessions"

8. Install and build:

   cd <clone-path> && npm install && npm run build

9. Set up upstream:

   cd <clone-path> && git remote add upstream https://github.com/sbusso/claudeclaw.git

10. Run service setup:

    cd <clone-path> && npx tsx setup/index.ts --step service

11. Print: "Migration complete! Run

    cd <clone-path> && claude

    to use developer mode. Remove

    --plugin-dir

    from your Claude Code invocation."

Workflow

1. Understand the request - Ask clarifying questions
2. Plan the changes - Identify files to modify. If a skill exists for the request (e.g.,

   /add-telegram

   for adding Telegram), invoke it instead of implementing manually.
3. Implement - Make changes directly to the code
4. Test guidance - Tell user how to verify

Key Files

src/service.ts

src/index.ts

src/orchestrator/message-loop.ts

src/orchestrator/config.ts

src/orchestrator/channel-registry.ts

src/orchestrator/extensions.ts

src/orchestrator/types.ts

src/orchestrator/db.ts

groups/CLAUDE.md

Common Customization Patterns

Adding a New Input Channel (e.g., Telegram, Slack, Email)

Questions to ask:

• Which channel? (Telegram, Slack, Discord, email, SMS, etc.)
• Same trigger word or different?
• Same memory hierarchy or separate?
• Should messages from this channel go to existing groups or new ones?

Implementation pattern:

1. Create

   src/channels/{name}.ts

   implementing the

   Channel

   interface from

   src/orchestrator/types.ts

   (see

   src/channels/whatsapp.ts

   for reference)
2. Add the channel instance to

   main()

   in

   src/index.ts

   and wire callbacks (

   onMessage

   ,

   onChatMetadata

   )
3. Messages are stored via the

   onMessage

   callback; routing is automatic via

   ownsJid()

Adding a New MCP Integration

Questions to ask:

• What service? (Calendar, Notion, database, etc.)
• What operations needed? (read, write, both)
• Which groups should have access?

Implementation:

1. Add MCP server config to the container settings (see

   src/orchestrator/container-runner.ts

   for how MCP servers are mounted)
2. Document available tools in

   groups/CLAUDE.md

Changing Assistant Behavior

Questions to ask:

• What aspect? (name, trigger, persona, response style)
• Apply to all groups or specific ones?

Simple changes → edit

src/orchestrator/config.ts

groups/CLAUDE.md

CLAUDE.md

Adding New Commands

Questions to ask:

• What should the command do?
• Available in all groups or main only?
• Does it need new MCP tools?

Implementation:

1. Commands are handled by the agent naturally — add instructions to

   groups/CLAUDE.md

   or the group's

   CLAUDE.md

2. For trigger-level routing changes, modify

   processGroupMessages()

   in

   src/index.ts

Changing Deployment

Questions to ask:

• Target platform? (Linux server, Docker, different Mac)
• Service manager? (systemd, Docker, supervisord)

Implementation:

1. Create appropriate service files
2. Update paths in config
3. Provide setup instructions

After Changes

Always tell the user:

# Rebuild and restart
npm run build
# macOS:
launchctl unload ~/Library/LaunchAgents/com.claudeclaw.plist
launchctl load ~/Library/LaunchAgents/com.claudeclaw.plist
# Linux:
# systemctl --user restart claudeclaw

Example Interaction

User: "Add Telegram as an input channel"

1. Ask: "Should Telegram use the same @Andy trigger, or a different one?"
2. Ask: "Should Telegram messages create separate conversation contexts, or share with WhatsApp groups?"
3. Create

   src/channels/telegram.ts

   implementing the

   Channel

   interface (see

   src/channels/whatsapp.ts

   )
4. Add the channel to

   main()

   in

   src/index.ts

5. Tell user how to authenticate and test