Pituitary

Catch spec drift before it catches you.

Solves intent drift. When your specs, docs, and decisions
silently contradict each other across sessions.

What It Catches · Quick Start · Editor · CI · Cheatsheet · Reference

---

For developers and teams where human+AI produce more docs and specs than anyone can keep consistent.

Watch on asciinema for the interactive version.

Single binary. No Docker. No API keys required. One SQLite file.

What It Catches

Overlapping decisions. A new spec covers ground an existing one already handles. Nobody noticed until both were accepted.

Stale docs. A spec changed, but the CLAUDE.md, AGENTS.md, runbooks, and guides that reference it weren't updated.

Code that contradicts specs. Pipe your diff in before you merge:

git diff origin/main...HEAD | pituitary check-compliance --diff-file -

Terminology drift. The team adopted new language but old terms persist across your docs and specs.

Quick Start

pituitary init --path .              # discover, index, report
pituitary check-doc-drift --scope all  # find stale docs
pituitary review-spec --path specs/X   # full review of one spec
pituitary status                       # index health at a glance

Command Reference

What you want to do	Command
First run on a repo	pituitary init --path .
Find stale docs	pituitary check-doc-drift --scope all
Check a PR diff against specs	git diff origin/main...HEAD | pituitary check-compliance --diff-file -
Full spec review	pituitary review-spec --path specs/X
Auto-fix deterministic drift	pituitary fix --scope all --dry-run
Search specs semantically	pituitary search-specs --query "rate limiting"
Trace impact of a spec change	pituitary analyze-impact --path specs/X
Compare two specs	pituitary compare-specs --path specs/A --path specs/B

All commands output JSON with --format json. review-spec also supports --format markdown and --format html for shareable reports with full evidence chains.

See the cheatsheet for every command, or the full reference for configuration, runtime setup, and spec format details.

Install

macOS (Homebrew):

brew install dusk-network/tap/pituitary

Linux / macOS (binary): download from GitHub Releases, then:

tar xzf pituitary_*_*.tar.gz
sudo install pituitary /usr/local/bin/

Windows: download pituitary_<version>_windows_amd64.zip from GitHub Releases, extract pituitary.exe, and add its location to your PATH.

Build from source (contributors): see docs/development/prerequisites.md.

Use It From Your Editor

Pituitary ships an MCP server so your agent gets spec awareness mid-session. Add it to Claude Code, Cursor, Windsurf, or any MCP-compatible client:

{
  "mcpServers": {
    "pituitary": {
      "command": "pituitary",
      "args": ["serve", "--config", ".pituitary/pituitary.toml"]
    }
  }
}

Your agent gets 6 tools: search_specs, check_overlap, compare_specs, analyze_impact, check_doc_drift, review_spec. It uses them when reviewing PRs, checking whether a change contradicts an accepted decision, or planning changes that touch governed code.

Use It in CI

Add spec hygiene checks alongside your linter:

- run: pituitary index --rebuild
- run: git diff origin/main...HEAD | pituitary check-compliance --diff-file -
- run: pituitary check-doc-drift --scope all

See docs/development/ci-recipes.md for a complete GitHub Actions recipe.

Semantic Retrieval (for professional accuracy beyond the deterministic default)

Pituitary works out of the box with no API keys and no external dependencies. If you work in a professional context with higher standards for accuracy, you can enable deeper semantic support. This improves how precisely overlap detection, drift checks, and search match related content across your specs and docs.

Cloud: OpenAI (if you already have a key)

[runtime.embedder]
provider = "openai_compatible"
model = "text-embedding-3-small"
endpoint = "https://api.openai.com/v1"
api_key_env = "OPENAI_API_KEY"

Local: LM Studio or Ollama (no data leaves your machine)

[runtime.embedder]
provider = "openai_compatible"
model = "nomic-embed-text-v1.5"
endpoint = "http://127.0.0.1:1234/v1"

Then rebuild: pituitary index --rebuild

Any OpenAI-compatible embedding API works. See runtime docs for full setup including analysis providers.

Architecture

See ARCHITECTURE.md for the full system design. Key decisions: deterministic retrieval first, tools-only (no embedded agent), single SQLite file with atomic rebuilds.

Project Status

Active development. Core analysis is functional end-to-end: overlap, drift, impact, compliance, terminology, and review workflows all ship today. Pituitary watches your specs, docs, and decision records. Code compliance is a supporting bridge, not the product center. See docs/rfcs/0001-spec-centric-compliance-direction.md.

See ROADMAP.md for what's shipped, what's next, and where Pituitary is headed.

Contributing

See CONTRIBUTING.md. The codebase has clear package boundaries so you can contribute to one area without understanding the whole system.

License

MIT