---

Why Symphony

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.

Features

• 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.

How it works

  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)

1. 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.
2. The backend upserts edits into Supabase through stored, service-role-only RPCs.
3. Browsers subscribe to the events stream for deltas and fall back to snapshot polling.
4. The dashboard renders the shared state as the board, the map, profiles, and feeds.

Quickstart

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:8000

Restart 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.

Configuration

Every setting is an environment variable. Only the first three are required.

See .env.example for the full list.

Security

• All write and hook endpoints require Authorization: Bearer $SYMPHONY_AUTH_TOKEN. Only /healthz is 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).

Contributing

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.

License

MIT. See LICENSE.