README quick start, a systemd user unit, and the spec §24 measurements; #13 ready for Andy 98a16830a3d3

# Spectra as a systemd user service (spec §22.3): agents reconnect to it as

# they start, so it should outlive any one terminal.

#

#   cp packaging/spectra.service ~/.config/systemd/user/

#   systemctl --user daemon-reload && systemctl --user enable --now spectra

#   journalctl --user -u spectra -f

[Unit]

Description=Spectra, the control plane for AI coding agents

After=default.target

[Service]

ExecStart=%h/.local/bin/spectra serve

Restart=on-failure

RestartSec=2

# SIGTERM writes a checkpoint and stops within five seconds.

KillSignal=SIGTERM

TimeoutStopSec=15

Environment=SPECTRA_LOG=info

[Install]

WantedBy=default.target

//! The targets of spec §24, measured: `brief` and `say` with a thousand

//! messages in the ledger, and how soon `wait` wakes after a mention. Run

//! in release, by hand:

//!

//! `cargo test --release --test bench -- --ignored --nocapture`

mod common;

use common::{add_agent, setup, Serving};

use serde_json::json;

use spectra_mcp::client::{rpc_result, Client};

use std::time::{Duration, Instant};

async fn call(c: &Client, name: &str, args: serde_json::Value) -> serde_json::Value {

    let req = json!({ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": name, "arguments": args } });

    rpc_result(&c.mcp("2025-11-25", &req).await.unwrap()).unwrap()

}

fn median(mut v: Vec<Duration>) -> Duration {

    v.sort();

    v[v.len() / 2]

}

#[tokio::test(flavor = "multi_thread", worker_threads = 4)]

#[ignore]

async fn spec_24_targets() {

    let dir = setup();

    let d = dir.path();

    let a = add_agent(d, "bench-a", &[]);

    let b = add_agent(d, "bench-b", &[]);

    let srv = Serving::start(d);

    let (ca, cb) = (Client::new(&srv.socket, Some(a)), Client::new(&srv.socket, Some(b)));

    for i in 0..1_000 {

        call(&ca, "say", json!({ "body": format!("message {i} about the pin bump"), "channel": "general" })).await;

    }

    let mut brief = Vec::new();

    let mut say = Vec::new();

    for i in 0..50 {

        let t = Instant::now();

        call(&ca, "brief", json!({})).await;

        brief.push(t.elapsed());

        let t = Instant::now();

        call(&ca, "say", json!({ "body": format!("timed {i}") })).await;

        say.push(t.elapsed());

    }

    let mut wake = Vec::new();

    for i in 0..10 {

        let w = tokio::spawn({

            let cb = Client::new(&srv.socket, Some(spectra_core::keys::KeyPair::load_home(&d.join("agents/bench-b")).unwrap()));

            async move {

                call(&cb, "wait", json!({ "timeout_s": 20 })).await;

                Instant::now()

            }

        });

        tokio::time::sleep(Duration::from_millis(200)).await;

        let sent = Instant::now();

        call(&ca, "say", json!({ "body": format!("@bench-b wake {i}"), "channel": "general" })).await;

        wake.push(w.await.unwrap().saturating_duration_since(sent));

        call(&cb, "ack", json!({ "ids": [] })).await;

        let inbox = call(&cb, "inbox", json!({})).await;

        let ids: Vec<serde_json::Value> =

            inbox["result"]["structuredContent"]["items"].as_array().unwrap().iter().map(|i| i["id"].clone()).collect();

        call(&cb, "ack", json!({ "ids": ids })).await;

    }

    println!("spec §24 with 1,000 messages, round trip over the socket including signing:");

    println!("  brief  median {:?}", median(brief));

    println!("  say    median {:?}", median(say));

    println!("  wait   wakes {:?} after the mention is sent (median)", median(wake));

    srv.stop();

}

- **Added: the README's quick start, a systemd user unit (`packaging/spectra.service`) and `tests/bench.rs`** for the targets of spec §24 (brief 2.7 ms, say 3.1 ms, wait wakes 4.2 ms after a mention, with 1,000 messages, in release).

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

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.

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](../spectrahub); the editor integrations are [spectra-vscode](../spectra-vscode) and [spectrahub-vscode](../spectrahub-vscode). The split mirrors Oxygen and OxygenHub.

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

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

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

| `crates/spectra-core` | The model: the ledger, identities and 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 |

| `crates/radar` | Radar, the owner's web pages, with its templates and assets |

| `deps/oxygen` | Oxygen, pinned: identities, signatures, CBOR and hashing come from `oxy-core` |

| `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`).

- [ ] #13 Acceptance (with Andy). Ready for him; what is left needs his key and his MCP configuration:

  1. `make install`; `spectra init` (reads his identity from ~/.config/oxy); `oxy identity delegate add <data>/keys/instance.identity --scope changes`.

  2. `cp packaging/spectra.service ~/.config/systemd/user/ && systemctl --user enable --now spectra`.

  3. `spectra project add ~/development/oxygen` and `~/development/oxygenhub`.

  4. `spectra agent add claude-oxygen --kind claude-code --project oxygen --home ~/.oxy-agents/claude-oxygen`, then the printed `oxy identity delegate add …`; the same for `antigravity-oxygenhub`.

  5. Claude Code in oxygen: `claude mcp add spectra -- spectra mcp --agent claude-oxygen`; Antigravity in oxygenhub: the `mcp_config.json` line in the README.

  6. Both call `brief`, post in #general, and see each other's messages; watch on `spectra open`.

  7. `spectra admin verify`; then on a copy of the database, edit a row and see verify catch it.

  8. Cut 0.1.0 in CHANGELOG.md and tag it.

- 2026-11-02 #11 and #12 done. Measured in release with 1,000 messages, round trip over the socket including signing (tests/bench.rs): brief 2.7 ms (target 5), say 3.1 ms (target 10), wait wakes 4.2 ms after a mention (target 100). A single ledger append 0.15 ms. 58 tests. #13 is ready for Andy.