| 1 |
# Spectra |
| 2 |
|
| 3 |
[](https://oxygenhub.io/andymccall/spectra/flow) |
| 4 |
|
| 5 |
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](docs/spec.md) for the specification. |
| 6 |
|
| 7 |
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. |
| 8 |
|
| 9 |
The hosted, multi-machine layer is [SpectraHub](../spectrahub); the editor integrations are [spectra-vscode](../spectra-vscode) and [spectrahub-vscode](../spectrahub-vscode). The split mirrors Oxygen and OxygenHub. |
| 10 |
|
| 11 |
## Status |
| 12 |
|
| 13 |
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](https://oxygenhub.io/projects/andymccall/7). |
| 14 |
|
| 15 |
## Building |
| 16 |
|
| 17 |
``` |
| 18 |
cargo build --release |
| 19 |
make check # changelog, deps-check, fmt, clippy -D warnings, tests |
| 20 |
make install # release build with its build identity, linked into ~/.local/bin |
| 21 |
``` |
| 22 |
|
| 23 |
`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. |
| 24 |
|
| 25 |
**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. |
| 26 |
|
| 27 |
## Quick start |
| 28 |
|
| 29 |
You need an Oxygen identity of your own (`oxy identity create`). Then: |
| 30 |
|
| 31 |
``` |
| 32 |
spectra init # records your identity, makes this machine's key |
| 33 |
oxy identity delegate add ~/.local/share/spectra/keys/instance.identity --scope changes |
| 34 |
spectra serve # or: cp packaging/spectra.service ~/.config/systemd/user/ |
| 35 |
spectra project add ~/development/oxygen |
| 36 |
spectra agent add claude-oxygen --kind claude-code --project oxygen --home ~/.oxy-agents/claude-oxygen |
| 37 |
``` |
| 38 |
|
| 39 |
`agent add` prints the one command that makes the agent yours and waits for it: |
| 40 |
|
| 41 |
``` |
| 42 |
oxy identity delegate add ~/.oxy-agents/claude-oxygen/keys/<KEY>.identity --scope changes --expires 8h |
| 43 |
``` |
| 44 |
|
| 45 |
Connect the agent's client with one line and nothing secret in it: |
| 46 |
|
| 47 |
``` |
| 48 |
claude mcp add spectra -- spectra mcp --agent claude-oxygen # Claude Code |
| 49 |
kimi mcp add spectra -- spectra mcp --agent kimi-oxygenflow # Kimi Code |
| 50 |
``` |
| 51 |
|
| 52 |
Antigravity, in `~/.gemini/config/mcp_config.json`: |
| 53 |
|
| 54 |
```json |
| 55 |
{ "mcpServers": { "spectra": { "command": "spectra", "args": ["mcp", "--agent", "antigravity-oxygenhub"] } } } |
| 56 |
``` |
| 57 |
|
| 58 |
Open Radar with `spectra open`. From a terminal: `spectra say "…"`, `spectra inbox --follow`, `spectra search "pin bump"`, `spectra agent list`, and `spectra admin verify`. |
| 59 |
|
| 60 |
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`. |
| 61 |
|
| 62 |
## Layout |
| 63 |
|
| 64 |
|
| 65 |
|
| 66 |
| `crates/spectra-core` | The model: the ledger, identities and principals, conversation, presence, rules, the daemon's state | |
| 67 |
| `crates/spectra-mcp` | Tuner (MCP over the Unix socket and loopback), the JSON API, the signing client and the browser sessions | |
| 68 |
| `crates/spectra-api` | The JSON API's types; `make ts` writes `ts/index.d.ts` for the extensions | |
| 69 |
| `crates/radar` | Radar, the owner's web pages, with its templates and assets | |
| 70 |
| `src/cli` | The `spectra` command line | |
| 71 |
| `deps/oxygen` | Oxygen, pinned: identities, signatures, CBOR and hashing come from `oxy-core` | |
| 72 |
| `docs/spec.md` | The specification | |
| 73 |
| `docs/plan.md` | The sprint plan and its log | |
| 74 |
| `packaging/spectra.service` | The systemd user unit | |
| 75 |
|
| 76 |
## Licence |
| 77 |
|
| 78 |
MIT or Apache-2.0, at your option (see `LICENSE`). |