claude-mococo

AI assistants on Discord. Each assistant is a real Discord bot backed by an AI engine (Claude, Codex, Gemini). It has its own GitHub account, personality, and permissions. Start with one, add more when you need them.

You: "Add a login page to my-app"

Assistant (bot): "On it. I'll create the auth routes and login form."
               → commits code → pushes branch → opens PR

Quick Start

1. Install

npm install -g claude-mococo

Or run directly without installing:

npx claude-mococo init
npx claude-mococo add
npx claude-mococo start

You also need at least one AI engine:

claude --version                  # Claude CLI (recommended)
npm install -g @openai/codex      # Codex CLI (optional)
npm install -g @google/gemini-cli # Gemini CLI (optional)

2. Create a Discord bot

1. Go to discord.com/developers/applications → New Application
2. Name it anything (e.g. my-assistant)
3. Sidebar → Bot:
   • Copy the bot token
   • Enable all three Privileged Gateway Intents (Presence, Server Members, Message Content)
4. Sidebar → OAuth2:
   • Scopes: bot
   • Permissions: Send Messages, Read Message History, Embed Links, Attach Files
   • Copy the URL → open in browser → add to your server

3. Initialize and add your assistant

mkdir my-team && cd my-team
mococo init                   # creates workspace (asks for Discord channel ID)
mococo add                    # interactive wizard — asks for name, engine, tokens, etc.

Commits will show the assistant's name as the author (configured via git.name in teams.json). If you need assistants to push or create PRs, provide your GitHub PAT during mococo add.

4. Link your repos and start

ln -s /path/to/my-app repos/my-app
mococo start

Talk to your bot in the Discord channel. Done.

CLI Commands

| Command | Description | |---------|-------------| | mococo init | Create a new workspace in the current directory | | mococo add | Add an assistant (interactive wizard) | | mococo start | Start all assistants | | mococo list | List configured assistants | | mococo remove <id> | Remove an assistant |

Adding More Assistants

mococo add        # repeat for each new assistant

Each one gets:

• Its own Discord bot (separate identity in chat)
• Its own git author name (visible in commit messages)
• Its own entry in teams.json (engine, personality, permissions)

You can build a full team this way:

| Assistant | Engine | Role | |-----------|--------|------| | Leader | Claude | Delegates work to other assistants | | Planner | Codex | Creates plans and specs | | Coder | Claude | Writes code | | Reviewer | Claude | Reviews and opens PRs | | Designer | Gemini | UI/UX guidance |

Or just run a single assistant. It's up to you.

How It Works

Message routing:

• If you @mention a specific bot → that assistant responds
• If no mention → the first assistant marked "isLeader": true responds

When an assistant mentions another (e.g. @Reviewer please check this) → that assistant is automatically invoked.

Permissions are controlled per-assistant in teams.json:

"permissions": {
  "allow": ["git push", "gh pr create"],
  "deny": ["gh pr merge"]
}

Engines: "claude" runs as a full agent (files, git, commands). "codex" and "gemini" run as text-only advisors.

Heartbeat & Scheduled Tasks:

The leader assistant runs a heartbeat every 3 minutes. If a heartbeat.md file exists in the workspace root, it is parsed for scheduled tasks:

| Section | Frequency | Description | |---------|-----------|-------------| | ## Daily | Once per day (first heartbeat) | Daily recurring tasks | | ## Weekly | Once per week (Monday, first heartbeat) | Weekly recurring tasks | | ## Periodic | Every heartbeat (3 min) | Lightweight monitoring tasks | | ## On-demand | Manual trigger only | One-off or special tasks |

Task format:

- [ ] Task description @assignee

• - [ ] = active (processed by heartbeat)
• - [x] = inactive (skipped)
• @assignee = optional, routes to a specific assistant

State is tracked in .mococo/heartbeat-state.json to avoid re-running daily/weekly tasks.

Configuration Reference

teams.json fields

| Field | Description | |-------|-------------| | engine | "claude", "codex", or "gemini" | | model | Model name (e.g. "sonnet", "opus", "o3", "gemini-2.5-pro") | | maxBudget | Max dollar spend per invocation (Claude only) | | prompt | Path to the personality/instructions file | | isLeader | If true, responds to all messages (not just @mentions) | | git.name / git.email | Git author for commits | | permissions.allow / permissions.deny | Allowed/denied shell commands |

Discord commands

| Command | Description | |---------|-------------| | !status | Show all assistants (busy/idle, online/offline) | | !teams | List assistants and their engines | | !repos | List linked repositories |

Manual Setup (without CLI)

You can also set up manually by cloning the repo:

git clone https://github.com/wodn5515/claude-mococo.git
cd claude-mococo
npm install
npm run build

Edit teams.json directly, create prompt files in prompts/, set tokens in .env, then npm start.

Troubleshooting

| Problem | Fix | |---------|-----| | Bot doesn't respond | Enable Message Content Intent in Discord Developer Portal | | "No team has a Discord token" | Add the token env var to .env | | Can't push to GitHub | Check the GitHub PAT in .env is valid | | Wrong commit author | Set git.email to [email protected] | | "command not found: codex" | Install it or change engine to "claude" |

License

MIT