Deterministic Context

Your AI assistant should read facts from a database, not guess.

AI coding agents start every session cold and re-infer project state. The dc tools replace that guessing with deterministic, queryable facts served over MCP.

$ uv tool install 'dctracker[mcp]'

$ dct init

dct on GitHub what's next: dcg ↓

The problem

Every session starts cold. The assistant re-explains, or guesses.

What was decided, what's mid-flight, how the code hangs together — re-inferred from scratch, every time. Re-inferring isn't just slow: it burns tokens re-reading files the agent already read yesterday. TODO.md rots. GitHub Issues live per-repo, behind an API the agent can't casually use.

Guessing

"Let me re-read the codebase…"
Stale TODO.md as memory
Decisions lost between sessions
Hundreds of reads to rebuild context
Plausible ≠ true

Facts

One user-scoped database
Read & written over MCP
Append-only ledger of decisions
State read once, not re-inferred
Same input, same answer

Tokens

Context comes from the database in one compact read — not re-inferred from the repo every session.

File reads

Recent changes are a query — changelog, items, decisions — not a blind grep expedition across the repo.

File writes

State goes to the ledger over MCP — no TODO.md churn, no status docs to keep in sync.

dct · Deterministic Context Tracker

End the day with /handoff. Start the next with /pickup.

The next session resumes exactly where the last one stopped — same open threads, same decisions, same plan. No copy-paste, no re-explaining.

# one working session

/track fix invoice rounding → issue #142 opened

/commit → blocked: no changelog entry

/commit → ok, changelog + commit recorded

/handoff → sprint flagged, prompt for next session stored

# next morning, cold start

/pickup → resumes #142: 2 todos open,

review gate pending, plan loaded

Session handoffs/handoff flags the sprint — what's in flight now — and leaves a prompt for the next session; /pickup reads both and resumes, across projects.
Append-only ledgerNotes and decisions are soft-deleted, never dropped.
Gate checkpointsA feature can't resolve while its gates are pending — dogfood, security, review. Enforced in code.
Changelog-firstA hook blocks git commit when app code changed without a changelog entry — the log writes itself, and /release is one command.
One-read pickup/pickup restores state in a single structured read — no repo re-crawl, no wasted tokens.
Local dashboarddct web — a read-only web viewer over the same database.

48 MCP tools13 skills4 hooks~670 testsPython 3.11+SQLite / PostgresMIT

dct web — the local read-only dashboard: sprint stats, item tables and project navigation — dct web — the local read-only dashboard, on the same database the agent uses.

dcg · Deterministic Context Graph

The blast radius of a change, visible before the damage.

dcg parses your codebase into a graph database and serves it to agents over MCP — 17 tools, Go single binary, Neo4j storage, Python and Go parsers, Django-aware.

> get_impacted billing/models.py::Invoice.total

Invoice.total ─ impacted (14 nodes, depth ≤3)
├─ billing/views.py
│  ├─ InvoiceDetail.get_context_data  [dj:view]
│  └─ export_csv                      [fn]
├─ billing/serializers.py
│  └─ InvoiceSerializer.get_total     [drf:fld]
├─ reports/monthly.py
│  └─ build_revenue_report            [fn] ⚠ entry pt
└─ templates/billing/detail.html      [dj:tpl]

coverage: py 96% · dj 91% · tpl 78%
unparsed: 3 files (listed on request)

"Same input, same graph, every time."

"It tells you what it doesn't know" — every parser reports coverage.

"One graph query replaces hundreds of grep/read operations — faster, cheaper, more reliable."

Coming soon — watch github.com/fotodeveloper.

Philosophy

Deterministic

Facts come from a database, not from a model's best guess. Same input, same answer — the property everything else here depends on.

Append-only

A ledger, not a whiteboard. Notes, checkpoints and decisions are soft-deleted at most; nothing is ever lost.

Enforced, not suggested

Gates and hooks live in code, not in convention. A commit without a changelog entry doesn't happen; a feature with failing gates doesn't resolve.

Local-first

Your tracking lives in your own database — SQLite in ~/.claude by default, first-class PostgreSQL when you want a server. Nothing leaves your machine.

Honest about limits

Every parser reports coverage. The tools tell you what they don't know, so you never mistake a partial answer for a complete one.

Open source

Built in the open.

The dc tools are developed publicly on GitHub. dct ships under the MIT license and takes issues and pull requests today; dcg opens up with its first public release. Bug reports, docs fixes and framework ideas are all welcome contributions.

Contribute on GitHub →