Span

[Span]

Carry useful investigations into the next coding session.

Span keeps the explanations your coding agent worked out, the evidence behind them, and what needs another look when that evidence changes.

[MCP server] [CI] [Apache-2.0] [Python 3.12+] [Linux verified] [Beta] [GitHub stars]

Quick start · How it works · Docs

Keep the understanding your agent worked for

A coding agent traces a request across services, checks the tests, finds the contract, and explains why the boundary exists. The next session should be able to find that explanation and see whether its support still holds.

Span makes that investigation reusable. It is a local MCP server where agents record coherent explanations with exact source support, explicit gaps, and version history. Later agents can discover the explanation through an ordinary engineering question, then inspect what is current, disputed, or changed.

The coding agent does the thinking. Span keeps the record and checks its support.

Three tools — ask, record, reconsider — carry one lifecycle: find current understanding, retain a supported conclusion, and re-align after change.

How it works

1. Investigate a real question. Ask about the surface you are looking at. Span returns current answers with surface status, or a gap with inspectable source evidence.
2. Record the useful result. Save one conclusion at a time with the file it rests on, or declare a service/domain surface for a cross-file explanation. Work that started outside Span can be recorded directly; the flat create derives support from the locator you already read.
3. Reuse in a fresh session. Ask the same question about the same surface, and retrieve the result with live support and challenges.
4. Reassess after change. Check affected dependencies, investigate what changed, then confirm, correct, replace, or withdraw the explanation. Earlier versions remain inspectable.

One explanation can span code, tests, CSS, configuration, and contracts. The agent decides what is worth recording; a file inventory does not become a mandatory documentation campaign.

See the lifecycle

Illustrative tool sequence, not literal request JSON. The installed schemas and MCP reference own the wire grammar.

ask: "How does checkout decide whether to charge?"  → Gap: exact evidence, a context, and an explicit question
agent investigates; record admits the source it just read
record(kind="understanding", conclusion, locator|observation_id|support)  → committed receipt, understanding version 1, support qualification
fresh session asks the same question about the same surface  → Answer with current conclusions, evidence, and surface statusask(selector=UnderstandingSnapshotSelector)  → recorded explanation, live support, gaps, and challenges
supporting source changesreconsider(changed_paths)  → every affected surface, with containment, direct, and indirect reasons,    and per-conclusion support state
agent investigates and records a correction against the expected version  → version 2; version 1 remains history

A query names the surface; saved understanding is matched by that surface and the recorded question. Wording is not treated as semantic equivalence, and a returned conclusion is a starting point for judgment.

Know what can be reused

Gaps and challenges remain visible independently of support currency. Matching bytes do not settle a dispute, and test existence does not establish a pass. Independent verification records the observations or evidence actually tested and preserves failures as failures.

Recording is atomic and returns a receipt. The caller preserves identity before sending; retrying the same identity and content recovers the retained receipt after a lost response or process restart. A committed receipt and a present support qualification answer different questions.

Quick start

The verified installation path is Linux with Python 3.12+, Node.js, and npm. From a checkout containing the current candidate:

python3 scripts/install-span.py --repo /path/to/your/repo

For a published package release, install span-mcp with your Python package manager and run span-install --repo /path/to/your/repo. See install and connect for registration, verification, and the offline store transition.

The installer provisions the managed structural indexer, runtime, skills, and host integration. With the default global OpenCode scope, it registers the Span lifecycle plugin and MCP server in the same global OpenCode configuration. Repeat installs use the receipt's absolute MCP path unless --opencode-config explicitly relocates it. Reconnect your coding agent after upgrade so it receives the new tools and instructions. Verify operational setup with:

span-install --verify-only

Setup creates no understanding. Begin with a question from your actual task; see using Span.

Beta host status

Registration, hook configuration, and model-delivered behavior are distinct. Optional hooks provide notices; retrieval and recording still check support when hooks are absent. See host integration.

Fits around your agent

Span runs locally over stdio and keeps state outside target repositories. Your agent uses its own model, tools, edits, and test runner. Span does not invoke a model or store provider credentials. Structural search helps investigation; recorded conclusions retain the agent's interpretation and declared support.

The intended benefit is continuity between sessions and a focused review of changed support. Recording and host delivery have costs. Measured cost is class-specific: repeated reuse of a covered surface breaks even at two uses on the tested tasks, while single-use implementation is currently more expensive than reading. This beta makes no universal time/token-saving claim or completed comparative product-fitness ACCEPT claim. See acceptance.

Status and documentation

This checkout describes 0.10.0: three lifecycle tools (ask, record, reconsider), schema-11 storage, surface-scoped answers, explicit store transition, and live support qualification. 0.10.0 makes the compact record grammar the only recording grammar: create takes exactly one evidence mode, updates are compact semantic deltas, new conclusion lineage identities are derived by Span, and expected_version remains compare-and-set. reconsider returns the expected version and context needed for the next record, and the legacy parallel create/challenge/verification wire path is removed. Host delivery is captured for the valid compact lifecycle on OpenCode; Codex has a current-candidate smoke create capture, and its full compact update journey is not re-observed. Claude registration/health and installer behavior are covered, while its authenticated model-delivery grammar and caller identity remain UNVERIFIED. OpenCode removes an unknown old-form field before delivery, so strict unknown-field rejection is not established through that host. Comparative fitness remains class-scoped (FD-53, FG-7). macOS and Windows installation paths remain unverified. Publication and product acceptance are separate from the implementation version.

• Install and connect
• Using Span and first investigation
• Agent lifecycle and MCP reference
• Support and reassessment
• Evidence and authority
• Scope and boundaries and FAQ
• Architecture, repository overview, and all docs
• Changelog

Older acceptance evidence retains its historical protocol and does not certify the rebuilt API or comparative value.

Contributing

See contributing. Preserve the central contract: useful understanding stays attached to its support, noncurrent or uncertain state stays explicit, and corrections preserve history. Security reports go through SECURITY.md; support expectations are in SUPPORT.md.

Registry

Official MCP Registry entry: io.github.pontivus-com/span

mcp-name: io.github.pontivus-com/span

License

Span is licensed under Apache License 2.0 (Apache-2.0). See LICENSE.