nrslib/takt

📦 Project: TAKT – AI‑Agent Coordination CLI

What it is

• A Node‑JS command‑line tool that lets you define repeatable development workflows for AI coding agents (Claude, OpenAI Codex, DeepSeek, Cursor, GitHub Copilot, etc.) using a simple YAML description.
• The CLI runs each step in an isolated Git worktree, logs everything, and can automatically open a PR when the workflow finishes.

Why it matters

• AI agents tend to forget earlier instructions, mix implementation and review, and produce un‑auditable changes. TAKT moves the process out of the model’s prompt and into a declarative workflow that the CLI enforces.
• Each step gets its own persona, permissions, knowledge, and output contract, so the model only sees the context it needs.
• Built‑in support for review/fix loops, human checkpoints, and per‑step output validation.

Core concepts

Concept	Role
Workflow	Ordered list of steps (plan → implement → review → fix …). Defined in workflows/*.yaml.
Step	One agent execution with a specific persona, permissions, and rules that decide the next step.
Provider	The underlying AI service (Claude SDK, Codex SDK, OpenCode CLI, etc.). TAKT talks to the provider via an SDK or external CLI.
Isolated worktree	A temporary Git checkout where the agent makes changes, keeping the main repo clean.
Log & report	After each step TAKT writes detailed logs and a summary report, making the path from task to PR auditable.

Key features

• YAML‑driven workflows – declare personas, permissions, and transition rules.
• Multiple providers – Claude, Codex, OpenCode, DeepSeek Harness, Cursor, Copilot, Kiro, etc.
• Automatic SDK installation (takt install <provider>) and updates.
• Review loops – explicit fix‑and‑re‑review cycles; optional human approval.
• Task queue – takt add to create tasks, takt run to execute them, takt watch for a resident executor.
• Web UI – optional viewer‑first UI at http://127.0.0.1:20525 for live logs and reports.
• Integration hooks – can be used as an Agent Client Protocol (ACP) or MCP server for other tools.
• Built‑in workflows – default, maintenance, pure, review, etc., plus a catalog of personas.
• Support for formal verification – optional Quint/Alloy checks for specifications.

Typical workflow

1. Talk to the AI with takt (or takt exec) to describe a task.
2. Use /go to generate a workflow YAML and save it as a task.
3. Run takt run – TAKT creates an isolated worktree, executes each step, logs results, and offers to open a PR.
4. Manage tasks with takt list, takt merge, takt retry, etc.

Installation & quick start

# Global install (requires Node ≥22.22)
npm install -g takt
# Install a provider SDK (example: Claude)
takt install claude-sdk

# Initialise a repo (must have at least one commit)
takt   # converse with the AI, then /go → Save as Task

takt run   # execute queued tasks

You can also install via Nix:

nix run github:nrslib/takt
nix profile install github:nrslib/takt

Use cases

• Automated feature development – plan, code, review, and fix a new feature without manual PR churn.
• Bug triage – turn a GitHub issue into a task, let the AI propose a fix, run a review loop, and merge automatically.
• Team‑level orchestration – define a team‑wide workflow (takt-default-team) that decomposes work among multiple agents.
• Formal verification – plug in Quint specifications to verify generated code before merging.

Limitations / considerations

• Requires Node 22+ and the appropriate provider SDKs or external CLIs to be installed.
• The quality of results depends on the underlying AI model; complex domains may still need human oversight.
• Review loops are explicit but can become long if the model repeatedly fails to satisfy contracts.
• Some providers need additional system dependencies (e.g., tmux for claude-terminal, Java 17 for Quint verification).
• The default web UI is experimental and currently Japanese‑first.

Where to learn more

• Full documentation: docs/README.md (English) and translations in docs/.
• Video tutorials: Chapter 1 & 2 linked in the README.
• CLI reference: docs/cli-reference.md.
• Workflow guide & built‑in catalog: docs/workflows.md & docs/builtin-catalog.md.

---

TAKT is itself built with TAKT (dog‑fooding), demonstrating the self‑hosted nature of the tool.