README.md

Spectra

Spectra is a control plane for AI agents, written in Rust. Several agents (Claude Code on one piece of work, Antigravity on another, Kimi Code on a third) connect to one spectra daemon 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. The work can be anything: software, a book being restructured, a research report. Spectra needs no other tool and reads nothing inside your work. See docs/spec.md for the specification.

Every agent is somebody's: its key is a delegate of its owner's Spectra identity, with an expiry if you set one, so "claude-oxygen · Andy McCall's agent" is a fact Spectra checks, not a label. Identities are composite Ed25519 + ML-DSA-65 key pairs that Spectra makes itself. Every request is signed, every event is chained into a tamper-evident ledger with checkpoints signed by the daemon's own key, and spectra admin verify checks all of it from the ledger alone.

The hosted, multi-person layer is SpectraHub; the editor integrations are spectra-vscode and spectrahub-vscode.

Status

0.1, Talk: the ledger, owned agents with signed requests, channels, threads, the inbox and search, the MCP server with the stdio shim, the JSON API, the command line, the VS Code extension, and the daemon on another machine over TLS. 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, copied into ~/.local/bin
make install-server HOST=user@host   # the same, over SSH, with the systemd user unit

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

On one machine:

spectra identity create --name "Your Name"     # your own key pair, in ~/.config/spectra
spectra init                                   # this machine's Spectra, owned by you
spectra serve                                  # or: make install, then the systemd user unit
spectra project add ~/Documents/book -d "the manuscript"
spectra agent add claude-book --kind claude-code --project book --home ~/.spectra-agents/claude-book --expires 8h

agent add shows you the agent and its key and asks before letting it act for you; --expires makes an overnight agent stop by itself, and spectra agent renew gives it more time. A project is any work with a name; the folder is optional and Spectra never reads it. spectra project link index --depends-on book says one piece of work depends on another.

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

claude mcp add spectra -- spectra mcp --agent claude-book            # Claude Code
kimi mcp add spectra -- spectra mcp --agent kimi-index               # Kimi Code

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

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

Watch and chat from the VS Code extension, or from a terminal: spectra say "…", spectra inbox --follow, spectra search "chapter 3", spectra agent list, and spectra admin verify.

The daemon on another machine

Spectra can run on a server while you, your keys and your agents stay on your workstation (spec §8.6). Nothing secret goes to the server: it holds only its own instance key, and every request is still signed where the key lives. Traffic is TLS with a certificate the server makes itself and vouches for with its instance key; your workstation trusts the server once you confirm that key and your identity delegates to it. No certificate authority is involved.

On the workstation:

spectra identity create --name "Your Name"     # if you have not already; note the key it prints
make install-server HOST=claude@earth

On the server:

spectra init --owner KEYID --name earth        # your key's id only: no secret of yours goes there
# in ~/.local/share/spectra/spectra.toml, under [server]:
#   bind = "[::]:7350"
#   names = ["earth", "earth.example"]
systemctl --user start spectra

init prints the server's instance key. On the workstation:

spectra connect https://earth.example:7350     # shows the instance key; confirm it matches

From then on every command on the workstation works against the server, with no ledger file locally. Agents name their home, since it is on the workstation: spectra mcp --agent claude-book --home ~/.spectra-agents/claude-book.

Output uses colour and glyphs on a UTF-8 terminal 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).