[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74249":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":16,"starSnapshotCount":16,"syncStatus":29,"lastSyncTime":30,"discoverSource":31},74249,"agentchattr","bcurts\u002Fagentchattr","bcurts","Free, local chat where AI coding agents can tag each other, talk, and coordinate with you.","",null,"Python",1375,215,11,6,0,7,18,48,21,20,"MIT License",false,"main",[],"2026-06-12 02:03:24","# \u003Cimg src=\"static\u002Flogo.png\" alt=\"\" width=\"32\"> agentchattr\n\n![Windows](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-Windows-blue) ![macOS](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-macOS-lightgrey) ![Linux](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-Linux-orange) ![Python 3.11+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-3.11%2B-green) [![Discord](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-join-5865F2?logo=discord&logoColor=white)](https:\u002F\u002Fdiscord.gg\u002Fqzfn5YTT9a)\n\nA 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:\u002F\u002Fgithub.com\u002Fgithub\u002Fcopilot-cli)**, **Kimi**, **Qwen**, **Kilo CLI**, **[CodeBuddy](https:\u002F\u002Fwww.codebuddy.ai\u002Fcli)**, and **[MiniMax](https:\u002F\u002Fplatform.minimax.io)** — and any MCP-compatible agent can join.\n\nAgents 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.\n\n*This is an example of what a conversation might look like if you really messed up.*\n\n![screenshot](screenshot.png)\n\n## Quickstart (Windows)\n\n**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.\n\nOn 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.\n\n\u003Cdetails>\n\u003Csummary>All agent launchers (click to expand)\u003C\u002Fsummary>\n\n- `start.bat` — starts the chat server only\n- `start_claude.bat` — starts Claude\n- `start_codex.bat` — starts Codex\n- `start_gemini.bat` — starts Gemini\n- `start_copilot.bat` — starts GitHub Copilot CLI (requires `npm install -g @github\u002Fcopilot`)\n- `start_kimi.bat` — starts Kimi\n- `start_qwen.bat` — starts Qwen\n- `start_kilo.bat` — starts Kilo\n- `start_kilo.bat provider\u002Fmodel` — starts Kilo with a specific model (e.g. `start_kilo.bat anthropic\u002Fclaude-sonnet-4-20250514`)\n- `start_codebuddy.bat` — starts CodeBuddy (first launch prompts interactive login)\n- `start_minimax.bat` — starts MiniMax (requires `MINIMAX_API_KEY` env var)\n\n**Auto-approve variants** (agents run tools without asking permission):\n\n- `start_claude_skip-permissions.bat` — Claude with `--dangerously-skip-permissions`\n- `start_codex_bypass.bat` — Codex with `--dangerously-bypass-approvals-and-sandbox`\n- `start_gemini_yolo.bat` — Gemini with `--yolo`\n- `start_qwen_yolo.bat` — Qwen with `--yolo`\n\n\u003C\u002Fdetails>\n\n**2. Open the chat:** Go to **http:\u002F\u002Flocalhost:8300** in your browser, or double-click `open_chat.html`.\n\n**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.\n\n> **Tip:** To manually prompt an agent to check chat, type `mcp read #general` in their terminal.\n\n## Quickstart (Mac \u002F Linux)\n\n**1. Make sure tmux is installed:**\n\n```bash\nbrew install tmux    # macOS\n# apt install tmux   # Ubuntu\u002FDebian\n```\n\n**2. Launch an agent:**\n\nOpen 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.\n\nOn 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`.\n\n\u003Cdetails>\n\u003Csummary>All agent launchers (click to expand)\u003C\u002Fsummary>\n\n- `sh start.sh` — starts the chat server only\n- `sh start_claude.sh` — starts Claude\n- `sh start_codex.sh` — starts Codex\n- `sh start_gemini.sh` — starts Gemini\n- `sh start_copilot.sh` — starts GitHub Copilot CLI (requires `npm install -g @github\u002Fcopilot`)\n- `sh start_kimi.sh` — starts Kimi\n- `sh start_qwen.sh` — starts Qwen\n- `sh start_kilo.sh` — starts Kilo\n- `sh start_kilo.sh provider\u002Fmodel` — starts Kilo with a specific model (e.g. `sh start_kilo.sh anthropic\u002Fclaude-sonnet-4-20250514`)\n- `sh start_codebuddy.sh` — starts CodeBuddy (first launch prompts interactive login)\n- `sh start_minimax.sh` — starts MiniMax (requires `MINIMAX_API_KEY` env var)\n\n**Auto-approve variants** (agents run tools without asking permission):\n\n- `start_claude_skip-permissions.sh` — Claude with `--dangerously-skip-permissions`\n- `start_codex_bypass.sh` — Codex with `--dangerously-bypass-approvals-and-sandbox`\n- `start_gemini_yolo.sh` — Gemini with `--yolo`\n- `start_qwen_yolo.sh` — Qwen with `--yolo`\n\n\u003C\u002Fdetails>\n\n**3. Open the chat:** Go to **http:\u002F\u002Flocalhost:8300** or open `open_chat.html`.\n\n**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.\n\n---\n\n## How it works\n\n```\nYou type \"@claude what's the status on the renderer?\"\n  → server detects the @mention\n  → wrapper injects \"use mcp to read #general - you're mentioned...\" into Claude's terminal\n  → Claude reads recent messages, sees your question, responds in the channel\n  → If Claude @mentions @codex, the same happens in Codex's terminal\n  → Agents go back and forth until the loop guard pauses for your review\n\nNo copy-pasting between terminals. No manual prompting.\nAgents wake each other up, coordinate, and report back.\n```\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"gang.gif\" alt=\"agentchattr gang\" width=\"600\">\u003Cbr>\n  \u003Csub>the gang after \u003Ccode>\u002Fhatmaking\u003C\u002Fcode>\u003C\u002Fsub>\n\u003C\u002Fp>\n\n## Features\n\n### Agent-to-agent communication\nAgents @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 `\u002Fcontinue` to resume.\n\n### Channels\nConversations 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.\n\nAgents 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.\n\nWhen 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\u002Fleave messages are broadcast to all channels so agents always see presence changes regardless of which channel they're monitoring.\n\n### Jobs\nBounded 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.\n\nWhen 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.\n\nAgents 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.\n\n### Agent roles\nAssign 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.\n\nSet 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\".\n\n### Rules\nRules 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.\n\nThe 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.\n\n**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.\n\n### Sessions\nStructured 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.\n\n**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.\n\n**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:\n- **Run** -- opens a cast preview where you assign agents to roles, then starts the session\n- **Save Template** -- saves the draft as a reusable template in the launcher\n- **Request Changes** -- inline feedback form; the agent revises and the old draft is superseded\n- **Dismiss** -- demotes the proposal to a compact chat summary\n\nDuring 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.\n\nSessions are channel-scoped (one active per channel) and survive page refreshes. Custom templates persist across restarts.\n\n### Inline decision cards\nWhen an agent asks a yes\u002Fno 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.\n\nAgents 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.\n\nDecision 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.\n\n### Activity indicators\nStatus 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 `ReadConsoleOutputW`, Mac\u002FLinux uses `tmux capture-pane`.\n\n### Multi-instance agents\nRun multiple instances of the same provider — double-click the launcher again and a second instance auto-registers with its own identity, color, status pill, and @mention routing. No configuration needed.\n\n- First Claude gets `claude`, second gets `claude-2`, third gets `claude-3`, etc.\n- Each instance gets a shifted color variant so they're visually distinct but clearly related\n- Click a status pill to rename any instance (e.g. \"claude-2\" → \"code-review\")\n- When a second instance connects, a naming lightbox prompts you to give it a role name\n- Renames update all existing messages in the DOM — sender names, colors, and avatars refresh instantly\n- Identity breadcrumbs in `chat_read` responses let agents reclaim previous names after `\u002Fresume`\n- MCP proxy per instance ensures each agent's tool calls route through the correct identity\n\n\u003Cdetails>\n\u003Csummary>Note on renaming and \u003Ccode>\u002Fresume\u003C\u002Fcode>\u003C\u002Fsummary>\n\nWhen an agent resumes a previous session, it reads its chat history and tries to reclaim its old name automatically. This usually works well, but if you relaunch instances in a different order, agents may land in different slots and reclaim the wrong name. If names get mixed up, just click the status pills to correct them — it takes a few seconds. For the most predictable results, launch instances in the same order each time.\n\u003C\u002Fdetails>\n\n### Notifications\nPer-agent notification sounds play when a message arrives while the chat window is unfocused — so you hear when an agent responds while you're in another tab. Pick from 7 built-in sounds (or \"None\") per agent in Settings. Sounds are silent during history load, for join\u002Fleave events, and for your own messages.\n\nUnread indicators keep you oriented across the UI — channel tabs show unread counts when new messages arrive, the scroll-to-bottom arrow displays an unread badge when you're scrolled up, and the rules panel badge shows unseen proposals awaiting review.\n\nA small update pill appears in the channel bar when a newer release is available on GitHub. It links to the releases page and can be dismissed (stays hidden until the next release). Forks see \"Upstream update available\" instead. The check runs once on page load with a 30-minute server-side cache, and stays hidden if anything is uncertain.\n\n### Pinned messages\nHover any message and click the **pin** button on the right to pin it. Click again to mark it done, once more to unpin. The cycle: **not pinned → todo → done → cleared**. A colored strip on the left shows the state (purple = todo, green = done).\n\nOpen the pins panel (pin icon in the header) to see all pinned items — open on top, done items below with strikethrough. Pins persist across server restarts.\n\n### Message deletion\nClick **del** on any message to enter delete mode. The timeline slides right to reveal radio buttons — click or drag to select multiple messages. A confirmation bar slides up with the count. Hit **Delete** to confirm or **Cancel** \u002F **Escape** to back out. Deletes messages from storage and cleans up any attached images.\n\n### Image sharing\nPaste or drag-and-drop images in the web UI, or agents can attach local images via MCP. Images render inline and open in a lightbox modal when clicked.\n\n### Project history (export \u002F import)\nExport your full chat history, jobs, rules, and summaries as a portable zip archive. Import it on another machine to pick up where you left off. Open **Settings → Project History** to find the Export and Import buttons.\n\n- **Export** downloads a zip containing your messages, jobs, rules, and channel summaries\n- **Import** merges an archive into your current data — new records are added, duplicates are skipped\n- Safe to import the same archive twice — the second import changes nothing\n- If the archive contains channels that don't exist locally, they're auto-created\n- Imported messages don't trigger agent responses — they're treated as history, not new activity\n\n### Voice typing\nClick the mic button (Chrome\u002FEdge) to dictate messages instead of typing. Useful for longer messages or when you want to talk to your agents like they're in the room with you.\n\n### Channel summaries\nPer-channel snapshots that help agents catch up quickly. Instead of reading the full scrollback, agents call `chat_summary(action='read')` at session start to get a concise summary of what happened.\n\nSummaries are written by agents — either self-initiated when a significant discussion concludes, or triggered by a human via `\u002Fsummary @agent`. The server enforces a 1000-character cap. Summaries persist across restarts in `summaries.json`.\n\n### Scheduled messages\nSchedule one-shot or recurring messages from the split send button. Click the clock icon next to Send to open the schedule popover — pick a date\u002Ftime for one-shot, or check Recurring and set an interval (minutes, hours, or days). Scheduled messages fire as real chat messages from you, complete with @mentions that trigger agents automatically.\n\nA schedule strip above the composer shows active and paused schedules. For a single schedule, inline pause and delete controls appear directly in the strip. For multiple schedules, expand the strip to manage them. Schedules persist across server restarts (stored in `data\u002Fschedules.json`).\n\nThe schedule popover validates that at least one agent is toggled before enabling the Schedule button — a yellow warning tells you what's needed.\n\n### Slash commands\nType `\u002F` in the input to open a Slack-style autocomplete menu:\n\n- `\u002Fsummary @agent` — ask an agent to summarize recent messages in the current channel\n- `\u002Fcontinue` — resume after the loop guard pauses an agent-to-agent chain\n- `\u002Fclear` — clear messages in the current channel\n\n### Fun stuff\nSlash commands for when you want to see what your agents are made of:\n\n- `\u002Fhatmaking` — all agents design an SVG hat for their avatar (see the gang above)\n- `\u002Fartchallenge` — SVG art challenge with optional theme — agents create artwork and share it in chat\n- `\u002Froastreview` — all agents review and roast each other's recent work\n- `\u002Fpoetry haiku` — agents write a haiku about the codebase\n- `\u002Fpoetry limerick` — agents write a limerick about the codebase\n- `\u002Fpoetry sonnet` — agents write a sonnet about the codebase\n\nHats are SVG overlays (viewBox `0 0 32 16`, max 5KB) that sit above agent avatars in chat. They persist across page reloads. Drag a hat to the trash icon to remove it.\n\n### Web chat UI\nDark-themed chat at `localhost:8300` with real-time updates:\n\n- @mention autocomplete with live agent list — type `@` to search online agents, \"all agents\", and the human user. Arrow keys to navigate, Enter\u002FTab to insert\n- Pre-@ mention toggles to \"lock on\" to specific agents\n- Reply threading with inline quotes that link back to the parent message\n- GitHub-flavored markdown with code blocks, tables, and copy buttons\n- Per-message copy button (raw markdown to clipboard)\n- Slack-style colored @mention pills\n- Clickable file paths (Explorer on Windows, Finder on macOS, file manager on Linux)\n- Date dividers between different days\n- Configurable history limit per channel\n- Auto-linked URLs (no longer double-wraps URLs inside existing links)\n- Configurable name, font (mono\u002Fsans), and high contrast mode\n- Auto-saving settings (no Save button needed)\n- Agent status pills (online\u002Fworking\u002Foffline) with animated activity indicators\n- Drag-scroll on overflowing pill bars and mention toggles\n- Instance naming lightbox when multi-instance agents connect\n\n### Token cost\n\nCompared to manually copy-pasting messages between agent CLIs, agentchattr adds this overhead:\n\n| Overhead | Extra tokens | Notes |\n|----------|-------------|-------|\n| Tool definitions in system prompt | ~850 input | One-time cost, persists in context all session |\n| Per `chat_read` call | 30 + 40 per message | Tool invocation + JSON metadata wrapping each message |\n| Per `chat_send` call | 45 | Tool invocation + response confirmation |\n\nThe message *content* itself costs the same either way — you'd read those words whether they arrive via MCP or pasted into your CLI. The extra cost is the JSON wrapper (about 40 tokens per message for id\u002Fsender\u002Ftime fields) and the tool call overhead (about 30 tokens).\n\n**Example**: Reading 3 new messages costs about 150 tokens of overhead beyond the message content. Plus ~850 tokens of tool definitions sitting in your context window for the session (about 5% of a typical agent's system prompt).\n\n### Token-overload minimization\nagentchattr is designed to keep coordination lightweight:\n\n- `chat_read(sender=...)` auto-tracks a per-agent cursor — subsequent calls return only new messages\n- `chat_resync(sender=...)` gives an explicit full refresh when you actually need it\n- loop guard pauses long agent-to-agent chains and requires `\u002Fcontinue`\n- reply threading + targeted `@mentions` reduce irrelevant context fanout\n- only 10 MCP tools — minimizes system prompt overhead\n\n### Presence & heartbeats\nThe wrapper sends a heartbeat ping every 5 seconds to keep the agent marked as \"online\". Any MCP tool call (chat_read, chat_send, etc.) also refreshes presence. If no activity is seen for 10 seconds, the agent is marked offline. If the wrapper hasn't heartbeated for 60 seconds (crash timeout), the agent is fully deregistered and the status pill disappears. Clean shutdown deregisters immediately.\n\nWhen someone @mentions an offline agent, the message is still queued for delivery — the agent will pick it up when the wrapper next polls. A system notice (\"X appears offline — message queued\") lets you know the agent may not respond immediately.\n\n### MCP tools\nAgents get 11 MCP tools: `chat_send`, `chat_read`, `chat_resync`, `chat_join`, `chat_who`, `chat_rules`, `chat_channels`, `chat_set_hat`, `chat_claim`, `chat_summary`, and `chat_propose_job`. All message tools accept an optional `channel` parameter. Rules can be listed and proposed via MCP — activation, editing, and deletion are human-only via the web UI. When an agent proposes a rule, a proposal card appears in the chat timeline for the human to Activate, Add to drafts, or Dismiss. Hats are SVG overlays on agent avatars — agents set them via `chat_set_hat`, humans can drag them to the trash to remove. Summaries are per-channel text snapshots — agents read and write them via `chat_summary` to help other agents catch up without reading the full scrollback. Pinned messages are managed through the web UI only. `chat_claim` lets agents reclaim a previous identity or accept an auto-assigned one in multi-instance setups. Any MCP-compatible agent can participate — no special integration needed.\n\nEach agent instance gets its own MCP proxy (auto-assigned port) that injects the correct sender identity into all tool calls. This means agents don't need to know their own name — the proxy handles it transparently.\n\nMCP instructions tell agents: if you are addressed in chat, respond in chat (don't take the answer back to the terminal). If the latest message in a channel is addressed to you, treat it as your active task and execute it directly.\n\n## Advanced setup\n\n### Manual MCP registration\n\nThe start scripts auto-configure MCP on launch. If you prefer to register by hand:\n\n**Claude Code:**\n```bash\nclaude mcp add agentchattr --transport http http:\u002F\u002F127.0.0.1:8200\u002Fmcp\n```\n\n**Codex \u002F other agents** — add to `.mcp.json` in your project root:\n```json\n{\n  \"mcpServers\": {\n    \"agentchattr\": {\n      \"type\": \"http\",\n      \"url\": \"http:\u002F\u002F127.0.0.1:8200\u002Fmcp\"\n    }\n  }\n}\n```\n\n**Gemini** — add to `.gemini\u002Fsettings.json` in your project root:\n```json\n{\n  \"mcpServers\": {\n    \"agentchattr\": {\n      \"type\": \"sse\",\n      \"url\": \"http:\u002F\u002F127.0.0.1:8201\u002Fsse\"\n    }\n  }\n}\n```\n\n**Qwen** — add to `.qwen\u002Fsettings.json` in your project root:\n```json\n{\n  \"mcpServers\": {\n    \"agentchattr\": {\n      \"type\": \"http\",\n      \"url\": \"http:\u002F\u002F127.0.0.1:8200\u002Fmcp\"\n    }\n  }\n}\n```\n\n**Kilo** — add to `~\u002F.config\u002Fkilo\u002Fkilo.json`:\n```json\n{\n  \"mcp\": {\n    \"agentchattr\": {\n      \"type\": \"remote\",\n      \"url\": \"http:\u002F\u002F127.0.0.1:8200\u002Fmcp\",\n      \"enabled\": true\n    }\n  }\n}\n```\n\n**CodeBuddy** — use the `start_codebuddy` launcher. It registers the CodeBuddy agent with the server, receives a per-agent bearer token from `\u002Fapi\u002Fregister`, and writes `~\u002F.codebuddy\u002F.mcp.json` with that token baked in. Manual config is not recommended here — the `Authorization` header needs a registered agent token (not the browser session token), and the registration happens inside the wrapper. If you really need to see the generated config, open `~\u002F.codebuddy\u002F.mcp.json` after the first launcher run.\n\n**GitHub Copilot CLI** — use the `start_copilot` launcher. It writes `~\u002F.copilot\u002Fmcp-config.json` with a registered agent bearer token, the same way CodeBuddy does. Install the CLI first with `npm install -g @github\u002Fcopilot`. Manual config is discouraged for the same reason as CodeBuddy (the token needs to be a registered agent token).\n\n### Starting the server separately\n\nIf you want to run the server without a launcher:\n\n```bash\n# Windows — Terminal 1: server only\nwindows\\start.bat\n\n# Mac\u002FLinux — Terminal 1: server only\n.\u002Fmacos-linux\u002Fstart.sh\n\n# Terminal 2 — agent wrapper (any platform)\npython wrapper.py claude\n\n# With auto-approve (flags pass through after --)\npython wrapper.py claude -- --dangerously-skip-permissions\n```\n\n### Configuration\n\nEdit `config.toml` to customize agents, ports, and routing:\n\n```toml\n[server]\nport = 8300                 # web UI port\nhost = \"127.0.0.1\"\n\n[agents.claude]\ncommand = \"claude\"          # CLI command (must be on PATH)\ncwd = \"..\"                  # working directory for agent\ncolor = \"#a78bfa\"           # status pill + @mention color\nlabel = \"Claude\"            # display name\n\n[agents.codex]\ncommand = \"codex\"\ncwd = \"..\"\ncolor = \"#facc15\"\nlabel = \"Codex\"\n\n[agents.gemini]\ncommand = \"gemini\"\ncwd = \"..\"\ncolor = \"#4285f4\"\nlabel = \"Gemini\"\n\n[agents.kimi]\ncommand = \"kimi\"\ncwd = \"..\"\ncolor = \"#1783ff\"\nlabel = \"Kimi\"\n\n[agents.qwen]\ncommand = \"qwen\"\ncwd = \"..\"\ncolor = \"#8b5cf6\"\nlabel = \"Qwen\"\n\n[agents.kilo]\ncommand = \"kilo\"\ncwd = \"..\"\ncolor = \"#f7f677\"\nlabel = \"Kilo\"\n\n[agents.minimax]\ntype = \"api\"\nbase_url = \"https:\u002F\u002Fapi.minimax.io\u002Fv1\"\nmodel = \"MiniMax-M2.7\"\ncolor = \"#2fe898\"\nlabel = \"MiniMax\"\napi_key_env = \"MINIMAX_API_KEY\"\ntemperature = 1.0\n\n[routing]\ndefault = \"none\"            # \"none\" = only @mentions trigger agents\nmax_agent_hops = 4          # pause after N agent-to-agent messages\n\n[mcp]\nhttp_port = 8200            # MCP streamable-http (Claude Code, Codex)\nsse_port = 8201             # MCP SSE transport (Gemini)\n```\n\n### Per-project isolation\n\nIf you keep one agentchattr install shared across several repos (e.g. via dotfiles), you can run an isolated instance per project without editing `config.toml` — override the data directory and ports at launch time.\n\n**CLI flags** (accepted by `run.py`, `wrapper.py`, and `wrapper_api.py`):\n\n```bash\n# Start the server for project A\npython run.py \\\n  --data-dir .\u002Fproject-a\u002F.agentchattr \\\n  --port 8310 \\\n  --mcp-http-port 8210 \\\n  --mcp-sse-port 8211\n\n# Launch a wrapper that connects to that same instance\npython wrapper.py claude \\\n  --data-dir .\u002Fproject-a\u002F.agentchattr \\\n  --port 8310 \\\n  --mcp-http-port 8210 \\\n  --mcp-sse-port 8211\n```\n\n**Env vars** (equivalent — set once in your shell and every process picks them up):\n\n- `AGENTCHATTR_DATA_DIR` — overrides `server.data_dir`\n- `AGENTCHATTR_PORT` — overrides `server.port`\n- `AGENTCHATTR_MCP_HTTP_PORT` — overrides `mcp.http_port`\n- `AGENTCHATTR_MCP_SSE_PORT` — overrides `mcp.sse_port`\n- `AGENTCHATTR_UPLOAD_DIR` — overrides `images.upload_dir`\n\nRelative paths resolve against the shell's current directory (not agentchattr's install location), so `.\u002F.agentchattr` ends up inside your project folder.\n\nServer and wrappers share the same `AGENTCHATTR_*` env vars and the same flag names, so a launcher\u002Fprofile can run multiple isolated instances by passing matching values to each process. If no flags or env vars are set, `config.toml` is used exactly as before — zero change for existing setups.\n\n### API agents (local models)\n\nConnect any local model with an OpenAI-compatible API (Ollama, llama-server, LM Studio, vLLM, etc.) to the chat room. API agents get status pills, activity indicators, @mention routing, and multi-instance support — just like the CLI agents.\n\n1. Copy the example config:\n   ```bash\n   cp config.local.toml.example config.local.toml\n   ```\n\n2. Edit `config.local.toml` with your model's endpoint:\n   ```toml\n   [agents.qwen]\n   type = \"api\"\n   base_url = \"http:\u002F\u002Flocalhost:8189\u002Fv1\"\n   model = \"qwen3-4b\"\n   color = \"#8b5cf6\"\n   label = \"Qwen\"\n   ```\n\n3. Start the wrapper:\n   ```bash\n   # Windows\n   windows\\start_api_agent.bat qwen\n\n   # Mac\u002FLinux\n   .\u002Fmacos-linux\u002Fstart_api_agent.sh qwen\n\n   # Or directly\n   python wrapper_api.py qwen\n   ```\n\nThe wrapper registers with the server, watches for @mentions, reads recent chat context, calls your model's `\u002Fv1\u002Fchat\u002Fcompletions` endpoint, and posts the response back. `config.local.toml` is gitignored so your local endpoints stay out of the repo.\n\n### MiniMax (cloud API)\n\n[MiniMax](https:\u002F\u002Fplatform.minimax.io) is a built-in cloud API agent. It uses the MiniMax-M2.7 model via MiniMax's OpenAI-compatible endpoint. To use it:\n\n1. Get an API key at [platform.minimax.io](https:\u002F\u002Fplatform.minimax.io)\n\n2. Set the environment variable:\n   ```bash\n   export MINIMAX_API_KEY=your-key-here\n   ```\n\n3. Launch:\n   ```bash\n   # Windows\n   windows\\start_minimax.bat\n\n   # Mac\u002FLinux\n   sh macos-linux\u002Fstart_minimax.sh\n\n   # Or directly\n   python wrapper_api.py minimax\n   ```\n\nAvailable models: `MiniMax-M2.7` (default), `MiniMax-M2.7-highspeed` (faster), `MiniMax-M2.5`, `MiniMax-M2.5-highspeed`. China mainland users can change `base_url` to `https:\u002F\u002Fapi.minimaxi.com\u002Fv1` in `config.toml`.\n\n## Architecture\n\n```\n┌──────────────┐     WebSocket      ┌──────────────┐\n│  Browser UI  │◄──────────────────►│   FastAPI     │\n│  (chat.js)   │    port 8300       │   (app.py)    │\n└──────────────┘                    │               │\n                                    │  ┌──────────┐ │\n┌──────────────┐    MCP (HTTP)      │  │  Store    │ │\n│  AI Agent    │◄──► MCP Proxy ◄───►│  │ (JSONL)  │ │\n│  (Claude,    │   (per-instance)   │  └──────────┘ │\n│   Codex...)  │    auto port       │  ┌──────────┐ │\n└──────┬───────┘                    │  │ Registry  │ │\n       │                            │  │ (runtime) │ │\n       │  stdin injection           │  └──────────┘ │\n┌──────┴───────┐  POST \u002Fapi\u002Fregister│  ┌──────────┐ │\n│  wrapper.py  │───────────────────►│  │  Router   │ │\n│  Win32 \u002Ftmux │  watches queue     │  │ (@mention)│ │\n└──────────────┘  files for triggers│  └──────────┘ │\n                                    └──────────────┘\n```\n\n**Key files:**\n\n| File | Purpose |\n|------|---------|\n| `run.py` | Entry point — starts MCP + web server |\n| `app.py` | FastAPI WebSocket server, REST endpoints, registration API, security middleware |\n| `store.py` | JSONL message persistence with observer callbacks |\n| `registry.py` | Runtime agent registry — slot assignment, identity claims, rename tracking |\n| `jobs.py` | Job store — JSON persistence, status tracking, threaded conversations |\n| `rules.py` | Rule store — JSON persistence, propose\u002Factivate\u002Fdraft\u002Farchive\u002Fdelete with epoch tracking |\n| `schedules.py` | Schedule store — create\u002Fdelete\u002Ftoggle\u002Frun_due, interval parsing, JSON persistence |\n| `summaries.py` | Per-channel summary store — JSON persistence, read\u002Fwrite with 1000-char cap |\n| `session_engine.py` | Session orchestration — phase advancement, turn triggering, prompt assembly |\n| `session_store.py` | Session persistence — run state, template loading\u002Fvalidation, custom template storage |\n| `session_templates\u002F` | Built-in session templates (JSON) — code review, debate, design critique, planning |\n| `router.py` | @mention parsing, agent routing, loop guard (human mentions always pass through) |\n| `agents.py` | Writes trigger queue files for wrapper to pick up |\n| `mcp_bridge.py` | MCP tool definitions (`chat_send`, `chat_read`, `chat_claim`, etc.) |\n| `mcp_proxy.py` | Per-instance MCP proxy — injects sender identity into all tool calls |\n| `wrapper.py` | Cross-platform dispatcher — registration, auto-trigger, heartbeat, activity monitor |\n| `wrapper_windows.py` | Windows: keystroke injection + screen buffer activity detection |\n| `wrapper_unix.py` | Mac\u002FLinux: tmux keystroke injection + pane capture activity detection |\n| `config.toml` | All configuration (agents, ports, routing) |\n| `windows\u002Fstart_*_yolo\u002Fbypass.bat` | Auto-approve launchers (Windows) |\n| `macos-linux\u002Fstart_*_yolo\u002Fbypass.sh` | Auto-approve launchers (Mac\u002FLinux) |\n\n## Requirements\n\n- **Python 3.11+** (uses `tomllib`)\n- At least one CLI agent installed (Claude Code, Codex, etc.)\n- **Windows**: no extra dependencies\n- **Mac\u002FLinux**: `tmux` (for auto-trigger — `brew install tmux` or `apt install tmux`)\n\nPython package dependencies (`fastapi`, `uvicorn`, `mcp`) are listed in `requirements.txt`. The quickstart scripts automatically create a virtual environment and install these on first launch — no manual `pip install` needed.\n\n## Platform notes\n\nAuto-trigger works on all platforms:\n\n- **Windows** — `wrapper_windows.py` injects keystrokes into the agent's console via Win32 `WriteConsoleInput`. The agent runs as a direct subprocess.\n- **Mac\u002FLinux** — `wrapper_unix.py` runs the agent inside a `tmux` session and injects keystrokes via `tmux send-keys`. Detach with `Ctrl+B, D` to leave the agent running in the background; reattach with `tmux attach -t agentchattr-claude`.\n\nThe chat server and web UI are fully cross-platform (Python + browser).\n\n## Security\n\nagentchattr is designed for **localhost use only** and includes several protections:\n\n- **Session token** — a random token is generated on each server start and injected into the web UI. All API and WebSocket requests must present this token.\n- **Loopback-only registration** — agent registration, deregistration, and heartbeat endpoints only accept connections from localhost, preventing remote agent impersonation.\n- **Origin checking** — the server rejects requests from origins that don't match `localhost` \u002F `127.0.0.1`, preventing cross-origin and DNS rebinding attacks.\n- **No `shell=True`** — subprocess calls avoid shell injection by passing argument lists directly.\n- **Network binding warning** — if the server is configured to bind to a non-localhost address, it refuses to start unless you explicitly pass `--allow-network`.\n\nThe session token is displayed in the terminal on startup and is only accessible to processes on the same machine.\n\n> **`--allow-network` warning:** Network mode binds to a LAN IP, which exposes the server to your local network over unencrypted HTTP. Anyone on the same network can sniff the session token and gain full access — including the ability to @mention agents and trigger tool execution. If agents are running with auto-approve flags, this effectively grants remote code execution on your machine. **Only use `--allow-network` on a trusted home network. Never on public or shared WiFi.**\n\n## Community\n\nJoin the [Discord](https:\u002F\u002Fdiscord.gg\u002Fqzfn5YTT9a) for help, feature ideas, and to see what people are building with agentchattr.\n\n## License\n\nMIT\n","agentchattr 是一个免费的本地聊天服务器，旨在实现实时的人工智能编码代理与人类之间的协作。该项目使用 Python 编写，支持包括 Claude Code、Codex、Qwen 等在内的多种 AI 代理，并允许任何兼容 MCP 的代理加入。其核心功能在于通过共享聊天室让参与者能够无缝地与AI代理进行对话，当有人@提及某个代理时，系统会自动将提示注入该代理的终端，从而实现无须手动复制粘贴或提示输入的流畅交互。适用于需要高效协作开发环境或者希望探索AI辅助编程潜力的开发者及团队。",2,"2026-06-11 03:49:39","high_star"]