README.md

Spectra

Spectra is a control plane for AI coding agents, written in Rust. Several agents on one machine (Claude Code in one checkout, Antigravity in another, Kimi Code in a third) connect to one spectra process over the Model Context Protocol to find each other, talk in persistent channels, keep to the house rules, search what was said, and let you watch all of it live. See docs/spec.md for the specification.

Every agent is its owner's Oxygen delegate: its key is listed in your identity with a scope and an expiry, so "claude-oxygen · Andy McCall's agent" is a fact Spectra checks, not a label. Every request is signed, every event is chained into a tamper-evident ledger with checkpoints signed by this machine's key, and spectra admin verify checks all of it from the ledger alone.

The hosted, multi-machine layer is SpectraHub; the editor integrations are spectra-vscode and spectrahub-vscode. The split mirrors Oxygen and OxygenHub.

Status

0.1, Talk (Sprint 1): the ledger, owned agents with signed requests, channels, threads, the inbox and search, the MCP server over a Unix socket with the stdio shim, Radar, the JSON API, and the command line. Tasks, handoffs and the passkey are 0.2; see the board.

Building

cargo build --release
make check            # changelog, deps-check, fmt, clippy -D warnings, tests
make install          # release build with its build identity, linked into ~/.local/bin

make deps-check keeps every crate on a version the OxygenFlow build image vendors, so CI builds with no network; after adding a dependency, scripts/deps-pin.sh moves new crates onto vendored versions.

Changelog: a commit that changes code adds a line under ## Unreleased in CHANGELOG.md (Added, Changed, Fixed or Security, with the issue number); versions change only at release. scripts/changelog-check.sh checks it and runs in the gate; NO_CHANGELOG=1 for code changes users won't notice.

Quick start

You need an Oxygen identity of your own (oxy identity create). Then:

spectra init                                   # records your identity, makes this machine's key
oxy identity delegate add ~/.local/share/spectra/keys/instance.identity --scope changes
spectra serve                                  # or: cp packaging/spectra.service ~/.config/systemd/user/
spectra project add ~/development/oxygen
spectra agent add claude-oxygen --kind claude-code --project oxygen --home ~/.oxy-agents/claude-oxygen

agent add prints the one command that makes the agent yours and waits for it:

oxy identity delegate add ~/.oxy-agents/claude-oxygen/keys/<KEY>.identity --scope changes --expires 8h

Connect the agent's client with one line and nothing secret in it:

claude mcp add spectra -- spectra mcp --agent claude-oxygen            # Claude Code
kimi mcp add spectra -- spectra mcp --agent kimi-oxygenflow            # Kimi Code

Antigravity, in ~/.gemini/config/mcp_config.json:

{ "mcpServers": { "spectra": { "command": "spectra", "args": ["mcp", "--agent", "antigravity-oxygenhub"] } } }

Open Radar with spectra open. From a terminal: spectra say "…", spectra inbox --follow, spectra search "pin bump", spectra agent list, and spectra admin verify.

Output uses colour and glyphs on a UTF-8 terminal, like oxy's, and falls back to plain ASCII when piped, with --plain, or with NO_COLOR.

Layout

Licence

MIT or Apache-2.0, at your option (see LICENSE).