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 that, and starts where the last one stopped — without walking into a wall somebody already hit. The briefing is capped rather than unbounded, in rows and in bytes, and it reports what the caps left out instead of trimming in silence. Nothing is ever cut mid-sentence: every record comes back named and dated with its first line, and a body of null means the budget was spent, not that the record is empty.

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.
• A file can be asked what is known about it. The same links that carry the hashes are readable from the other end: get_file_context takes a path and answers with the tasks that touched it, their dead ends, and any standing note attached to it. Paths are folded to their repo-relative form, so a link made on one machine is found from another.

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 15+; see below for a container
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_…"

// OpenCode v1 — ~/.config/opencode/opencode.json.
// MCP key is `mcp` (server name is a direct key under it), NOT `mcpServers`.
// `type` is `"remote"`, NOT `"http"` — the Claude/Cursor/VS Code value is
// silently ignored on OpenCode.
{
  "mcp": {
    "todox": {
      "type": "remote",
      "url": "https://www.todox.dev/api/mcp",
      "headers": { "Authorization": "Bearer todox_…" }
    }
  }
}

// OpenCode v2 — same key, server now nested under `mcp.servers`.
{
  "mcp": {
    "servers": {
      "todox": {
        "type": "remote",
        "url": "https://www.todox.dev/api/mcp",
        "headers": { "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.
{
  "mcpServers": {
    "todox": {
      "type": "http",
      "url": "https://www.todox.dev/api/mcp",
      "headers": { "Authorization": "Bearer todox_…" }
    }
  }
}

// VS Code — the user-level mcp.json ("MCP: Open User Configuration").
// The root key is "servers", NOT "mcpServers". This is the one client
// that differs, and getting it wrong is silent.
{
  "servers": {
    "todox": {
      "type": "http",
      "url": "https://www.todox.dev/api/mcp",
      "headers": { "Authorization": "Bearer todox_…" }
    }
  }
}

The MCP config key and the type value differ per agent, and the wrong combination is silently ignored — no error, no warning, the tool just does not show up:

agent	key	type
Claude Code	mcpServers.NAME	"http"
OpenCode v1	mcp.NAME	"remote"
OpenCode v2	mcp.servers.NAME	"remote"
Cursor	mcpServers.NAME	"http"
VS Code (Copilot Chat)	servers.NAME	"http"
Codex	TOML [mcp_servers.NAME]	n/a

Where those files live differs by platform, and VS Code is the one that is not where a Linux habit puts it:

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.

Then tell your agent to use it

Connecting is not the same as being used, and the gap is bigger than it looks. An MCP server's instructions are background reading; a skill or a CLAUDE.md rule is an instruction. When they disagree, the server loses — measured, in a fresh project, with todox connected the whole time and never once called.

So put four lines in the memory file your agent actually obeys:

todox MCP is installed here — persistent memory across projects.

- Call `get_context` before starting non-trivial work (cwd = your working
  directory). It registers a new repo by itself.
- `create_task` for anything that will not finish this session.
- Before stopping, `log_entry(kind:'handoff')` on every task you touched,
  and `dead_end` for approaches that failed.
- Always pass your own model id.

Or let the installer do it:

pnpm install:mcp claude-code --write-memory

It is off unless asked, because that file is yours rather than ours, and it is idempotent — the block is fenced with an HTML comment, so a second run replaces it instead of leaving two sets of instructions where the older one wins. Add --dry-run to see the exact block first.

The user-level file, not the project one. This is the same trap as the config above, one directory over:

A repository's own AGENTS.md, and the per-project rules files the editors also read, apply inside that checkout only. A cross-project memory installed into one project is the thing this whole section exists to avoid.

The token stays out of that file — it lives in your MCP config. This is the habit, not the credential.

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. There is nothing to clone:

TODOX_TOKEN=todox_… TODOX_URL=https://www.todox.dev \
  npx https://github.com/beydemirfurkan/todox/releases/latest/download/todox-mcp.tgz

Or as an MCP config, which is the form an agent wants:

{
  "mcpServers": {
    "todox": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/beydemirfurkan/todox/releases/latest/download/todox-mcp.tgz"
      ],
      "env": { "TODOX_TOKEN": "todox_…", "TODOX_URL": "https://www.todox.dev" }
    }
  }
}

There is no npm package, and that is a decision rather than a to-do. A GitHub Release needs no account and no token to publish or to install from, so the tarball is the whole distribution and npx takes its URL directly. The URL above always resolves to the newest release; every release also carries a todox-mcp-<version>.tgz if you would rather pin and choose when to move.