witan

Pronounced WIT-ən (/ˈwɪtən/) — rhymes with "written" minus the r. From Old English witan, the king's council of advisors.

A team-wide shared knowledge graph for coding agents, backed by Omnigraph. Stores coding patterns, project/repo facts, lessons, and agent context. Exposed over MCP so every agent platform (pi, Claude Desktop, GitHub Copilot) can read and write without platform-specific code.

Documentation

See the User Guide for a task-oriented walkthrough (install, setup, day-to-day loop, operating modes, troubleshooting) and the CLI Reference for the full witan command surface.

Quick Start

witan setup installs the omnigraph binary, copies hooks/skills, and wires the MCP server entry into your agent config in one step. Run it once; re-run after upgrades to refresh installed files.

The omnigraph binary step always downloads the release pinned by _OMNIGRAPH_VERSION in the shared installer witan_core.omnigraph_install straight from GitHub releases into ~/.local/bin/omnigraph — there is no build-time bundling, so re-running witan setup is also how you pick up an omnigraph version bump (a Renovate PR bumps the pin; see renovate.json's omnigraph-version customManager). When witan-code is also installed (importable in this environment — e.g. via the --with in the uv tool install/MCP server's uvx invocation below), witan setup folds its skill and hooks into the same install pass — registered as witan code …, so the hooks only need witan on PATH, not a separate witan-code binary — and skips a separate MCP entry, since witan serve already mounts witan-code's tools in-process. One witan setup then covers both packages. Installed standalone (without witan), witan-code has its own equivalent witan-code setup (or the mounted witan code setup) — see its README.

With persistent CLI — required for Claude Code and Pi (and --agent all), whose hooks/extensions call the witan command directly, so it must stay on your PATH. Install witan-code alongside it with --with so its witan code … hooks work too (omit --with for a witan-only install):

# Install the latest release from PyPI …
uv tool install --with witan-code witan-council
# … or, to track pre-release/unreleased code, from the git repo directly:
uv tool install --with git+https://github.com/mitodl/agent-kit#subdirectory=mcp/servers/witan-code \
    git+https://github.com/mitodl/agent-kit#subdirectory=mcp/servers/witan
# … or editable from a local checkout, at the repo root:
uv tool install --editable --with ./mcp/servers/witan-code mcp/servers/witan

# then run setup:
witan setup --agent claude   # or: pi | all

On these two platforms the MCP server entry witan setup writes is witan serve — the same install the hooks use. The MCP-only agents below get a self-contained uvx --from … entry instead, since they have no CLI to point at. That difference is deliberate: registering the uvx form here would leave Claude Code and Pi running two witan installs from two different sources (the hooks on your PATH install, the MCP server on git main), which skew silently as those lineages diverge.

Without persistent CLI — enough for the MCP-only agents (Copilot, OpenCode, Kilo), whose server runs via uvx, so no install is needed:

# From PyPI …
uvx --from witan-council witan setup --agent copilot   # or: opencode | kilo
# … or, to track pre-release/unreleased code, from the git repo directly:
uvx --from git+https://github.com/mitodl/agent-kit#subdirectory=mcp/servers/witan \
    witan setup --agent copilot   # or: opencode | kilo
# … or from a local checkout, at the repo root:
uvx --from mcp/servers/witan witan setup --agent copilot

# Optional — set your author name (defaults to git config user.name or $USER):
export WITAN_AUTHOR="Your Name"

Manual wiring (if you prefer to configure agents by hand): run ./install.sh to initialise the local graph, then copy the appropriate config snippet from config/ into your agent's MCP config file.

Local development setup (both servers, hooks, and skills wired from your checkout): see Local Development Setup.

Environment Variables

For an S3-backed personal target, put the profile selection next to the store instead of wrapping witan in a credential-export shell script:

[targets.personal]
server = "s3://personal-witan/graph.omni"
s3_profile = "personal"
s3_region = "us-east-1"
match_paths = ["~/src/personal"]

Before each omnigraph subprocess, witan runs aws configure export-credentials --profile personal --format process and supplies the resulting access key, secret, and optional session token only in that child process's environment. The profile can therefore use static keys, SSO, role assumption, or credential_process; credentials are never written into config.toml. The AWS CLI must be installed when s3_profile is configured. Local and HTTP graph stores ignore these settings.

witan migrate merge --from <name> --to <name> carries each named target's own profile for its end of the merge, so two buckets under two profiles work in one command. A bare store URI on either end gets the ambient profile only when it is the configured store; otherwise it inherits whatever AWS credentials the environment already has, so name a target when the bucket needs its own.

MCP Tools

witan memory vs. your agent's built-in/session memory. witan is the shared, synced, team-wide store; a coding agent's built-in memory (e.g. Claude Code's memory/ files) is private to one machine and user. Durable, shareable engineering knowledge — project facts, patterns, lessons, decisions — belongs in witan so other agents and future sessions can find it; keep only private/ephemeral notes in built-in memory. The witan-memory skill and the MCP server instructions steer the agent accordingly.

Memory Tools

Workflow Tracking Tools

Track engineering projects end-to-end across multiple Claude Code sessions. See mcp/servers/witan/witan/skills/witan-project-tracker/SKILL.md for usage.

Task Tracking Tools

A dependency-aware, hierarchical task tracker (beads-like) in the same graph, so tasks hard-link to projects, sessions, and memories. See mcp/servers/witan/witan/skills/witan-task/SKILL.md (the /witan-task skill) for usage.

Tasks are hierarchical (an epic decomposes into sub-issues via parent, with parentSlug denormalized for fast child lookup) and dependency-aware (blocked_by maintains a denormalized blockedBy list that drives the task_ready query without graph traversal). external_uri links a task to a GitHub issue/PR or any reference.

Comments (TaskComment) are the way to say something about a task rather than to it. Every other write primitive either mutates the task (task_update, which overwrites another author's text) or creates a node (task_create, which puts a non-work item into the ready-work list) — so a one-paragraph correction used to cost a whole p0 task plus a parent edge written onto someone else's claimed row. task_comment is flat and append-only: no threading, no editing, no deleting, no resolution. It deliberately leaves the task's own row untouched, updated_at included, since that field doubles as the advisory-lease start for an in_progress task with no claimed_at — bumping it would silently renew a stranger's claim. Comments come back oldest-first in task_get, and the UserPromptSubmit hook surfaces unread ones on a task you hold (see below).

Code Branch Tracking

Links a git branch (repo + raw branch name, e.g. feature/new-api — never witan-code's sanitized omnigraph branch name) to the task/project it's carrying, so "which branch carries task X" and "which tasks are in flight on branch B" are one-hop graph queries. Coordination state that lives in witan (shared, durable), not witan-code's per-repo/bridge omnigraph stores — those are shareable now, but they stay re-derivable caches, rebuildable from the source tree by reindexing, and that is the distinction that matters here. (branches --prune is the narrow case: it deletes this checkout's own local branch views, refuses a shared graph outright, and never touches the bridge store.)

Wired in automatically, best-effort — no dedicated tool call needed:

• workflow_session_start upserts a CodeBranch for the current checkout's repo+branch (when detected) and links it ForProject to the session's project.
• task_claim upserts a CodeBranch on success and links it WorksOn the claimed task; re-calling task_claim (lease renewal) does not duplicate the edge.
• The UserPromptSubmit context-injection hook surfaces an In-Flight Branch section when the current checkout's branch already carries an open task — a signal that this session should likely continue that work rather than pick up something new.
• The same hook surfaces a New Comments on Work You Hold section, ahead of everything else, when an in_progress task held by this identity has a comment it has not shown yet. "Unread" is a local watermark in the session state dir, not a read receipt in the graph: it records what was rendered into this machine's prompt, which is a fact about a client rather than about shared work. Losing the file re-shows a comment, which is the harmless direction to fail in. Held tasks are found via cfg.author locally and task_list(assignee="@me") against a deployment, where the identity comes from the caller's token and the client cannot know it.

Both call sites no-op silently with no repo/branch context (detached HEAD, outside a git repo, or a store that predates this feature and hasn't run witan migrate schema yet) — this is metadata riding alongside a task/ workflow tool call, never a hard requirement for the tool it's attached to.

Write-path content scanning

Pluggable secret/PII scanning on every write (memories, tasks, projects, sessions, traces), with block/redact/warn enforcement and a witan.scanners entry-point mechanism so other organizations can add their own detection rules without forking. Enabled by default (opt-out) — see docs/write-path-scanning.md for the full config surface, the witan scan test/witan scan rules CLI, the audit trail, and how to write a plugin, and ADR 0001 for the design rationale.

Migrating or merging stores

Moving a store to a new machine, merging two machines' local stores, or moving a local store onto the shared multi-tenant server — same command in all three cases:

witan migrate merge [source] [--from <name>] [--to <name>] [--target-uri <uri>] [--dry-run]

Reconciles slug collisions newest-record-wins (by timestamp) rather than omnigraph load --mode merge's raw last-loaded-wins overwrite, and is repeatable — re-running against an already-merged target loads nothing new. --from/--to name [targets.<name>] config blocks (--to ol is how a local store moves onto the deployment); --target-uri names a store URI. Never mv/copy a store directly (Lance embeds absolute paths). See docs/migration-runbook.md for the procedure and docs/store-merge-findings.md for what was verified about --mode merge's actual collision behavior.

Tests

Integration tests spin up throwaway omnigraph graphs and exercise the real query files end-to-end (they skip automatically if the omnigraph binary is absent):

uv run --group test pytest

Exploring the graph (witan)

A cyclopts CLI for manual inspection of the work-coordination graph and the indexed code graphs. Installed alongside the server (uv run witan …, or uv tool install the package to get it on PATH):

Pass --output-format json|toml|yaml (default txt; env WITAN_OUTPUT_FORMAT) anywhere on the command line to get a machine-readable dump instead of the rich view, e.g. witan tasks --all-repos --output-format json. The table commands (tasks, projects, memory, traces, scan test, scan rules, target list, and with witan-code installed code repos, code symbols and code stitch) print {title, rows}. For witan's own commands an empty result is rows: [], never a sentence; the code commands still print prose when empty. task <slug> (also task show <slug>) and project status print the tool's record whole, and project tasks and session list print the tool's rows. Those four keep nulls in JSON and YAML and omit them in TOML, which has no null; the table commands still print a null as "" in every format. project <slug>, trace <slug> and graph are unaffected.

A structured run writes one document to stdout and nothing else; notices and log lines go to stderr, including on success. Branch on the exit code, not on whether stderr is empty: task <slug>, project <slug>, project status and project tasks exit 1 on a missing slug.

run claims the task (in_progress + your author), then hands the terminal to the agent seeded with the task description and a reminder to task_close when done — invoke it from the task's repo checkout. Use --dry-run to print the prompt without launching.

Operating Modes

Local Disk (default)

No extra infrastructure. Memories persist at ~/.local/share/witan/graph.omni.

# No env vars required.
export WITAN_AUTHOR="Alice Smith"

Local RustFS (S3-compatible, for testing team mode)

RUSTFS=1 ./install.sh
# Follow the printed export instructions.

Remote Team Server

export WITAN_MEMORY_URI=http://witan.internal:8080
export WITAN_MEMORY_TOKEN=<bearer-token>
export WITAN_AUTHOR="Alice Smith"

See docs/internals/agent-memory.md for full deployment instructions, the graph schema, and the v2 roadmap.

Project Structure

witan/
├── README.md                  # This file
├── install.sh                 # Initialise local graph (manual alternative to `witan setup`)
├── pyproject.toml             # Python package metadata
├── schema/
│   └── schema.pg              # Omnigraph graph schema
├── queries/
│   ├── read.gq                # Read queries
│   └── mutations.gq           # Insert/update queries
├── tests/                     # Integration tests
├── witan/          # Python package
│   ├── __init__.py
│   ├── __main__.py            # Entry point
│   ├── server.py              # FastMCP app + tool definitions
│   ├── cli.py                 # `witan` umbrella CLI (cyclopts)
│   ├── config.py              # Config loaded from env vars
│   ├── context.py             # inject-context / session-checkpoint helpers
│   ├── repo.py                # Git remote → canonical repo slug
│   ├── graph.py               # OmnigraphClient (CLI subprocess wrapper)
│   ├── setup.py               # `witan setup` agent-installer + omnigraph fetch logic
│   ├── extensions/            # Agent extension configs (bundled by setup)
│   ├── hooks/                 # Shell hooks (bundled by setup)
│   └── skills/                # Bundled agent skills
└── config/
    ├── pi.json                # Snippet for ~/.pi/agent/mcp.json
    ├── claude.json            # Snippet for claude_desktop_config.json
    └── copilot.json           # Snippet for .vscode/mcp.json