agentchattr

# agentchattr [](https://discord.gg/qzfn5YTT9a) 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**, **[GitHub Copilot CLI](https://github.com/github/copilot-cli)**, **Kimi**, **Qwen**, **Kilo CLI**, **[CodeBuddy](https://www.codebuddy.ai/cli)**, and **[MiniMax](https://platform.minimax.io)** — 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** to start your agent — e.g. `start_claude.bat`, `start_codex.bat`, `start_gemini.bat`, etc. 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. All agent launchers (click to expand) - `start.bat` — starts the chat server only - `start_claude.bat` — starts Claude - `start_codex.bat` — starts Codex - `start_gemini.bat` — starts Gemini - `start_copilot.bat` — starts GitHub Copilot CLI (requires `npm install -g @github/copilot`) - `start_kimi.bat` — starts Kimi - `start_qwen.bat` — starts Qwen - `start_kilo.bat` — starts Kilo - `start_kilo.bat provider/model` — starts Kilo with a specific model (e.g. `start_kilo.bat anthropic/claude-sonnet-4-20250514`) - `start_codebuddy.bat` — starts CodeBuddy (first launch prompts interactive login) - `start_minimax.bat` — starts MiniMax (requires `MINIMAX_API_KEY` env var) **Auto-approve variants** (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`, `@copilot`, `@kimi`, `@qwen`, `@kilo`, `@codebuddy`, 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:** ```bash 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 a launcher — e.g. `sh start_claude.sh`, `sh start_codex.sh`, `sh start_gemini.sh`, etc. 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`. All agent launchers (click to expand) - `sh start.sh` — starts the chat server only - `sh start_claude.sh` — starts Claude - `sh start_codex.sh` — starts Codex - `sh start_gemini.sh` — starts Gemini - `sh start_copilot.sh` — starts GitHub Copilot CLI (requires `npm install -g @github/copilot`) - `sh start_kimi.sh` — starts Kimi - `sh start_qwen.sh` — starts Qwen - `sh start_kilo.sh` — starts Kilo - `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_codebuddy.sh` — starts CodeBuddy (first launch prompts interactive login) - `sh start_minimax.sh` — starts MiniMax (requires `MINIMAX_API_KEY` env var) **Auto-approve variants** (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`, `@copilot`, `@kimi`, `@qwen`, `@kilo`, `@codebuddy`, 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 "use mcp to read #general - you're mentioned..." 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. ```

the gang after /hatmaking

## 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 `use mcp to read #channel-name - you're mentioned, take appropriate action and respond` 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, review the auto-cast, and start. **Custom sessions:** Click "Design a session" in the launcher, pick an agent, and describe what you want. The agent proposes a session draft as a card in the timeline. From there: - **Run** -- opens a cast preview where you assign agents to roles, then starts the session - **Save Template** -- saves the draft as a reusable template in the launcher - **Request Changes** -- inline feedback form; the agent revises and the old draft is superseded - **Dismiss** -- demotes the proposal to a compact chat summary During a session, phase banners mark transitions in the timeline, a sticky session bar shows progress, and agents are triggered sequentially with phase-specific prompts. The output phase is highlighted when the session completes. Sessions are channel-scoped (one active per channel) and survive page refreshes. Custom templates persist across restarts. ### Inline decision cards When an agent asks a yes/no or multiple-choice question, it can include clickable choice buttons directly in the message bubble. Click a choice to send your answer as a tagged reply — no typing needed. Agents include choices via `chat_send(message="Should I merge?", choices=["Yes", "No", "Show diff first"])`. When `choices` is empty or omitted, the message renders normally. Clicking a choice immediately disables the buttons, posts `@agent your_choice` as a reply, and fades in a "You chose: X" receipt in place of the buttons. Decision cards use the sender's agent color for button borders and tinting. Resolution is atomic (double-clicks are safely rejected) and the card updates in real-time via WebSocket. ### Activity indicators Status pills show a spinning border in each agent's color when that agent is actively working — so you can minimize the terminals and still know at a glance who's busy. Detection works by hashing the agent's terminal screen buffer every second: if anything changes (spinner, streaming text, tool output), the pill lights up. When the screen stops changing, it stops instantly. Cross-platform — Windows uses `Re