Symphony is an open-source control room for AI coding agents. Watch Claude Code, Codex, and opencode edit your repository in real time, and catch two agents about to collide on the same file before it becomes a merge conflict.
Quickstart · How it works · Features · Deployment guide · Research
The current wave of LLM observability tools traces agents you build with SDKs: waterfalls, token cost, session replays for your own orchestrated code.
Symphony answers a different question, the one every team running coding agents actually has:
Who or what is touching my repo right now, and are they about to step on each other?
You do not instrument your code. You install a hook. From then on every edit any agent makes, across every teammate's machine, streams onto one shared, live map of your codebase.
This is not a new idea, it is a well-studied one that never had a product for the AI-agent era. Decades of HCI research (FASTDash at Microsoft Research, Manhattan, TeamWATCH) showed that a shared, real-time, spatial view of who-is-editing-what measurably improves team awareness and catches edit conflicts early. Symphony brings that to autonomous coding agents. See docs/RESEARCH.md for the citations.
- Live repository board. A shared file tree that lights up as agents claim files, with per-file editor chips, freshness, and an attention panel for collisions and sensitive areas.
- Live 3D agent map. A perspective-projected constellation of your system: zones ring the repo core, agents hold position around the zones they are touching, live edits travel the edges as animated particles, and collisions pulse red. The layout stays still; the view moves only when you drag or zoom. Falls back to a card view under prefers-reduced-motion. Plain-English zone names come from an optional LLM pass.
- Collision detection. When two agents claim the same file, the board flags it, the pre-edit hook warns the other agent before it saves, and optional Slack alerts DM both people.
- Blast radius. A dependency graph per file: see what depends on the file an agent is editing before a risky change lands on it.
- Multi-agent, multi-machine. One hook covers Claude Code, Codex, and opencode. Every teammate's sessions land on the same board.
- Real-time, no reload. Edits stream over server-sent events (with Supabase Realtime push and a snapshot-poll fallback), so the board stays correct even if a socket drops.
- Optional LLM enrichment. Point it at an OpenAI or Anthropic key and you get per-person work summaries, a team standup blurb, plain-English system-map zones, new-identity classification, and an "Ask" box that answers questions from the live board state.
- Profiles, leaderboard, meetings. Per-person pages with current and completed work, a token leaderboard, and an optional meeting-notes drawer fed by a sync script.
- Self-hostable in minutes. Bring a free Supabase project and a token. Run locally or deploy the three-surface app to Modal.
your machines hosted backend browser
------------- -------------- -------
Claude Code \ live board
Codex >-- hook POST --> ingest API --> Supabase <== events ==> dashboard
opencode / (edit events) (FastAPI) (state + (SSE/WS) (web UI)
backplane)
- A lightweight hook on each machine mints a stable event id per edit, spools it to disk, and drains it to the ingest API without ever blocking the agent's tool call.
- The backend upserts edits into Supabase through stored, service-role-only RPCs.
- Browsers subscribe to the events stream for deltas and fall back to snapshot polling.
- The dashboard renders the shared state as the board, the map, profiles, and feeds.
Requires Python 3.11+ and a free Supabase project.
git clone https://github.com/itsloganmann/symphony.git
cd symphony
cp .env.example .env # fill in SUPABASE_URL, service key, and tokens
pip install -e ".[serve]"
# 1. Create the schema in your Supabase project
SUPABASE_PROJECT_ID=... SUPABASE_ACCESS_TOKEN=... \
python -m symphony.scripts.apply_supabase_schema
# 2. Run the server
python -m symphony # serves the dashboard on http://localhost:8000
# 3. Install the hook into your agents, from inside the repo you want on the board
python symphony/scripts/install_hooks.py --endpoint http://localhost:8000Restart any open Claude Code, Codex, or opencode session so the hook loads, then start
editing. Open the dashboard, enter your SYMPHONY_READ_TOKEN, and watch the board light up.
To group agents under people (names, avatars, aliases), copy team.example.json to
team.json and edit it. Hosted deployment (Modal), the read API for agents, and the full
security posture are in the deployment guide.
Every setting is an environment variable. Only the first three are required.
| Variable | Required | Purpose |
|---|---|---|
SYMPHONY_SUPABASE_URL |
yes | Supabase project URL |
SYMPHONY_SUPABASE_SERVICE_ROLE_KEY |
yes | Server-side Supabase key (never sent to the browser) |
SYMPHONY_AUTH_TOKEN |
yes | Bearer token for hooks and writes |
SYMPHONY_READ_TOKEN |
recommended | Token browsers use to open the dashboard |
SYMPHONY_REPO_ROOT_LABEL |
no | Repo name the board displays |
SYMPHONY_TEAM_FILE |
no | Path to the team roster JSON (default team.json) |
SYMPHONY_SUPABASE_ANON_KEY |
no | Enables realtime push |
SYMPHONY_SUPABASE_JWT_SECRET |
no | Mints scoped realtime tokens |
OPENAI_API_KEY / ANTHROPIC_API_KEY |
no | LLM enrichment (summaries, zones, ask) |
See .env.example for the full list.
- All write and hook endpoints require
Authorization: Bearer $SYMPHONY_AUTH_TOKEN. Only/healthzis public. - Read endpoints require
SYMPHONY_READ_TOKEN; the dashboard cookie does not authorize them. - Supabase is reached only through stored RPCs granted to
service_role. The service key lives server-side and is redacted from all rendered HTML. - Request bodies are capped per endpoint; oversize returns 413, malformed JSON returns 400.
- Untrusted fields are bounded server-side (path lists stripped of control characters and length-capped, metadata size-capped).
Issues and pull requests are welcome. Symphony is built to be forked. See docs/DESIGN.md for the design system and docs/RESEARCH.md for the evidence base.
MIT. See LICENSE.