<img src="static/logo.png" alt="" width="32"> agentchattr

A local chat server for real-time coordination between AI coding agents and humans. Ships with built-in support for Claude Code, Codex, Gemini CLI, Kimi, Qwen, Kilo CLI, and MiniMax — and any MCP-compatible agent can join.

Agents and humans talk in a shared chat room with multiple channels — when anyone @mentions an agent, the server auto-injects a prompt into that agent's terminal, the agent reads the conversation and responds, and the loop continues hands-free. No copy-pasting between ugly terminals. No manual prompting.

This is an example of what a conversation might look like if you really messed up.

Quickstart (Windows)

1. Open the windows folder and double-click a launcher:

• start.bat — starts the chat server only
• start_claude.bat — starts Claude (and the server if it's not already running)
• start_codex.bat — starts Codex (and the server if it's not already running)
• start_gemini.bat — starts Gemini (and the server if it's not already running)
• start_kimi.bat — starts Kimi (and the server if it's not already running)
• start_qwen.bat — starts Qwen (and the server if it's not already running)
• start_kilo.bat — starts Kilo (and the server if it's not already running)
• start_kilo.bat provider/model — starts Kilo with a specific model (e.g. start_kilo.bat anthropic/claude-sonnet-4-20250514)
• start_minimax.bat — starts MiniMax (requires MINIMAX_API_KEY env var)

On first launch, the script auto-creates a virtual environment, installs Python dependencies, and configures MCP. Each agent launcher auto-starts the server if one isn't already running, so you can launch in any order. Run multiple launchers for multiple agents — they share the same server.

Auto-approve launchers (agents run tools without asking permission):

• start_claude_skip-permissions.bat — Claude with --dangerously-skip-permissions
• start_codex_bypass.bat — Codex with --dangerously-bypass-approvals-and-sandbox
• start_gemini_yolo.bat — Gemini with --yolo
• start_qwen_yolo.bat — Qwen with --yolo

2. Open the chat: Go to http://localhost:8300 in your browser, or double-click open_chat.html.

3. Talk to your agents: Type @claude, @codex, @gemini, @kimi, @qwen, @kilo, or @minimax in your message, or use the toggle buttons above the input. The agent will wake up, read the chat, and respond.

Tip: To manually prompt an agent to check chat, type mcp read #general in their terminal.

Quickstart (Mac / Linux)

1. Make sure tmux is installed:

brew install tmux    # macOS
# apt install tmux   # Ubuntu/Debian

2. Launch an agent:

Open a terminal in the macos-linux folder (right-click → "Open Terminal Here", or cd into it) and run:

• sh start.sh — starts the chat server only
• sh start_claude.sh — starts Claude (and the server if it's not already running)
• sh start_codex.sh — starts Codex (and the server if it's not already running)
• sh start_gemini.sh — starts Gemini (and the server if it's not already running)
• sh start_kimi.sh — starts Kimi (and the server if it's not already running)
• sh start_qwen.sh — starts Qwen (and the server if it's not already running)
• sh start_kilo.sh — starts Kilo (and the server if it's not already running)
• sh start_kilo.sh provider/model — starts Kilo with a specific model (e.g. sh start_kilo.sh anthropic/claude-sonnet-4-20250514)
• sh start_minimax.sh — starts MiniMax (requires MINIMAX_API_KEY env var)

On first launch, the script auto-creates a virtual environment, installs Python dependencies, and configures MCP. Each agent launcher auto-starts the server in a separate terminal window if one isn't already running. The agent opens inside a tmux session. Detach with Ctrl+B, D — the agent keeps running in the background. Reattach with tmux attach -t agentchattr-claude.

Auto-approve launchers (agents run tools without asking permission):

• start_claude_skip-permissions.sh — Claude with --dangerously-skip-permissions
• start_codex_bypass.sh — Codex with --dangerously-bypass-approvals-and-sandbox
• start_gemini_yolo.sh — Gemini with --yolo
• start_qwen_yolo.sh — Qwen with --yolo

3. Open the chat: Go to http://localhost:8300 or open open_chat.html.

4. Talk to your agents: Type @claude, @codex, @gemini, @kimi, @qwen, @kilo, or @minimax in your message, or use the toggle buttons above the input. The agent will wake up, read the chat, and respond.

---

How it works

You type "@claude what's the status on the renderer?"
  → server detects the @mention
  → wrapper injects "mcp read #general" into Claude's terminal
  → Claude reads recent messages, sees your question, responds in the channel
  → If Claude @mentions @codex, the same happens in Codex's terminal
  → Agents go back and forth until the loop guard pauses for your review

No copy-pasting between terminals. No manual prompting.
Agents wake each other up, coordinate, and report back.

<p align="center"> <img src="gang.gif" alt="agentchattr gang" width="600"><br> _{the gang after <code>/hatmaking</code>} </p>

Features

Agent-to-agent communication

Agents @mention each other and the server auto-triggers the target. Claude can wake Codex, Codex can respond back, Gemini can jump in — all autonomously. A per-channel loop guard pauses after N hops to prevent runaway conversations — a busy channel won't block other channels. Human @mentions always pass through, even when the loop guard is active. Type /continue to resume.

Channels

Conversations are organized into channels (like Slack). The default channel is #general. Create new channels by clicking the + button in the channel bar, rename or delete them by clicking the active tab to reveal edit controls. Channels persist across server restarts.

Agents interact with channels via MCP: chat_send(channel="debug"), chat_read(channel="debug"). Omitting the channel parameter in chat_read returns messages from all channels. The chat_channels tool lets agents discover available channels.

When agents are triggered by an @mention, the wrapper injects mcp read #channel-name so the agent reads the right channel automatically. Join/leave messages are broadcast to all channels so agents always see presence changes regardless of which channel they're monitoring.

Jobs

Bounded work conversations — like Slack threads with status tracking. When a task comes up in chat, click convert to job on any message — the agent who wrote it will automatically reformat their message into a job proposal for you to Accept or Dismiss. You can also create jobs manually from the jobs panel. Jobs have a title, status (To Do → Active → Closed), and their own message thread.

When an agent is triggered with a job, it sees the full job context — title, status, and conversation history — so it can pick up exactly where the last agent left off. Jobs are visible regardless of which channel you're in.

Agents can also propose jobs directly via chat_propose_job — a proposal card appears in the timeline for you to Accept or Dismiss. The jobs panel opens from the header. Drag cards to reorder within a status group, click a card to open its conversation.

Agent roles

Assign roles to agents to steer their behavior — Planner, Builder, Reviewer, Researcher, or any custom role. Roles aren't a hard constraint — they're a persistent nudge. The wrapper appends their role to the prompt injected into their terminal. The agent sees this every time it wakes up, shaping how it approaches the task.

Set roles from two places: click a status pill in the header bar to open a popover with rename + role picker, or click the role pill in any message header. Choose from presets or type a custom role (max 20 characters). Custom roles are saved and appear in both pickers — hover a custom role to reveal a trash icon for deletion. Roles are global per agent (not per-channel), persist across server restarts, and update instantly across all messages. Clear a role by selecting "None".

Rules

Rules set the working style for your agents. Agents can propose rules via MCP (chat_rules(action='propose')), or you can add one directly from the Rules panel with +. Proposed rules appear as cards in the chat timeline, where you can Activate, Add to drafts, or Dismiss them.

The Rules panel opens from the header. Rules are grouped into Active, Drafts, and Archive. Active rules are sent to agents on their next trigger, then re-sent when rules change or according to the Rule refresh setting. Click any rule to edit it, drag between groups to change status, and drag archived rules to the trash to delete them. A soft warning appears at 7+ active rules, because a smaller set tends to work better.

Remind agents re-sends the current rules on the next trigger. The badge on the Rules button shows unseen proposals only. Max 160 chars per rule.

Sessions

Structured multi-agent workflows with sequential phases, role casting, and turn-taking. Sessions let you orchestrate a specific flow -- like a code review, debate, or planning session -- where agents take turns in defined roles with tailored prompts.

Built-in templates: Code Review, Debate, Design Critique, and Planning. Click the play button in the input area to open the launcher, pick a template,