# dc tools — Deterministic Context

> Full content of https://dctools.dev/ as markdown. Short version: https://dctools.dev/llms.txt

## 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 persistent, queryable memory — deterministic facts served over MCP.

Install:

    uv tool install 'dctracker[mcp]'
    dct init

Package: dctracker · command: dct.

## The problem

Every session starts cold. You re-explain, or the assistant guesses. What was decided, what's mid-flight, how the code hangs together — re-inferred from scratch, every time. That rebuild isn't just slow: it burns tokens on files the agent already read yesterday. TODO.md rots. GitHub Issues track a repo, not your working state — per-repo, remote, and blind to what's mid-flight across your projects.

Guessing looks like: "Let me re-read the codebase…", stale TODO.md as memory, decisions lost between sessions, hundreds of reads to rebuild context, plausible ≠ true.

Facts look like: one user-scoped database, read and written over MCP, an append-only ledger of decisions, state read once instead of re-inferred, same query → same answer.

What it saves:

- **Tokens** — context comes from one compact database read instead of re-inferring the repo every session.
- **File reads** — recent changes are a query: changelog, items, decisions, no blind grep expedition.
- **File writes** — state goes to the ledger over MCP, so there is no TODO.md churn and no status docs to keep in sync.

## The tools

### dct — Deterministic Context Tracker (v1.4.0, available)

Cross-project work tracking for AI coding agents. Issues, todos, plans, changelogs, sprints, decisions and session handoffs in one database your agent reads directly — any MCP client (Cursor, Windsurf, …) gets the full 52-tool server and CLI; Claude Code adds 13 skills and 4 hooks.

- Repository: https://github.com/fotodeveloper/dct
- Docs: https://github.com/fotodeveloper/dct/tree/main/docs
- PyPI: https://pypi.org/project/dctracker/ (package name: dctracker)
- Any MCP client: register `dct server` (stdio) in the client's MCP config; in Claude Code `dct init` does it for you

Workflow: end the day with /handoff, start the next with /pickup. The next session picks up the same open threads, decisions and plan — the outgoing session wrote the handoff while it still had the context, so nobody re-explains in the morning. Nothing to memorize: plain conversation drives it, and the slash commands are optional Claude Code shortcuts (any MCP client calls the same tools: create_item, pickup_work, handoff_work).

Example session:

    # one working session
    /track  fix invoice rounding   → issue #142 opened
    /commit → blocked: no changelog entry
             → agent adds changelog entry: "fix invoice rounding"
    /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

    # shown as Claude Code skills — any MCP client calls the same tools:
    # create_item · pickup_work · handoff_work

Features:

- **Cross-project tracker** — issues, todos and features with priorities, notes and checkpoints; one database across every repo, read and written by the agent over MCP.
- **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.
- **Markdown plans, indexed** — plan, spec and ADR files stay markdown; dct anchors their sections and checkpoints in the DB, promotable to items and sprints.
- **Append-only ledger** — notes and decisions are soft-deleted, never hard-deleted.
- **Gate checkpoints** — a feature can't resolve while its gates are pending (dogfood, security, review, approval). Enforced in code.
- **Changelog-first** — a Claude Code hook (wired at init with your consent, then on by default per project) blocks agent commits until a changelog entry exists — one line per change, written while the diff is still on screen; /release is one command.
- **One-read pickup** — /pickup restores recorded state in a single structured read, cutting the repeat discovery reads.
- **Local dashboard** — `dct web`, a read-only web viewer over the same database.

Stats: 52 MCP tools · 13 Claude Code skills · 4 Claude Code hooks · ~1180 tests · Python 3.11+ · SQLite / Postgres · MIT.

### dcg — Deterministic Context Graph (in development)

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.

Example query:

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

Design tenets: same input, same graph, every time. Every parser reports coverage — it tells you what it doesn't know. One graph query instead of a grep-and-read expedition.

Coming soon — watch https://github.com/fotodeveloper.

### dctools (planned)

The family is built to grow. `dctools` is the planned name for a future suite install.

## Philosophy

- **Deterministic** — facts come from a database, not from a model's best guess: same query, same answer. Where a model does help — classifying an ambiguous plan heading — its verdict is written down once and becomes a stored fact, never re-guessed. Determinism means retrieval: once recorded, state is never inferred again.
- **Append-only** — a ledger, not a whiteboard. Notes, checkpoints and decisions are soft-deleted at most; nothing is ever hard-deleted.
- **Enforced, not suggested** — gates and hooks live in code, not in convention. An agent commit without a changelog entry doesn't happen — a Claude Code hook blocks it at the tool boundary; a feature with pending gates doesn't resolve.
- **Local-first** — your tracking data lives in your own database: SQLite in your platform's data directory by default, first-class PostgreSQL when you want a server — and is never uploaded. The only network touchpoints are explicit and optional: a daily PyPI version probe (opt-out) and LLM plan-classification through the claude CLI you already use.
- **Honest about limits** — dcg's parsers report coverage; across the family, the tools tell you what they don't know, so you never mistake a partial answer for a complete one.

## Open source

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

- Contribute: https://github.com/fotodeveloper/dct
- © 2026 fotodeveloper · MIT (dct)