# Spectra

[![OxygenFlow](https://oxygenhub.io/andymccall/spectra/flow/badge.svg)](https://oxygenhub.io/andymccall/spectra/flow)

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](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](../spectrahub); the editor integrations are [spectra-vscode](../spectra-vscode) and [spectrahub-vscode](../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](https://oxygenhub.io/projects/andymccall/7).

## 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`:

```json

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

```

Watch and chat from the [VS Code extension](../spectra-vscode), 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

| Path | Contents |

|---|---|

| `crates/spectra-core` | The model: the ledger, Spectra's own identities, signatures and CBOR, principals, conversation, presence, rules, the daemon's state |

| `crates/spectra-mcp` | Tuner (MCP over the Unix socket and loopback), the JSON API, the signing client and the browser sessions |

| `crates/spectra-api` | The JSON API's types; `make ts` writes `ts/index.d.ts` for the extensions |

| `src/cli` | The `spectra` command line |

| `docs/spec.md` | The specification |

| `docs/plan.md` | The sprint plan and its log |

| `packaging/spectra.service` | The systemd user unit |

## Licence

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