Content
<p align="center">
<img src="assets/logo.png" alt="Codey — multi-agent workbench for Claude Code, Codex, OpenCode and pi" width="300" />
</p>
# Codey 🚀 — a multi-agent workbench for Claude Code, Codex, OpenCode & pi
[English](README.md) | [中文](README.zh-CN.md)
<p align="center">
<a href="https://github.com/its-ahoh/codey/releases/latest"><img src="https://img.shields.io/github/v/release/its-ahoh/codey?label=download&color=2ea44f" alt="Latest release" /></a>
<img src="https://img.shields.io/badge/platform-macOS-black" alt="Platform: macOS" />
<a href="LICENSE"><img src="https://img.shields.io/github/license/its-ahoh/codey" alt="License: MIT" /></a>
<a href="https://github.com/its-ahoh/codey/stargazers"><img src="https://img.shields.io/github/stars/its-ahoh/codey?style=social" alt="GitHub stars" /></a>
</p>
**A multi-agent workbench for coding agents.** Codey is one place to organize, switch between, and orchestrate Claude Code, OpenCode, Codex, pi (and more) across your projects — give each project its own workspace, build teams of reusable bot roles, run several agents in parallel on the same task to compare, and reach all of it from a native macOS app, chat platforms (Telegram / Discord / iMessage), or system-wide push-to-talk voice.
Think of it less as a chat bridge and more as **the control plane for the coding agents you already use**. It runs entirely on your own machine, using your existing agent CLIs and accounts — no proxy server, no extra subscription.
**Contents:** [Why Codey](#why-codey) · [Download](#download) · [Features](#features) · [Quick Start](#quick-start) · [Configuration](#configuration) · [Teams & flow graphs](#bot-configuration) · [Commands](#commands) · [Voice](#voice-input-macos) · [FAQ](#faq)
<p align="center">
<img src="assets/demo.gif" alt="Codey demo: a scheduled Automation drafts a post and publishes it through the built-in agent-controlled browser, hands-free" width="800" />
</p>
<p align="center"><em>A scheduled Automation researches the news, drafts a post, and publishes it through Codey's built-in agent-controlled browser — hands-free (2.5× speed).</em></p>
## Why Codey
- **One project, the right agent for each job.** Per-workspace defaults plus per-bot overrides — Architect on Opus, Executor on Codex, Reviewer on local OpenCode, etc.
- **Run multiple agents in parallel on the same prompt.** Compare Claude Code vs. Codex vs. OpenCode side by side instead of guessing which one fits.
- **Bot teams instead of single prompts.** Define roles, personalities, tools, and let them run sequentially or be auto-dispatched to the subset that's actually relevant.
- **Use them from anywhere.** Native macOS menu-bar app for daily driving, chat platforms for delegating from your phone, voice input for hands-free dictation into any focused app.
- **Local and yours.** Runs on your machine, talks to your accounts, no proxy server in the middle.
## Download
Grab the latest macOS app from the [Releases page](https://github.com/its-ahoh/codey/releases/latest):
- Apple Silicon: `Codey-<version>-arm64.dmg`
- Intel: `Codey-<version>.dmg`
Builds are currently unsigned — on first launch, right-click the app → **Open** → confirm to bypass Gatekeeper.
## Features
**Agent management**
- **Multiple coding agents**: Claude Code, OpenCode, Codex, [pi](https://pi.dev) (with session resume)
- **Parallel execution**: Run multiple agents on the same prompt simultaneously to compare
- **Per-workspace defaults**: Each project picks its own default agent + model
- **Thinking effort**: One low → max control that maps onto each CLI's own reasoning knob
- **Auto-dispatcher**: Optional built-in dispatcher routes a task to the right subset of a team
**Workspaces & bots**
- **Multi-workspace**: Each workspace has its own working directory, memory, and bots
- **Bot teams**: Define bots with roles, personalities, and tools; execution inherits the chat or Default agent/model
- **Flow graphs**: Draw a team as a graph on a canvas — a judge LLM picks the next edge by its condition, so runs can branch, loop back for revisions, or pause to ask you
- **Memory**: Workspace + user-global memory that bots read on every run and write insights back to
- **Conversation context**: Remembers previous messages within a session
**Interfaces**
- **macOS menu-bar app** with multi-chat tabs, workspace switcher, and inline settings
- **Chat platforms**: Telegram, Discord, iMessage
- **Voice (macOS)**: Push-to-talk dictation into any focused app, plus a spoken back-and-forth conversation mode — on-device WhisperKit (CoreML / ANE), OpenAI-compatible APIs, or streaming realtime
- **Health endpoints**: Built-in health check and metrics
**In the chat window**
- **Live status panel**: The agent's own todo list and what it's working on right now, normalized across all four CLIs
- **File changes**: Every edit in the chat, grouped by file, as git-style diffs
- **Git-aware**: Branch picker, sync status, and optional per-chat git worktree isolation so parallel chats never collide
- **Quick Question**: A read-only side thread that answers questions about the current chat without touching it
- **`@` file mentions, attachments, and themes**: Type `@` to pull in workspace files; paste or drop images and files; pick a color theme
**Skills, automation & web**
- **Skills & playbooks**: Toggle skills per workspace; Codey watches what your runs actually do and crystallizes repeated procedures into reusable playbooks
- **Automations**: Put agents on a schedule — daily posts, recurring checks, cron-style workflows managed from the Mac app
- **Agent-controlled browser**: A built-in secure browser agents can open, read, click, and fill — view-only by default, with every state-changing action gated on your approval
- **External MCP servers**: Plug extra tools into your agents from the Mac app's MCP tab
- **QR pairing**: Link Telegram / iMessage to your gateway by scanning a code
## Quick Start
This is a monorepo with three workspaces: `@codey/core`, `@codey/gateway`, and `codey-mac`.
```bash
# Install dependencies (all workspaces)
npm install
# Build everything
npm run build
# Copy config template
cp gateway.json.example gateway.json
# Configure (optional)
npm run configure
# Start the gateway
npm start
```
To run the macOS app in development:
```bash
npm run dev -w codey-mac # dev with hot reload
npm run build:mac -w codey-mac # produce a DMG in codey-mac/release/
```
## Configuration
Edit `gateway.json`:
```json
{
"gateway": {
"port": 3000,
"defaultAgent": "claude-code",
"defaultModel": "claude-sonnet-4-20250514"
},
"channels": {
"telegram": { "enabled": true, "botToken": "YOUR_TOKEN" },
"discord": { "enabled": false, "botToken": "" },
"imessage": { "enabled": false }
},
"agents": {
"claude-code": { "enabled": true, "provider": "anthropic", "defaultModel": "claude-sonnet-4-20250514" },
"opencode": { "enabled": true, "provider": "openai", "defaultModel": "gpt-4.1" },
"pi": { "enabled": true, "provider": "anthropic", "defaultModel": "claude-sonnet-4-5" },
"codex": { "enabled": true, "provider": "openai", "defaultModel": "gpt-5-codex" }
},
"profiles": [
{
"name": "default",
"anthropic": { "apiKey": "sk-..." },
"openai": { "apiKey": "sk-..." }
}
],
"activeProfile": "default",
"dev": {
"logLevel": "info"
}
}
```
Advisor (auto-dispatch + team routing) settings: `advisor.{agent, model}` (optional).
## Workspace Structure
```
workspaces/
├── default/
│ ├── workspace.json # Workspace config (workingDir + bots)
│ └── bots/
│ ├── architect.md
│ └── executor.md
├── project-a/
│ ├── workspace.json
│ └── bots/
│ └── ...
└── project-b/
├── workspace.json
└── bots/
└── ...
```
User and project memories are stored in Co-memo, separately from workspace files. Project memory is scoped by the project directory path.
Each workspace ties to a project directory via `workspace.json`:
```json
{
"workingDir": "/path/to/project",
"bots": {
"architect": {
"tools": ["file-system", "git", "web-search"]
}
}
}
```
Switching workspaces (`/workspace myproject`) automatically sets the agent's working directory.
## Bot Configuration
Each bot is defined in a markdown file:
```markdown
# Bot: Architect
## Role
Lead architect responsible for project planning...
## Soul
Strategic thinker, focused on scalability...
## Coding Agent
claude-code
## Model
claude-opus-4-20250514
## Tools
file-system, git, web-search
## Relationship
Leads the implementation bots
## Instructions
When prompted, analyze requirements and provide...
```
## Commands
### Bots
| Command | Description |
|---------|-------------|
| `/bots` | List all bots in current workspace |
| `/bot <name> <task>` | Run a specific bot |
| `/team <name> [--all] <task>` | Run a named team (see below) |
**Team dispatch details:**
- `/team <name> [--all] <task>` — Run a named team. Members run sequentially with carry chain.
- Teams default to `dispatch: 'sequential'` (every member runs in order).
- Teams configured with `dispatch: 'auto'` first invoke the built-in Advisor
that selects the relevant subset. Pass `--all` to bypass it for one call.
- Optional `dispatchHint` on each bot's `config.json` improves routing accuracy.
- The Advisor's agent/model is configured under `gateway.json` `advisor.{agent, model}`,
defaulting to the gateway's default agent/model.
- Teams configured with `dispatch: 'roundtable'` run as an **Advisor-moderated roundtable**:
all bots run concurrently as long-lived agent sessions, sharing opinion files in
`chats/<chatId>/discussion/`. An Advisor loop evaluates progress, maintains a summary,
and decides when to ask the user, continue, or terminate.
Optional settings under `roundtable: { maxDurationMs, idleTimeoutMs, advisorPollMs }`.
See [design spec](docs/superpowers/specs/2026-05-24-team-parallel-mode-design.md).
- A sequential (`all`) team can also carry a **flow graph** — `graph: { entry, maxHops, nodes, edges }`.
Nodes are bots (plus `start` / `end`); each edge carries a natural-language condition.
After every bot runs, a judge LLM (the Advisor's agent/model) picks the next edge, so a flow can
branch or loop back to an earlier bot for revision until it reaches `end` or hits `maxHops`.
Bots can pause the flow with `[ASK_USER]`; the run resumes when you reply, on chat or in the Mac app.
Draw one on the drag-and-drop canvas in the Mac app's flow editor.
### Workspaces
| Command | Description |
|---------|-------------|
| `/workspaces` | List all workspaces |
| `/workspace <name>` | Switch to a workspace |
### Agents
| Command | Description |
|---------|-------------|
| `/parallel <prompt>` | Run all agents in parallel |
| `/all <prompt>` | Run all agents in parallel |
| `/agent <name>` | Switch default agent |
### Settings
| Command | Description |
|---------|-------------|
| `/help` | Show help message |
| `/status` | Show gateway status |
| `/clear` | Clear conversation history |
| `/reset` | Start a new conversation |
| `/model <name>` | Show/set model |
## Examples
```bash
# Switch workspace
/workspace myproject
# List bots
/bots
# Run a bot
/bot architect design a REST API
# Run team task
/team build a todo app
# Run all agents in parallel
/parallel create a hello world app
```
## Voice Input (macOS)
System-wide push-to-talk dictation. Hold the configured hotkey (default `Fn`), speak, release — Codey transcribes and pastes into whatever text field is focused, no matter which app you're in.
**Transcription backends:**
- **Local (WhisperKit)** — on-device CoreML / Neural Engine. Models pulled from HuggingFace on first use; default is `large-v3-turbo` quantized (~954 MB). No network, no API key. Pipeline idle-unloads after 30s so RAM/ANE stay free when you're not dictating.
- **API** — any OpenAI-compatible `/audio/transcriptions` endpoint. Just point `apiUrl` / `apiKey` / `apiModel` (e.g. `whisper-1`, `gpt-4o-transcribe`).
**HUD overlay:**
- **Recording**: floating pill with a 5-bar live audio meter so you can see the mic is hearing you
- **Transcribing**: spinner + "Transcribing…"
- **Inserted**: green check, auto-hide
- **No focus to paste into**: full transcript shown in a wider card, auto-copied to clipboard, dismiss by click
**Controls:**
- **Hotkey** (default `Fn`) — toggle recording on / off. Configurable to F-keys or modifier combos (`Cmd+Shift+V`, etc.)
- **Esc while recording** — cancel without transcribing (buffer discarded)
Configure everything from the macOS app's **Whisper** tab: pick provider, swap models, download / warm / delete WhisperKit variants, change hotkey or injection mode (paste vs Accessibility API).
Requires Microphone and Accessibility permissions (the app prompts on first launch).
## Health Endpoints
The gateway exposes health endpoints on `port + 1`:
- `GET /health` - Full status JSON
- `GET /metrics` - Prometheus-style metrics
- `GET /ready` - Readiness check
## CLI Commands
```bash
npm run configure # Interactive configuration
npm run status # Show config
npm run set-agent claude-code # Set default coding agent
npm run set-model # Set default model
npm run tui # Launch terminal UI
npm run build # Build all workspaces
```
For everything else (channels, profiles, API keys), edit `gateway.json` directly or use the macOS app's Settings panel.
## Project Structure
```
packages/
├── core/ # Shared types, workspace + bot managers
│ └── src/
└── gateway/ # Gateway server, channels, agents
└── src/
├── agents/ # Coding agent adapters (claude-code, opencode, codex, pi)
├── channels/ # Chat platform handlers (telegram, discord, imessage)
├── config.ts
├── conversation.ts
├── gateway.ts
├── health.ts
├── logger.ts
└── index.ts
codey-mac/ # macOS menu-bar app (Electron + React)
├── electron/ # Main + preload processes
└── src/ # Renderer (React UI)
voice/ # Native Swift helper for hotkey + capture + WhisperKit
└── Sources/CodeyVoice/ # AudioCapture, HotkeyManager, HudOverlay, WhisperKitEngine, ...
workspaces/ # Per-workspace config, memory, and bots
```
## FAQ
**Does Codey replace Claude Code / Codex / OpenCode?**
No — it drives them. Codey shells out to the agent CLIs you already have installed and signed in, and adds the layer above them: workspaces, bot teams, parallel runs, scheduling, and remote access.
**Do I need an API key?**
Only for what you use. If your agent CLI is already authenticated (e.g. a Claude subscription), Codey uses it as-is. API keys in `gateway.json` are for agents/models you want to reach directly, and for cloud voice transcription.
**Is my code sent anywhere?**
Codey itself is local — the gateway, the macOS app, and the voice helper all run on your machine. Your code goes wherever your chosen agent CLI already sends it, and nowhere else. On-device WhisperKit keeps voice local too.
**Which platforms are supported?**
The gateway is Node.js and runs anywhere Node does; the desktop app and voice input are macOS-only today.
**Can I use it from my phone?**
Yes — connect Telegram, Discord, or iMessage (scan a QR code to pair) and send prompts to the same workspaces from anywhere.
**How is this different from running several terminals?**
Shared workspaces and memory across agents, teams and flow graphs instead of one-shot prompts, per-chat git worktrees so parallel work doesn't collide, scheduled automations, and one UI that shows every run's status, diffs, and todo list.
## License
[MIT](LICENSE)
## Releasing (maintainers)
codey-mac auto-updates via electron-updater from GitHub Releases.
**Required repo secrets** (Settings → Secrets and variables → Actions):
- `CSC_LINK` — base64 of the Apple Developer ID `.p12` certificate
- `CSC_KEY_PASSWORD` — password for that `.p12`
- `APPLE_ID` — Apple ID email used for notarization
- `APPLE_APP_SPECIFIC_PASSWORD` — app-specific password for that Apple ID
- `APPLE_TEAM_ID` — Apple developer team ID (`N59NN58KB2`)
(`GITHUB_TOKEN` is provided automatically.)
**To ship a release:**
1. Bump the version in `package.json` and `codey-mac/package.json`.
2. Commit, then tag: `git tag vX.Y.Z && git push origin vX.Y.Z`.
3. The `Release codey-mac` workflow builds, signs, notarizes, and publishes the
dmg + zip + `latest-mac.yml` to the GitHub Release.
4. Installed apps detect the new version on next launch (or within ~4h) and show
the update button in the sidebar footer.
### Shared memory with Co-memo
Codey uses the official `@ahoh.tech/co-memo` 0.7.0 package through local MCP stdio. The gateway requires Node.js 24.12+. User notes are shared across projects; project notes use the chat's working directory, including its worktree. Conversations without a project receive personal memory only. No Bot-private memory is created.
Settings → Memory and workspace memory panels edit Co-memo directly. Edits and archives retain the version shown to the user, so concurrent changes are rejected. Archive keeps history. Codey's memory panels provide active, archived and conflict views, version history, restoration, and explicit conflict resolution by selecting current/candidate content or saving a merge. Stale restores and changed conflict reviews are rejected. Search, pause/resume and confirmed permanent deletion of archived notes are available directly in Codey. Memory controls use the app theme, with expandable cards and an on-demand composer; no external console is required.
The gateway recalls memory context before execution. Manage user memory in Settings and project memory in workspace panels. Agents receive instructions for the bundled Co-memo CLI; they decide what to save. There is no background transcript extractor. Disabling automatic saves requests Co-memo's user-level explicit-only policy. Disabling prompt memory affects Codey injection, not independent agent hooks or already-loaded conversation text. Read failures are logged and do not prevent the coding task; write/sync failures are shown rather than reported as saved.
`CO_MEMO_HOME` selects an existing custom store; omission uses Co-memo's normal data directory. `CO_MEMO_NODE` and `CO_MEMO_CLI` can override the bundled launcher (0.7+ required). Codey does not install per-project hooks. If a CLI already has Co-memo hooks, use its tools-only configuration to avoid duplicate context delivery. Upgrade older connected Co-memo installations before opening the shared database with 0.7.
Workspace memory panels include the actual checkout paths of their project chats, so isolated worktree memories can be managed alongside the base workspace. Resumed ordinary and Bot sessions receive current retrieval; Codey memory mutations invalidate both kinds of session anchors.
Automatic memory saving and Playbook learning are separate settings: Co-memo controls durable user/project facts, while Skills controls execution traces and procedure evolution. Conversation history, summaries and team blackboards remain task state managed by Codey.
New Codey-created worktrees inherit a one-time copy of the workspace main directory's active, non-conflicted project notes. Every worktree keeps its own Co-memo project ID; user notes remain shared. Later parent/worktree edits do not propagate, and merging a PR does not merge memory. Existing worktrees are not backfilled automatically.
Inheritance snapshots and source-note IDs/versions are retained under the Codey workspace's `memory-inheritance/` directory, outside the code checkout. Interrupted copies resume from the frozen snapshot before the first agent run. A paused or explicit-only Co-memo policy blocks automatic copying and leaves the worktree available for retry; no policy is bypassed. Already linked Co-memo projects are rejected rather than silently shared.
Co-memo is the only user/project memory store. Codey no longer scans, imports, rewrites or removes legacy Codey memory files. Workspace lifecycle operations do not create or maintain `memory.md` or a legacy index.
Connection Info
You Might Also Like
No recommendations available