TandemAI

TandemAI is a local-first delivery cockpit shared by Product Builders, developers, and coding agents. Its Delivery Map connects Epics, executable tickets, dependencies, agent activity, verification evidence, durable knowledge, and project documentation. Work stays in the agent's native interface; TandemAI never launches or selects that agent for you.

Install once, connect any project

TandemAI requires Node.js 22.13 or newer.

npm install --global tandemai-dev
cd /path/to/project
tandem-ai init
npm run tandem

tandem-ai init scaffolds the project MCP configuration for every supported agent, so teams can commit both integrations even when the maintainer uses only one of them. It separately detects supported agent commands on PATH without executing them and installs user-scoped skills only for agents found locally:

| Agent | Project MCP config | Shared workflow skill | | ----------- | -------------------- | ------------------------------------- | | Codex | .codex/config.toml | ~/.codex/skills/tandem-ai-workflow | | Claude Code | .mcp.json | ~/.claude/skills/tandem-ai-workflow |

Both MCP entries always call the same global tandem-ai mcp --project-root . command. If both agents are installed, both user skills are installed. If none is detected, the shareable MCP configs, project manifest, and npm scripts are still initialized; rerunning tandem-ai init later installs the missing user skill. Existing MCP entries, locally modified skills, /docs, and human content are preserved. TandemAI never adds itself to the project’s dependencies or lockfile.

Invoke the workflow as $tandem-ai-workflow in Codex or /tandem-ai-workflow in Claude Code. MCP project configurations are intended to be committed so every developer gets the connection; each developer still installs the global package and receives the managed skill in their own home directory.

The daemon intentionally keeps running after the terminal is released so other projects can join the same workspace. Stop the shared daemon for every connected project with:

npm run tandem:stop

The runtime registry keeps every authenticated fallback instance, so this command also cleans up an older daemon if a previous launch had moved to another port.

TandemAI also remembers every successfully connected project in ~/.tandem-ai/projects.json. After stopping or restarting the daemon, run npm run tandem from any one project: the workspace restores all remembered projects automatically, so the command does not need to be repeated in every repository.

Use tandem-ai doctor for versions, compatibility, daemon, ports, registry, databases, and MCP health. Run tandem-ai daemon only when you want the runtime attached to the terminal and stoppable with Ctrl+C.

Commit the generated MCP configuration for each agent used by the team (.codex/config.toml and/or .mcp.json), tandem.config.json, and the npm scripts added to package.json. User-scoped managed skills are not committed. Paths, tokens, and ports stay local; the manifest contains only the stable project identity, key, workflow version, and compatibility ranges. Legacy runner preferences may remain in an existing project for compatibility but no longer trigger agent execution.

The first project starts the daemon. Following projects authenticate the service identity before joining it; an unrelated process on the preferred port is never treated as TandemAI. The workspace restores registered projects after restart, while the UI keeps one explicit active project at a time.

Run tandem-ai update to update the global runtime without deleting registered projects or their databases. tandem-ai uninstall stops the daemon and removes the global registry and package, but intentionally leaves every project’s .tandem-ai/tandem.sqlite data in place.

Workflow

• Discuss the need and answer material questions in the agent interface you already use. Invoke tandem-ai-workflow; TandemAI does not provide a second conversation surface.
• The skill inspects the repository, evaluates product and security risk, then creates a positioned Epic and reviewable tasks through revisioned semantic MCP tools. Every Epic belongs to the Delivery Map.
• Routing happens when work is claimed. The agent uses the strongest available capability when risk or uncertainty is high, delegates only when the runtime supports it, and keeps the parent responsible for verification. Delegation never removes the MCP tools or skills available to the child.
• One project is active at a time. Its overview surfaces executable work, reviews and blockers.
• The Delivery Map is the primary workspace. It shows the dependency-aware Epic roadmap and opens a cockpit with a deterministic vertical execution order. Tasks in the same step may run in parallel; fine-grained execution detail belongs in the mutable plan rather than another task level.
• A claim records the factual agent, provider, model and effort exposed by the runtime. Missing data is stored as unknown; a recommendation is never invented. Historical runs and their frozen context remain readable for audit.
• Material questions stay in the native agent conversation. TandemAI records only the resulting decision or useful waiting state.
• Acceptance criteria require evidence before agent work can enter review. The agent records evidence and checks each proven criterion; the human remains responsible for final acceptance.
• Project is a read-only documentation center for /docs, ADRs, AGENTS.md, CLAUDE.md, and installed project skills. Git and the native agent remain the editing path; /docs is the shared project memory.
• The Epic inspector separates Learn, evidence, and reports. Learn shows Epic-specific knowledge plus the paths and diff of project documentation actually added by the agent; it contains no manual proposal queue.
• An Epic requires both a technical and a business report, each linked to real evidence, before it can enter review. review is visible and no longer blocks successors; only the human can close the Epic as done, which is the sole status hidden by the Terminées filter.
• Before its first claim, ready work can be edited or moved to recoverable project-local trash. After that, activity, attribution, Learn, and project knowledge are read-only in the cockpit.

The distributed workflow follows Frame → Shape → Plan → Ready → Execute → Verify → Deliver → Learn. Feature-specific knowledge belongs to versioned Epic memory; only concise cross-feature truths are candidates for the Git-backed project documentation under /docs.

Sources of truth

| Concern | Source of truth | | -------------------------------- | --------------------------------------------- | | Human scope and acceptance | Versioned ticket brief | | Agent execution strategy | Mutable ticket plan | | One historical run's exact input | Frozen context snapshot | | Feature decisions | Versioned Epic memory | | Cross-feature knowledge | Relevant Markdown and ADRs under /docs | | Agent rules | AGENTS.md and CLAUDE.md | | Repeatable procedures | Project SKILL.md files | | Verification and delivery | Evidence plus technical/business Epic reports |

Delivery context is assembled in this order: repository instructions, relevant project documentation, relevant project skills, Epic memory, ticket brief, then useful history. All project content is treated as untrusted data and cannot weaken sandbox, approval, or authority boundaries.

Develop locally

npm install
npm run build
npm test
npm run tandem

The React client uses Tailwind CSS v4 and source-owned shadcn/ui primitives. Feature modules, dependency rules, and component conventions are documented in src/web/ARCHITECTURE.md.

Runtime data stays under .tandem-ai/ and is ignored by Git.

Releases

The npm package is public under the name tandemai-dev. Every change pushed to main is validated on the oldest supported Node.js release and the current Node.js release. Publishing is intentionally separate: update the version, publish a GitHub release for the matching vX.Y.Z tag, and the trusted publish.yml workflow validates and publishes that exact version to npm.

The npm trusted publisher is restricted to MathiasD07/tandem-ai/.github/workflows/publish.yml; no long-lived npm token is stored in GitHub.