TAKT

🇯🇵 日本語ドキュメント | 💬 Discord Community

TAKT Agent Koordination Topology — Give your AI coding agents structured review loops, managed prompts, and guardrails — so they deliver quality code, not just code.

TAKT runs AI agents (Claude Code, Codex, OpenCode, Cursor, GitHub Copilot CLI) through YAML-defined workflows with built-in review cycles. You talk to AI to define what you want, queue tasks, and let TAKT handle the execution — planning, implementation, multi-stage review, and fix loops — all governed by declarative workflow files.

TAKT is built with TAKT itself (dogfooding).

Why TAKT

Batteries included — Architecture, security, and AI antipattern review criteria are built in. Ship code that meets a quality bar from day one.

Practical — A tool for daily development, not demos. Talk to AI to refine requirements, queue tasks, and run them. Worktree isolation on task execution, PR creation, and retry on failure.

Reproducible — Execution paths are declared in YAML, keeping results consistent. Workflows are shareable — a workflow built by one team member can be used by anyone else to run the same quality process. Every step is logged in NDJSON for full traceability from task to PR.

Multi-agent — Orchestrate multiple agents with different personas, permissions, and review criteria. Run parallel reviewers, route failures back to implementers, aggregate results with declarative rules. Prompts are managed as independent facets (persona, policy, knowledge, instruction) that compose freely across workflows (Faceted Prompting).

Requirements

The provider you choose determines whether you need to install an external CLI or can run on Node.js alone via a TypeScript SDK.

These providers run via SDK (no CLI required, Node.js only):

• claude-sdk — @anthropic-ai/claude-agent-sdk
• codex — @openai/codex-sdk
• opencode — @opencode-ai/sdk

These providers require an external CLI:

• claude — Claude Code
• copilot — GitHub Copilot CLI
• cursor — Cursor Agent

Optional:

• GitHub CLI (gh) — for takt #N (GitHub Issue tasks)
• GitLab CLI (glab) — for GitLab Issue/MR integration (auto-detected from remote URL)

OAuth usage: Whether OAuth is permitted varies by provider and use case. Check each provider's terms of service before using TAKT.

Quick Start

Install

npm install -g takt

Talk to AI and queue tasks

$ takt

Select workflow:
  ❯ 🎼 default (current)
    📁 🚀 Quick Start/
    📁 🎨 Frontend/
    📁 ⚙️ Backend/

> Add user authentication with JWT

[AI clarifies requirements and organizes the task]

> /go

Proposed task:
  ...

What would you like to do?
    Execute now
    Create GitHub Issue
  ❯ Queue as task          # ← normal flow
    Continue conversation

Choosing "Queue as task" saves the task to .takt/tasks/. Run takt run to execute — TAKT creates an isolated worktree, runs the workflow (plan → implement → review → fix loop), and offers to create a PR when done.

# Execute queued tasks
takt run

# You can also queue from GitHub Issues
takt add #6
takt add #12

# Execute all pending tasks
takt run

"Execute now" runs the workflow directly in your current directory without worktree isolation. Useful for quick experiments, but note that changes go straight into your working tree.

Manage results

# List task branches — merge, retry, requeue, force-fail, or delete
takt list

How It Works

The name TAKT comes from the German word for "beat" or "baton stroke," used in conducting to keep an orchestra in time. TAKT uses workflow and step consistently in both user-facing and implementation-facing terminology.

A workflow is defined by a sequence of steps. Use steps, initial_step, and max_steps. Each step specifies a persona (who), permissions (what's allowed), and rules (what happens next). Here's a minimal example:

name: plan-implement-review
initial_step: plan
max_steps: 10

steps:
  - name: plan
    persona: planner
    edit: false
    rules:
      - condition: Planning complete
        next: implement

  - name: implement
    persona: coder
    edit: true
    required_permission_mode: edit
    rules:
      - condition: Implementation complete
        next: review

  - name: review
    persona: reviewer
    edit: false
    rules:
      - condition: Approved
        next: COMPLETE
      - condition: Needs fix
        next: implement    # ← fix loop

Rules determine the next step. COMPLETE ends the workflow successfully, ABORT ends with failure. See the Workflow Guide for the full schema, parallel steps, and rule condition types.

Workflow files live in workflows/ as the official directory name.

When the same workflow name exists in multiple locations, TAKT resolves in this order: .takt/workflows/ → ~/.takt/workflows/ → builtins.

Recommended Workflows

Workflow	Use Case
default	Standard development workflow. Test-first with AI antipattern review and parallel review (architecture + supervisor).
frontend	Frontend development workflow.
backend	Backend development workflow.
dual	Combined frontend + backend workflow.
takt-default	The workflow used to develop TAKT itself. Directly applicable to other CLI tool development.
*-mini series	Lightweight variants of each workflow (default-mini / frontend-mini / backend-mini / dual-mini). Omits write_tests.

See the Builtin Catalog for all workflows and personas.

Key Commands

Command	Description
takt	Talk to AI, refine requirements, execute or queue tasks
takt run	Execute all pending tasks
takt list	Manage task branches (merge, retry, requeue, force-fail, instruct, delete)
takt #N	Execute GitHub Issue as task
takt eject	Copy builtin workflows/facets for customization
takt workflow init	Create a new workflow scaffold
takt workflow doctor	Validate workflow definitions
takt repertoire add	Install a repertoire package from GitHub

See the CLI Reference for all commands and options.

Configuration

Minimal ~/.takt/config.yaml:

provider: claude    # claude, claude-sdk, codex, opencode, cursor, or copilot
model: sonnet       # passed directly to provider
language: en        # en or ja

Or use API keys directly (no CLI installation required for Claude, Codex, OpenCode):

export TAKT_ANTHROPIC_API_KEY=sk-ant-...   # Anthropic (Claude)
export TAKT_OPENAI_API_KEY=sk-...          # OpenAI (Codex)
export TAKT_OPENCODE_API_KEY=...           # OpenCode
export TAKT_CURSOR_API_KEY=...             # Cursor Agent (optional if logged in)
export TAKT_COPILOT_GITHUB_TOKEN=ghp_...   # GitHub Copilot CLI

See the Configuration Guide for all options, provider profiles, and model resolution.

Customization

Custom workflows

takt workflow init my-flow   # Create a new workflow scaffold
takt workflow doctor my-flow # Validate a workflow definition
takt eject default           # Copy builtin workflow to ~/.takt/workflows/ and edit

Custom personas

Create a Markdown file in ~/.takt/personas/:

# ~/.takt/personas/my-reviewer.md
You are a code reviewer specialized in security.

Reference it in your workflow: persona: my-reviewer

See the Workflow Guide for details. The list of builtin personas is in the Builtin Catalog.

CI/CD

TAKT provides takt-action for GitHub Actions:

- uses: nrslib/takt-action@main
  with:
    anthropic_api_key: ${{ secrets.TAKT_ANTHROPIC_API_KEY }}
    github_token: ${{ secrets.GITHUB_TOKEN }}

For other CI systems, use pipeline mode:

takt --pipeline --task "Fix the bug" --auto-pr

See the CI/CD Guide for full setup instructions.

Project Structure

~/.takt/                    # Global config
├── config.yaml             # Provider, model, language, etc.
├── workflows/              # User workflow definitions
├── facets/                 # User facets (personas, policies, knowledge, etc.)
└── repertoire/             # Installed repertoire packages

.takt/                      # Project-level
├── config.yaml             # Project config
├── workflows/              # Project workflow overrides
├── facets/                 # Project facets
├── tasks.yaml              # Pending tasks
├── tasks/                  # Task specifications
└── runs/                   # Execution reports, logs, context

Workflow definitions are stored under workflows/.

Adopting Spec-Driven Development

TAKT enforces phase transitions declaratively as a YAML state machine, formalizes the artifact of each phase with output contracts, and routes deviations back via parallel review and fix loops. This structure is particularly well-suited for users who follow Spec-Driven Development (SDD) and keep the spec at the center of the process. Once the spec is well-defined, the AI cannot silently skip a phase, drop an acceptance criterion, or claim "done" without passing the verification gate.

For users who want to adopt SDD, the community provides j5ik2o/takt-sdd as a ready-made implementation. It ships pieces for Requirements → Gap Analysis → Design → Tasks → Implementation → Validation, plus an OpenSpec-style change-proposal flow. Install in one command:

npx create-takt-sdd

See External Integrations for other community integrations.

Documentation

Document	Description
CLI Reference	All commands and options
Configuration	Global and project settings
Workflow Guide	Creating and customizing workflows
Builtin Catalog	All builtin workflows and personas
Faceted Prompting	Prompt design methodology
Repertoire Packages	Installing and sharing packages
Task Management	Task queuing, execution, isolation
CI/CD Integration	GitHub Actions and pipeline mode
External Integrations	Community examples that extend TAKT without modifying core (audit trails, etc.)
Changelog (日本語)	Version history

Community

Join the TAKT Discord for questions, discussions, and updates.

Contributing

See CONTRIBUTING.md for details.

License

MIT — See LICENSE for details.