TAKT: YAML-Defined Coordination for AI Coding Agent Workflows

Why AI coding agents need external process control

AI coding agents working from prompts face a structural problem in long-running tasks: they forget earlier instructions, accumulate context pollution, blur the distinction between implementation and review, and may silently skip review steps that the prompt asked for. Adding more rules to a CLAUDE.md or a system prompt helps, but the README makes the constraint explicit: whether the rules are followed is still left to the agent's behavior. A prompt cannot enforce a process.

TAKT treats this differently. Instead of asking the agent to follow a process, TAKT defines the process in YAML workflow files that the tool itself enforces. Each phase of a task (planning, implementation, review, fix) is a defined workflow step. The agent receives only the context, permissions, and output contract for the current step. Review steps cannot be silently skipped; findings route work back to fix steps. Human judgment can be requested when a step requires a decision the agent should not make alone. TAKT was built using TAKT itself, which the README describes as dogfooding.

YAML workflows as the process definition

A TAKT workflow is a YAML file that defines phases, steps, personas, policies, knowledge sources, and output contracts. Each step receives only the context it needs for that phase, which keeps context focused and avoids the growing-context problem of single-agent sessions. The README describes the key elements: a persona defines the agent's role for that step (implementer, reviewer, fixer), a policy constrains what the agent may do, knowledge adds relevant domain information for the step, and an output contract defines what a valid output looks like.

The separation of responsibilities is the core mechanism. An implementation step is not allowed to review its own output. A review step produces findings that either close the task or route it back to a fix step. Fix steps address specific findings and produce an updated output for re-review. This loop can run multiple times until the review step passes or until a human checkpoint is reached. The workflow is reusable, versionable, and reproducible: running the same workflow on the same task description should produce a structurally similar result regardless of which session runs it.

Installing and running the first task

TAKT requires Node.js 22.22.0 or later. Installation is a single npm command:

npm install -g takt

From a Git repository with at least one commit, the basic workflow is:

# Talk to AI, describe a task, use /go, then choose "Queue as task"
takt

# Execute queued tasks in isolated worktrees
takt run

# Review diffs, merge, retry, requeue, or delete task branches
takt list

On first run, configure a provider in ~/.takt/config.yaml or set the API key environment variables for the provider you intend to use. The takt command opens an interactive session where you describe a task in natural language. Using the /go command and selecting 'Queue as task' adds it to the task queue. Queued tasks run in isolated git worktrees when you execute takt run, keeping the main working tree clean. After completion, takt list shows the task branches and their diffs for review.

Eight provider types and their requirements

TAKT supports multiple AI coding providers with different requirements. Four providers run via TypeScript SDK and require only Node.js with no external CLI: claude-sdk (using @anthropic-ai/claude-agent-sdk), codex (using @openai/codex-sdk), opencode (using @opencode-ai/sdk), and pi (using @earendil-works/pi-coding-agent).

The deepseek-harness provider uses a managed environment that TAKT builds with uv and communicates with through a private JSON-RPC bridge. It requires a separate installation step before first use:

takt deepseek-harness install

This command must complete before starting the provider. The managed environment uses uv-managed CPython 3.12. Supported platforms for deepseek-harness are Linux x64/arm64 with glibc 2.28 or later, and macOS arm64 14.0 or later. Windows, macOS x64, Linux musl, older Linux glibc, and older macOS versions are not supported and fail fast without a fallback. CLI-based providers (Cursor, GitHub Copilot CLI, Kiro) require their respective external CLIs to be installed and authenticated.

Isolated worktrees and step-level tracing

Each queued task in TAKT runs in an isolated git worktree. This means the task's changes do not touch the current working tree while in progress. Multiple tasks can run without interfering with each other or with active development in the main tree. When a task is complete, the diff is visible through takt list for review before merging.

Every step leaves logs and reports. The path from the initial task description to the pull request remains traceable: which phases ran, what each step produced, which review findings triggered a fix loop, and what the final diff contains. The README frames this as making the development process reviewable and reproducible without constant human intervention. The .takt/ directory at the repository root stores the workflow definitions used to build TAKT itself, providing a concrete working example of the format. Docker support is also present: the Dockerfile and docker-compose.yml at the root build the project in a node:24-alpine container and can run tests or lint.

Human checkpoints and when agents are not sufficient

TAKT includes a mechanism for requesting human judgment at specific points in a workflow. When a step determines that a decision requires human input (an architectural choice, a scope clarification, a security review), it can pause and surface the question rather than guessing. This is an explicit escalation path rather than an implicit one.

The README states that TAKT is built primarily for AI coding workflows but that the same model applies beyond coding: any task where multiple AI agents need to coordinate, or where review, judgment, and feedback loops can improve task quality. The comparison table in the README is specific: plain AI coding agents let prompts ask agents to follow a process, while TAKT's YAML workflow owns the process. Reviews that can be forgotten or skipped in a plain agent become explicit transitions in TAKT. The tradeoff is setup time: defining a YAML workflow for a task takes more work than writing a single prompt.

Where TAKT does not extend

TAKT orchestrates the coordination layer but does not replace the underlying AI coding agents. If the agent makes wrong implementation decisions, TAKT's review step may catch them, but only if the review workflow and persona are configured to check for the relevant error type. A workflow that does not include a security review step will not catch security issues no matter how many fix loops run.

The deepseek-harness platform support limitation is a concrete constraint for teams on Windows or non-glibc Linux: that provider is unavailable on those platforms. The SDK-based providers (claude-sdk, codex, opencode, pi) are cross-platform via Node.js. TAKT also requires git: the isolated worktree mechanism depends on a git repository with at least one commit. Non-git projects cannot use the worktree isolation feature. The web-ui/ directory at the repository root suggests a browser-based UI is in development or available, but the README documents the CLI workflow, not the web interface.

Maintenance and MIT license

The last push to nrslib/takt was on 2026-09-27, one day before this review. The package.json version is 0.66.1. There are no GitHub releases; the version is tracked in package.json. The MIT license permits unrestricted commercial use, modification, and redistribution. The repository root contains AGENTS.md, CLAUDE.md, a .coderabbit.yaml for automated code review, and a .devcontainer/ for VS Code container development. The changelog is maintained in CHANGELOG.md.

The test infrastructure uses vitest with multiple configuration files targeting different test categories (unit, integration, e2e with smoke, parallel, and provider-specific variants), and a Dockerfile that runs tests in a container. An eval/ directory and eval scripts suggest the project runs LLM-evaluation suites to test workflow quality. The project README and documentation exist in docs/, and written tutorials are referenced. The Discord server linked from the README provides a community channel.

Editorial conclusion

TAKT is suited for teams or solo developers who find that AI coding agents working from a single long context produce inconsistent results or skip review steps on longer tasks. The YAML workflow model gives the process durability and repeatability that prompt instructions alone cannot guarantee. Node.js 22.22.0 or later is required. The deepseek-harness provider needs a separate install step; SDK-based providers (claude-sdk, codex, opencode, pi) need only Node.js. Check the supported platform list for the deepseek-harness provider before committing to that path on Windows or older Linux glibc.

Frequently asked questions

Official sources

1. Official README
2. Project repository