Open Counsel

A framework for running multiple autonomous AI agents as a collaborative team, powered by Claude Code and Discord.

Each agent runs as an independent Claude Code session with its own persona, Discord bot, and MCP (Model Context Protocol) channel server. Agents communicate with your team via Discord and with each other through B2B messaging.

Built on the official MCP channel protocol — no unofficial API calls, no browser automation, no TOS risk.

For AI agents: If you're Claude, Codex, or another AI working with this codebase, read AGENTS.md instead. It's written for you.

Architecture

┌─────────────────────────────────────────────────────┐
│  Discord Server                                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │ #alpha   │  │ #beta    │  │ #gamma   │  ...      │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘          │
└───────┼──────────────┼──────────────┼────────────────┘
        │              │              │
  ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
  │ Channel   │  │ Channel   │  │ Channel   │
  │ Server    │  │ Server    │  │ Server    │
  │ (MCP+Bot) │  │ (MCP+Bot) │  │ (MCP+Bot) │
  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘
        │              │              │
  ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
  │ Claude    │  │ Claude    │  │ Claude    │
  │ Code      │  │ Code      │  │ Code      │
  │ Session   │  │ Session   │  │ Session   │
  └───────────┘  └───────────┘  └───────────┘

Key design: Each channel server is a single Node.js process that acts as both an MCP stdio server (for Claude Code) and a Discord.js bot. No HTTP gateways, no file-based message passing — direct in-process communication.

Features

• Multi-agent collaboration — Each agent has its own role, persona, and Discord channel
• MCP channel protocol — Real-time Discord ↔ Claude Code message bridging
• Auto-restart wrapper — Agents automatically respawn on crash or context compaction
• Session memory system — 30-minute session notes, auto-archival to journals, shared memory
• Hook system — Pre/post-compact context injection, session start restoration, stop guards, diminishing returns detection
• MJ integration — Optional Midjourney watcher with auto-download, button clicking, /imagine via API
• Extensible tools — Add custom MCP tools per agent (see agent-beta.mjs example)
• Permission auto-approve — Agents auto-approve tool permissions for unattended operation

Quick Start

Prerequisites

• Claude Code CLI installed and authenticated
• Node.js 20+
• A Discord server with bot applications created

Setup

1. Clone and install:

   git clone https://github.com/minoming/open-counsel.git
   cd open-counsel
   npm install
   cd channels && npm install && cd ..
   

2. Configure environment:

   cp .env.example .env
   # Edit .env with your Discord bot tokens, channel IDs, etc.
   

3. Create Discord bots:

   • Go to Discord Developer Portal
   • Create one application per agent
   • Enable: MESSAGE_CONTENT intent, SERVER MEMBERS intent
   • Generate bot tokens → paste into .env
   • Invite bots to your server with appropriate permissions

4. Set up memory directory:

   mkdir -p ~/Documents/MAGI_Memory/{session_notes,journals,self_persona,inbox/images}
   cd ~/Documents/MAGI_Memory && git init
   

5. Create Discord channels:

   • One channel per agent (their "home" channel — agents listen without @mention)
   • Copy channel IDs → paste into .env

6. Make run scripts executable:

   chmod +x run-*.sh hooks/*.sh
   

7. Launch:

   # Launch all agents
   ./run-all.sh
   
   # Or launch individually
   ./run-alpha.sh
   

Project Structure

magi-system/
├── channels/
│   ├── base-channel.mjs      # Core: MCP + Discord hybrid (shared by all agents)
│   ├── agent-alpha.mjs        # Simple agent (config-only)
│   ├── agent-beta.mjs         # Agent with extra tools
│   ├── mj_watcher.mjs         # Midjourney automation (optional)
│   └── package.json
├── hooks/
│   ├── session-start.sh       # Context restoration on fresh start
│   ├── pre-compact.sh         # Discord notification + timestamp before compaction
│   ├── post-compact.sh        # Re-inject context after compaction
│   ├── stop-check.sh          # Block stop if session notes stale
│   ├── diminishing-returns.sh # Warn on consecutive tool failures
│   └── log-compact.sh         # Track compaction frequency
├── personas/
│   ├── examples/              # Example persona templates
│   └── CUSTOMIZATION.md       # How to write effective personas
├── .env.example               # Environment variable template
├── .mcp-alpha.json            # Per-agent MCP config
├── .mcp-beta.json
├── CLAUDE.md                  # Instructions loaded into every Claude Code session
├── run-alpha.sh               # Agent launch script (auto-restart)
├── run-beta.sh
└── run-all.sh                 # Launch all agents

Adding a New Agent

1. Copy an agent channel file:

   cp channels/agent-alpha.mjs channels/agent-myagent.mjs
   

   Edit: agentName, discordTokenEnv, homeChannel, emoji, instructions

2. Create MCP config:

   cp .mcp-alpha.json .mcp-myagent.json
   

   Update the server name and args path.

3. Create run script:

   cp run-alpha.sh run-myagent.sh
   

   Update: MAGI_AGENT, token var, persona path, MCP config path.

4. Create persona:

   cp personas/examples/agent-alpha.md personas/examples/agent-myagent.md
   

   Customize for your agent's role.

5. Add to .env:

   DISCORD_BOT_TOKEN_MYAGENT=your-token
   DISCORD_MYAGENT_HOME_CHANNEL=your-channel-id
   

Hook Configuration

Hooks are shell scripts that run at specific lifecycle events. Configure them in your Claude Code settings (~/.claude/settings.json or project .claude/settings.local.json):

{
  "hooks": {
    "SessionStart": [{ "command": "bash hooks/session-start.sh" }],
    "PreCompact": [
      { "command": "bash hooks/pre-compact.sh" },
      { "command": "bash hooks/log-compact.sh" }
    ],
    "PostCompact": [{ "command": "bash hooks/post-compact.sh" }],
    "Stop": [{ "command": "bash hooks/stop-check.sh" }],
    "PostToolUse": [{ "command": "bash hooks/diminishing-returns.sh" }]
  }
}

How It Works

Message Flow

1. User sends a message in #alpha Discord channel
2. The channel server (MCP + Discord.js bot) receives it
3. Channel server sends an MCP notification to Claude Code
4. Claude Code processes the message with the agent's persona
5. Claude Code calls the reply MCP tool
6. Channel server sends the reply to Discord

Agent-to-Agent (B2B) Communication

Agents can talk to each other by mentioning another agent's bot in their reply:

@BetaBot Can you generate a concept image for this scene?

The mentioned agent's channel server picks it up and delivers it as a B2B message (prefixed with BOT:).

Session Memory

• Session notes — Written every 30 minutes, stored in MAGI_MEMORY_DIR/session_notes/{agent}/
• Journals — Compressed archives of old session notes
• SHARED_MEMORY.md — Shared knowledge base across all agents
• Self-reflection — Agent-specific learning and growth notes

Context Compaction

When Claude Code's context window fills up:

1. pre-compact.sh fires — sends Discord notification, records timestamp
2. Claude Code compresses the conversation
3. post-compact.sh fires — re-injects SHARED_MEMORY, session notes, persona, and pending tasks

Configuration Reference

Env Variable	Required	Description
DISCORD_BOT_TOKEN_{AGENT}	Yes	Discord bot token per agent
DISCORD_SERVER_ID	Yes	Your Discord server ID
DISCORD_DIRECTOR_ID	No	Director's Discord user ID
DISCORD_{AGENT}_HOME_CHANNEL	Yes	Agent's home channel (listens without @mention)
DISCORD_PERMISSION_CHANNEL	No	Channel for permission responses
MAGI_MEMORY_DIR	No	Memory directory (default: ~/Documents/MAGI_Memory)
SESSION_NOTE_INTERVAL_MS	No	Note reminder interval (default: 1800000 = 30min)
DISCORD_USER_TOKEN	No	For MJ button clicks and /imagine (optional)

License

MIT