MatClaw Customization
This skill helps users add capabilities or modify behavior. Use AskUserQuestion to understand what they want before making changes.
Workflow
- Understand the request - Ask clarifying questions
- Plan the changes - Identify files to modify
- Implement - Make changes directly to the code
- Test guidance - Tell user how to verify
Key Files
| File |
Purpose |
src/index.ts |
Orchestrator: state, message loop, agent invocation |
src/channels/whatsapp.ts |
WhatsApp connection, auth, send/receive |
src/ipc.ts |
IPC watcher and task processing |
src/router.ts |
Message formatting and outbound routing |
src/types.ts |
TypeScript interfaces (includes Channel) |
src/config.ts |
Assistant name, trigger pattern, directories |
src/db.ts |
Database initialization and queries |
src/whatsapp-auth.ts |
Standalone WhatsApp authentication script |
groups/CLAUDE.md |
Global memory/persona |
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:
- Create
src/channels/{name}.ts implementing the Channel interface from src/types.ts (see src/channels/whatsapp.ts for reference)
- Add the channel instance to
main() in src/index.ts and wire callbacks (onMessage, onChatMetadata)
- 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:
- Add MCP server config to the container settings (see
src/container-runner.ts for how MCP servers are mounted)
- 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/config.ts
Persona changes → edit groups/CLAUDE.md
Per-group behavior → edit specific group's 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:
- Commands are handled by the agent naturally — add instructions to
groups/CLAUDE.md or the group's CLAUDE.md
- 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:
- Create appropriate service files
- Update paths in config
- Provide setup instructions
After Changes
Always tell the user:
# Rebuild and restart
npm run build
# macOS:
launchctl unload ~/Library/LaunchAgents/com.matclaw.plist
launchctl load ~/Library/LaunchAgents/com.matclaw.plist
# Linux:
# systemctl --user restart matclaw
Example Interaction
User: "Add Telegram as an input channel"
- Ask: "Should Telegram use the same @Andy trigger, or a different one?"
- Ask: "Should Telegram messages create separate conversation contexts, or share with WhatsApp groups?"
- Create
src/channels/telegram.ts implementing the Channel interface (see src/channels/whatsapp.ts)
- Add the channel to
main() in src/index.ts
- Tell user how to authenticate and test
1---2name: customize-53description: Add new capabilities or modify MatClaw behavior. Use when user wants to add channels (Telegram, Slack, email input), change triggers, add integrations, modify the router, or make any other customizations. This is an interactive skill that asks questions to understand what the user wants.4---5
6# MatClaw Customization
7
8This skill helps users add capabilities or modify behavior. Use AskUserQuestion to understand what they want before making changes.
9
10## Workflow
11
121. **Understand the request** - Ask clarifying questions
132. **Plan the changes** - Identify files to modify
143. **Implement** - Make changes directly to the code
154. **Test guidance** - Tell user how to verify
16
17## Key Files
18
19| File | Purpose |
20|------|---------|
21| `src/index.ts` | Orchestrator: state, message loop, agent invocation |
22| `src/channels/whatsapp.ts` | WhatsApp connection, auth, send/receive |
23| `src/ipc.ts` | IPC watcher and task processing |
24| `src/router.ts` | Message formatting and outbound routing |
25| `src/types.ts` | TypeScript interfaces (includes Channel) |
26| `src/config.ts` | Assistant name, trigger pattern, directories |
27| `src/db.ts` | Database initialization and queries |
28| `src/whatsapp-auth.ts` | Standalone WhatsApp authentication script |
29| `groups/CLAUDE.md` | Global memory/persona |
30
31## Common Customization Patterns
32
33### Adding a New Input Channel (e.g., Telegram, Slack, Email)
34
35Questions to ask:
36- Which channel? (Telegram, Slack, Discord, email, SMS, etc.)
37- Same trigger word or different?
38- Same memory hierarchy or separate?
39- Should messages from this channel go to existing groups or new ones?
40
41Implementation pattern:
421. Create `src/channels/{name}.ts` implementing the `Channel` interface from `src/types.ts` (see `src/channels/whatsapp.ts` for reference)
432. Add the channel instance to `main()` in `src/index.ts` and wire callbacks (`onMessage`, `onChatMetadata`)
443. Messages are stored via the `onMessage` callback; routing is automatic via `ownsJid()`
45
46### Adding a New MCP Integration
47
48Questions to ask:
49- What service? (Calendar, Notion, database, etc.)
50- What operations needed? (read, write, both)
51- Which groups should have access?
52
53Implementation:
541. Add MCP server config to the container settings (see `src/container-runner.ts` for how MCP servers are mounted)
552. Document available tools in `groups/CLAUDE.md`
56
57### Changing Assistant Behavior
58
59Questions to ask:
60- What aspect? (name, trigger, persona, response style)
61- Apply to all groups or specific ones?
62
63Simple changes → edit `src/config.ts`
64Persona changes → edit `groups/CLAUDE.md`
65Per-group behavior → edit specific group's `CLAUDE.md`
66
67### Adding New Commands
68
69Questions to ask:
70- What should the command do?
71- Available in all groups or main only?
72- Does it need new MCP tools?
73
74Implementation:
751. Commands are handled by the agent naturally — add instructions to `groups/CLAUDE.md` or the group's `CLAUDE.md`
762. For trigger-level routing changes, modify `processGroupMessages()` in `src/index.ts`
77
78### Changing Deployment
79
80Questions to ask:
81- Target platform? (Linux server, Docker, different Mac)
82- Service manager? (systemd, Docker, supervisord)
83
84Implementation:
851. Create appropriate service files
862. Update paths in config
873. Provide setup instructions
88
89## After Changes
90
91Always tell the user:
92```bash
93# Rebuild and restart
94npm run build
95# macOS:
96launchctl unload ~/Library/LaunchAgents/com.matclaw.plist
97launchctl load ~/Library/LaunchAgents/com.matclaw.plist
98# Linux:
99# systemctl --user restart matclaw
100```
101
102## Example Interaction
103
104User: "Add Telegram as an input channel"
105
1061. Ask: "Should Telegram use the same @Andy trigger, or a different one?"
1072. Ask: "Should Telegram messages create separate conversation contexts, or share with WhatsApp groups?"
1083. Create `src/channels/telegram.ts` implementing the `Channel` interface (see `src/channels/whatsapp.ts`)
1094. Add the channel to `main()` in `src/index.ts`
1105. Tell user how to authenticate and test
majiayu000