matdac12/traccia

You and your agents, on the same page.
A minimal, self-hosted issue tracker for one developer and their AI agents. Agents reach it over MCP; you use the dashboard. It runs on a private Tailscale network, and nowhere else.
No accounts, no seats, no sign-up. One SQLite file and one attachments folder, on a box you own.
Set it up with your agent
Traccia is small enough to install in one sitting, and it is meant to be installed by the agent sitting next to you. Paste the prompt below into Claude Code, Codex or OpenCode. It reads the self-hosting guide and does the work. You bring a Linux server and a free Tailscale account.
What it is
- Issues with projects, milestones, labels, sub-issues, priorities, estimates and blockers.
- A per-project knowledge layer: memories (titled markdown notes with tags) and documents (files) that agents read before they start work. Both are searchable, soft-deleted and restorable.
- Thirty MCP tools, so agents create and update their own work and read the project's knowledge. The list is in docs/mcp-tools.md.
- A dashboard with a table grouped by status, and a Kanban board.
- Attachments, full-text search, and soft delete with restore.
- Two actors only, you and agent. Every write is attributed.
- One SQLite file plus an attachments folder to back up.
It is deliberately not a team tool, not SaaS, and not a general project manager. The spec is the source of truth for what is out of scope.
Screenshots
The issues table, grouped by status, with inline editing and the row menu.
The same issues as a Kanban board, one column per status.
Architecture
Both containers bind to 127.0.0.1 on your server. tailscale serve is the only thing that publishes them, on your tailnet. The api is the only process that touches the database. The dashboard calls the api from server-side code and never exposes its token to the browser.
Quickstart
Local development needs Node 22 or newer and pnpm 10.
Run the api. BASE_URL is required, and DATA_DIR defaults to /data, so point it somewhere writable:
Then the dashboard, in another shell:
Self-hosting
The full walkthrough is docs/self-hosting.md: a Linux server, Docker and Tailscale. Deploying updates — build on your Mac, or pull the CI-built image — is in deploy/README.md.
Connect your agents
Create one token per tool and machine, then point the tool at https:// /mcp. Claude Code, Codex and OpenCode are covered in docs/agent-setup.md. Paste docs/agent-snippet.md into a repo's AGENTS.md so its agents follow the tracker's conventions.
To add Traccia to a whole claude.ai account instead, without a token per machine, there is an optional claude.ai custom connector; it is not required, and the setup above stays the default. See the optional connector section.
Configuration
One .env file in /opt/tracker (never committed): the api reads it directly, and the compose file passes the web variables through to the dashboard. The template is deploy/.env.example. The api validates its variables with Zod at startup and exits with a clear message on a bad value; apps/api/src/config.ts is the only place that reads process.env. A test (apps/api/test/readme.test.ts) fails if this table misses a variable from config.ts.
| Variable | Service | Default | Purpose |
|----------|---------|---------|---------|
| PORT | api | 8787 | HTTP port. Fixed to 8787 in the compose file |
| DATA_DIR | api | /data | SQLite file and attachments. Fixed to /data (the data volume, traccia-data) in the compose file |