todox

Working memory for developers and their agents. Not a checklist — a log your next session can actually resume from.

An issue tracker is written human-to-human. todox is written agent-to-agent, with a human reading over its shoulder. Every task carries the decisions behind it, the approaches that failed, the questions still open, and the note the last session left behind.

A fresh agent calls get_context, reads all of that, and starts where the last one stopped — without walking into a wall somebody already hit.

What goes in a log

Two things fall out of treating the log as the product:

• Stale context is flagged, and never faked. Linked files are hashed by the side that can see them — the agent — and the server stores the hashes and compares. If the code moves on, get_context says the note may be lying. Until an agent has actually looked, the note is marked as never checked rather than claimed to be fresh: context that lies is worse than none, and that includes lying about how sure we are.

• Reports come from the log, not from commits. Every status change is an event, so what did I finish today, how long did it take, which model did it is a query rather than archaeology.

Related MCP server: MCP Handoff Server

Try it

todox.dev — anyone can register. Small personal deployment, no uptime promise. Self-host if the log matters to you.

Run your own

pnpm install
cp .env.example .env.local     # any Postgres; a free Neon branch works
pnpm db:migrate                # idempotent
pnpm seed                      # optional demo account: demo / todox-demo
pnpm dev

Connect an agent

todox is a remote MCP server. There is nothing to install and no repository to clone: point any MCP client at the URL with an agent token.

Create a token on the Account page and it hands you text you can paste straight into whichever agent you use, plus the config snippet for the four common ones. The shape is always the same — one URL, one header:

# Claude Code. --scope user, because the default is this directory only.
claude mcp add --scope user --transport http todox https://www.todox.dev/api/mcp \
  --header "Authorization: Bearer todox_…"

# Codex — ~/.codex/config.toml
[mcp_servers.todox]
url = "https://www.todox.dev/api/mcp"
http_headers = { Authorization = "Bearer todox_…" }

// Cursor — ~/.cursor/mcp.json, the one in your home directory.
// VS Code — the user-level mcp.json ("MCP: Open User Configuration"),
// where the root key is "servers" rather than "mcpServers".
{
  "mcpServers": {
    "todox": {
      "type": "http",
      "url": "https://www.todox.dev/api/mcp",
      "headers": { "Authorization": "Bearer todox_…" }
    }
  }
}

Install it globally, not per project. Every one of these tools defaults to the directory you are standing in — claude mcp add without a scope, .cursor/mcp.json, .vscode/mcp.json — and a memory that only exists in one repository is the opposite of the point. It also fails quietly: the tools simply are not there in the next project, so the agent never mentions them.

Spell out "type": "http". A client that finds a url without one tends to assume a local command and fails with something unhelpful.

Optional: local mode

The hosted server has no filesystem — but your agent does, and that is enough: it sends the hash when it links a file and calls report_file_hashes with what it finds afterwards, so staleness works over HTTP like anywhere else.

The stdio server does that part itself rather than asking. Worth running if you would rather not spend an agent's attention on it, or want the hashing to happen even when the agent forgets:

TODOX_TOKEN=todox_… TODOX_URL=https://www.todox.dev pnpm -C /path/to/todox mcp

Tools

Every write tool takes a model, and the server instructions tell the agent to always pass it. That is what makes the per-model breakdown real rather than guessed.

Prompts

Three, because there are three moments this is for. They show up in your client's own menu, so you can see what the server does without reading anything:

Deploying

Vercel plus a hosted Postgres.

Run pnpm db:migrate when the schema changes. It deliberately does not run on cold start: DDL racing across serverless instances is a bad way to discover lock contention.

Coming from the old SQLite version? pnpm db:import-sqlite [path] copies a ~/.todox/todox.db across.

Security

Passwords are scrypt; sessions, agent tokens and email links are stored as hashes only. Ownership is enforced in one module, and a row belonging to someone else answers 404 rather than 403 so ids cannot be probed. Rate limits live in the database, so they hold across instances.

Details, and an honest list of what is not covered, in SECURITY.md.

Known gaps

• Search is ILIKE, not full-text.

• Staleness is per-file hash; per-symbol would be the honest version. Hosted, it depends on the agent actually sending hashes — the instructions ask, and nothing can make it.

• The smoke suites need a database. Point DATABASE_URL at a throwaway branch and CI runs them; without the secret that job skips and says so.

• No 2FA, no per-session revocation, no audit log.

• Share links are unlisted, not access-controlled.

• No keyboard navigation beyond / for search.

Contributing

The rules the codebase actually follows, and how to run the checks: CONTRIBUTING.md.

MIT — see LICENSE.