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

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

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.

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 (local, re-derivable caches branches --prune may destroy at any time).

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.

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> [--target <target>] [--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. Never mv/copy a store directly (Lance embeds absolute paths). See docs/migration-runbook.md for the full procedure and 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 of a table-producing command's rows instead of the rich table — e.g. witan tasks --all-repos --output-format json. Covers tasks, projects, memory, traces, scan test, scan rules, and (when witan-code is installed) code repos, code symbols, and code stitch; commands whose output isn't a flat table (task <slug>, project <slug>, graph, …) are unaffected.

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