Witnis

An engineering witness for AI coding agents.

Map the repo. Trace the blast radius. Verify with evidence — not vibes.

Witnis pairs with Harnis: the harness limits what an agent can do; the witness grounds what an agent can claim.

Why it exists

Agents can edit files, run tests, and sound sure of themselves. They still often:

• treat a text hit as a typed symbol

• miss call, inherit, and override edges that define real blast radius

• equate “tests passed once” with proof — without a gated verify path

• answer without a machine-checkable evidence status

Grep and RAG find strings. They do not witness claims.

Witnis is local-first: index the tree into SQLite, answer through shared contracts, and keep Core facts free of any LLM.

flowchart LR
  Repo[Repository] --> Index[SQLite index]
  Index --> Search[search / LSP]
  Index --> Trace[trace / impact]
  Trace --> Plan[plan-verify]
  Plan --> Gate{authorized?}
  Gate -->|no| Blocked[blocked]
  Gate -->|yes| Verify[verify]
  Index --> Studio[Studio]
  Index --> MCP[MCP]

Related MCP server: roam-code

Quick start

git clone https://github.com/L00PLeGeNd/Witnis.git
cd Witnis
pip install -e ".[dev,lsp]"

witnis demo                 # index sample + witness card
witnis index .              # or index your own repo
witnis look login           # search · trace · impact · tests · plan
witnis studio login --open  # HTML dashboard

Deeper cuts when you need them:

witnis search login
witnis trace login --plain
witnis plan login
witnis verify login          # blocked until authorized
WITNIS_ALLOW_VERIFY=1 witnis verify login --execute
witnis bench --suite public

Extras: .[lsp] (Jedi), .[rust] (maturin), or .[all].

How agents should use it

witnis index .
witnis look <symbol>
witnis plan <symbol>
WITNIS_ALLOW_VERIFY=1 witnis verify <symbol> --execute
witnis studio <symbol> --open

look is the short path: one card instead of four separate JSON dumps.
Playbook: examples/agent-playbook.md

Envelope shape

CLI, MCP, and SDK share the same JSON shape:

{
  "status": "success",
  "repository": { "name": "mini_py", "root_path": "..." },
  "result": {},
  "evidence": [
    {
      "type": "symbol",
      "status": "observed",
      "path": "auth.py",
      "line": 12,
      "name": "AuthService.login"
    }
  ],
  "limitations": ["Search is name/path FTS+LIKE, not embeddings"],
  "generated_at": "2026-11-03T12:00:00Z"
}

Statuses encode uncertainty: observed · derived · verified · unverified · contradicted · stale · …

Contracts: docs/contracts-v1.md

Surfaces

Against simple baselines

witnis baselines fixtures/mini_py

MCP (any compatible client)

Same Core over MCP for any compatible host or coding agent. Index the repo, then register the server:

{
  "mcpServers": {
    "witnis": {
      "command": "witnis",
      "args": ["mcp"],
      "env": {
        "WITNIS_DB": "/ABS/PATH/TO/repo/.witnis/index.sqlite"
      }
    }
  }
}

Sample: examples/mcp.example.json

Clients differ in config file layout; the important bits are the witnis mcp command and WITNIS_DB. Agents should call list_capabilities before assuming tool names.

Security posture

Read-only by default.

• Paths sandboxed to the indexed root (symlink escapes rejected)

• Sensitive names (.env, *.pem, *.key, …) skipped or flagged

• Secret-like values redacted in previews

• Verify stays blocked until you authorize it

• Repo prose is untrusted input (prompt-injection aware)

More: SECURITY.md

Benchmarks

CI keeps the public suite green:

witnis bench --suite local
witnis bench --suite public

Public score (v1.8.0): 21 / 21.
Method: docs/benchmarks/PUBLIC.md · History: docs/benchmarks/public-scoreboard.md

Layout

adapters   CLI · MCP · SDK · Studio
    │
core       index · search · trace · impact · verify · evidence · LSP
    │
native     optional witnis._native (PyO3) → witnis-core (Rust)
    │
store      SQLite + FTS5 (symbols, relations, snapshots)

Python adapters install with plain pip. Rust speeds discover, digests, RustPython AST, and SQLite index/search. If _native is missing, Python paths still work.

Optional Rust tools

cargo test -p witnis-core
cargo run -p witnis-cli -- discover fixtures/mini_py
cargo run -p witnis-cli -- index fixtures/mini_go --db .witnis/rust-go.sqlite --full
cargo run -p witnis-cli -- search Login --db .witnis/rust-go.sqlite
cargo run -p witnis-cli -- overview --db .witnis/rust-go.sqlite

maturin build -m crates/witnis-py/Cargo.toml --release --out dist-native
pip install dist-native/witnis-*.whl

See docs/rust-migration.md.

Docs

Status

Ready for local Python-first agent work:

index → search / trace / impact → gated verify → Studio / MCP

Still ahead: a single Rust witnis binary, stronger language servers, larger third-party corpora.

Latest: v1.8.0

Contributing

See CONTRIBUTING.md. Keep pytest and witnis bench --suite public green.

License

Apache-2.0 — LICENSE.