wctx

Workspace context for coding agents.

Your system spans multiple repos. Your agent's context should too.

wctx capture --summary "what this session figured out"   # at the end of a session
wctx search  "has anyone looked at this?"                # from any other repo, later

Session in Repo A
        ↓
discovers behavior in Repo B
        ↓
wctx
        ↓
fresh session in Repo B retrieves it

A coding-agent session is scoped to a repository, because that is where files get edited. The system under investigation is not. So a session in your UI repo works out that the bug is actually in your SDK — and when you open a fresh session in the SDK a week later, that knowledge is gone.

wctx turns completed agent sessions into structured, evidence-backed engineering context, and serves it to future sessions over MCP. Local-first: no cloud account, no embeddings, no transcript upload.

---

Two-minute demo

pnpm install
pnpm demo

No API key, no network. It builds three synthetic repositories, imports a finished session from one, then asks a plain-language question from another:

$ wctx search "Has the selfie session expiration issue already been investigated?" --repo websdk-demo

  3 result(s) · 4 candidates · 14ms · searched websdk-demo plus 2 related repositories

  1. WebSDK uploadSessionImage does not retry after session expiration  [finding]
     from websdk-demo · session ses_8d3fb1a5 · commit 45a4cab · confidence 0.87
     · matches the query text
     · same repository
     · matches symbol uploadSessionImage

  3. Verify UI delegates selfie upload to the WebSDK  [finding]
     from verify-ui-demo · session ses_8d3fb1a5 · commit b041200 · confidence 0.95
     · matches the query text
     · verify-ui-demo uses websdk-demo (direct consumer)
     · high stated confidence (0.95)

Then the SDK file changes, and the evidence stops being trustworthy:

$ wctx evidence verify ev_9ae81278
  before: current — The repository is still at the source commit b60a991; nothing has changed.
  after:  stale   — All 1 referenced file(s) changed in b60a991..1ceeaa4. Re-read the code
                    before relying on this.

Full walkthrough: docs/demo.md.

Installation

Requires Node 22+ and git.

pnpm install
pnpm build
npm link        # optional: puts `wctx` on your PATH

wctx init       # creates ~/.wctx
wctx doctor     # checks database, git, adapters, and prints MCP setup hints

MCP setup

claude mcp add wctx -- wctx mcp

Or, for Codex and other MCP clients:

{ "mcpServers": { "wctx": { "command": "wctx", "args": ["mcp"] } } }

Seven tools, ordered for progressive disclosure so they stay affordable in a context window:

Tool	Purpose
workspace_overview	Orient in an unfamiliar repository: topology, recent sessions, key findings
search_session_evidence	The main one. Search prior sessions across related repositories
get_evidence	One item in full, with complete provenance
get_session_evidence	Everything from one session (transcript only on explicit opt-in)
get_related_repositories	How this repository relates to the others, and in which direction
verify_finding_freshness	Has the referenced code changed since this was recorded?
finalize_session	The single write tool: record what this session learned

wctx mcp-info prints the surface and client configuration snippets.

Recording what a session learned

One command, at the end of a session. It imports the session if needed and records the evidence in a single step, defaulting to the session you are running in:

wctx capture --summary "Traced the upload failure into the SDK" \
  --finding "SDK swallows the 419 :: uploadSessionImage returns it as terminal, no retry" \
  --repo my-sdk \
  --file "src/session/upload.ts#uploadSessionImage"

Or just ask your agent to do it — "record what we learned" — and it calls finalize_session with its own session id. It never needs to know an internal id, and calling it repeatedly in one session accumulates evidence rather than duplicating the session.

Making it proactive

An agent only does this if something tells it to, and the strongest place to say so is the project's own agent file — those are read on every request:

wctx instructions          # print the guidance
wctx instructions --write   # install it into CLAUDE.md / AGENTS.md (idempotent)

The guidance covers when to search (before investigating anything non-trivial), when to record (root causes, decisions with rationale, hard-won constraints, unresolved questions, surprises), and what not to record. That is the difference between a tool you remember to use and one that accretes.

With no summary supplied at all, wctx capture derives a factual one from the session's recorded tool activity — file counts, commands, errors, files changed. Dull on purpose: inventing a narrative from tool calls would be exactly the confident nonsense this project refuses to produce.

Core concepts

Workspace — a logical product above repositories. The context boundary. Repositories stay the edit boundary; nothing here widens an agent's write scope.

Repository — a registered git checkout, identified by its realpath so the same repository cannot register twice through a symlink or subdirectory. It may belong to several workspaces.

Relation — a declared, directional, typed edge (uses, depends_on, calls, imports, consumes_api, provides_api, shares_schema_with, related). Traversal follows edges in both directions, because if verify-ui uses websdk then a session in websdk still wants what verify-ui learned.

Session — a normalized coding-agent session from Xirp, Claude Code, or generic JSONL, with its cwd, branch, commit, messages, and tool activity.

Evidence — a finding, decision, change, unresolved question, known issue, architecture note, or constraint, attached to the repository it is about (often not the one the session ran in), with the files and symbols it concerns and the commit it was true at.

Freshness — a git-based verdict on whether the referenced files have changed since that commit: current, possibly_stale, stale, or unknown.

Architecture

Xirp · Claude Code · Codex · generic JSONL
                  ↓
          session adapters              ← the only code that knows a vendor format
                  ↓
        NormalizedSession
           ↓            ↓
  transcript copy   deterministic extraction (files, commands, errors — no LLM)
                        ↓
              structured evidence (findings, decisions, questions)
                        ↓
              workspace catalog · SQLite + FTS5 + git
                        ↓
              CLI  ·  MCP  ·  web UI          ← one service layer, no duplicated logic

Details, and the reasoning behind each boundary: docs/architecture.md.

Xirp integration status

Xirp turned out to expose a genuine, documented read path, so the adapter is real rather than a stub.

Question	Status
Session export exists	CONFIRMED — $CHIRP_SQUAB_PATH provides --session-history and session-parse, both versioned and harness-agnostic
Stable session id	CONFIRMED — survives harness moves; the harness's own id does not
Repository attribution	CONFIRMED — cwd in both the manifest and the harness records
Tool calls and file operations	CONFIRMED — recoverable per message
Who owns the transcript	CONFIRMED — the harness, not Xirp
Session-completion hook	LIKELY — harness stop hooks exist; installing one mutates harness config, so it is opt-in and out of scope here
MCP configuration	LIKELY delegated to the underlying harness
Schema stability across versions	UNKNOWN — only Xirp 0.12.1 with the claude harness was observed

The adapter pins both schema strings and fails loudly on an unknown version rather than guessing. Full evidence, including what remains unverified and how to reproduce it: docs/research/xirp.md.

Security

Nothing leaves your machine. No cloud, no telemetry, no embeddings API, no transcript upload; the entire dependency list is @modelcontextprotocol/server, better-sqlite3, commander, and zod.

• Transcripts are copied into your data directory (Claude Code deletes its own after 30 days) with a redacted copy alongside — and only the redacted copy is ever served.
• Redaction covers private keys, JWTs, authorization headers, AWS/GitHub/Slack/OpenAI/Google tokens, credentialed URLs, and secret assignments. It is best-effort pattern matching and is not a guarantee that a transcript is safe to share.
• Evidence returned to agents is labelled as historical, untrusted data, and instruction-like lines ("ignore all previous instructions") are neutralised. Mitigation, not immunity.
• Every git call uses an argument array, never a shell string. FTS5 queries are constructed, never interpolated.
• Transcript deletion and evidence deletion are independent operations.

Details: docs/security.md.

Comparison with existing tools

Capability claims are from each project's own README, checked 2026-08-13. Nothing here asserts that another project cannot do something.

Project	Primary strength	What wctx does differently
agentmemory	Broad automatic capture: 12 lifecycle hooks, 54 MCP tools, embeddings, session replay	Optimised for one question — what did a prior session in a related repository learn — with 7 tools and workspace topology as the routing key
engram	Lightweight agent-agnostic local memory: Go binary, SQLite + FTS5, MCP/HTTP/CLI/TUI	Post-session evidence with commit, file, and symbol provenance, plus a staleness verdict
context-router	Multi-repo workspaces, observations + ADRs, cross-repo edges inferred from imports and contracts	Its unit is an observation written at commit time; ours is a completed session decomposed into evidence, and our edges are declared and drive explainable ranking
anchor	Repo and org memory from GitHub PR history, with confidence, freshness, and cross-repo impact	PRs record what was merged; we index the investigation — including the dead ends and the unresolved questions — and need no GitHub auth
Rewind	Nightly consolidation of finished Claude transcripts into durable facts	Same philosophy (post-session beats in-session discipline), extended to multiple agents and a multi-repository workspace
byterover-cli	Curated, shareable context tree	Provenance and staleness over curation
codebase-memory-mcp	Code intelligence: 158 languages into a knowledge graph, sub-ms queries	Complementary — that indexes code as it is now; this indexes what sessions learned about it

Full survey with each project's memory boundary, capture mechanism, and what was reused as an idea: docs/research/competitive-landscape.md.

Evaluation

On a synthetic 15-query, 28-item corpus (pnpm eval), the relevant prior session appeared in the top five for 15 of 15 queries and ranked first for 11 of 15, with a median local retrieval latency of 1.6 ms. Adding workspace topology to plain FTS5 left hit-rate unchanged on this corpus but improved MRR from 0.839 to 0.867, made repository attribution exact (0.93 → 1.00), and eliminated results from unrelated repositories (0.20 → 0.00 per query).

The corpus is small, synthetic, and written by the same person who wrote the queries. What that means for reading the numbers is spelled out in docs/evaluation.md.

Limitations

The honest list, in full: KNOWN_LIMITATIONS.md. The three that matter most:

• Retrieval is keyword-shaped. FTS5 matches tokens. A fully paraphrased query with no lexical overlap can miss; structural boosts only partly compensate.
• Freshness is not verification. It answers "did the referenced files change?", never "is this claim still true". A behaviour change in an untouched file is invisible.
• Relations are declared, not inferred. An undeclared relation is invisible to ranking.

Roadmap

Ordered by how much they would improve the core loop:

1. Automatic session finalization via a harness stop hook (currently manual).
2. Xirp adapter hardening across versions and the codex / gemini harnesses.
3. Conflict detection and supersession suggestions — the schema supports both; nothing populates them.
4. Backstage / Portal catalog-info.yaml import behind the existing CatalogProvider seam.
5. A harder evaluation corpus with near-duplicate findings, to test whether topology helps find rather than only order.

Contributing

See CONTRIBUTING.md. pnpm typecheck && pnpm lint && pnpm test must pass, and pnpm demo must work from a clean clone with no credentials.

Attribution and non-affiliation

wctx is an independent open-source experiment inspired by public ideas from Xirp, Spotify Portal, Backstage, and MCP.

It is not affiliated with or endorsed by Spotify.

No source code from any of the projects in the comparison table was copied. The Backstage Component/System distinction is used as design inspiration, not as a runtime dependency, and no Backstage instance is required.

License

MIT. See LICENSE.