# Run a task (will prompt for workflow selection and optional isolated clone)
takt "Add a login feature"

# Add a task to the queue
takt /add-task "Fix the login bug"

# Run all pending tasks
takt /run-tasks

# Watch for tasks and auto-execute
takt /watch

# Review task branches (merge or delete)
takt /review-tasks

# Switch workflow
takt /switch

Commands

Command	Alias	Description
`takt "task"`		Execute task with current workflow (continues session)
`takt -r "task"`		Execute task, resuming previous session
`takt /run-tasks`	`/run`	Run all pending tasks from `.takt/tasks/`
`takt /watch`		Watch `.takt/tasks/` and auto-execute tasks (stays resident)
`takt /add-task`	`/add`	Add a new task interactively (YAML format, multiline supported)
`takt /review-tasks`	`/review`	Review task branches (try merge, merge & cleanup, or delete)
`takt /switch`		Switch workflow interactively
`takt /clear`		Clear agent conversation sessions
`takt /refresh-builtin`		Update builtin agents/workflows to latest version
`takt /config`		Display current configuration
`takt /help`		Show help

Workflows

TAKT uses YAML-based workflow definitions. Place them in:

~/.takt/workflows/*.yaml

Example Workflow

name: default
max_iterations: 10

steps:
  - name: plan
    agent: planner
    provider: claude         # Optional: claude or codex
    model: opus              # Claude: opus/sonnet/haiku, Codex: gpt-5.2-codex/gpt-5.1-codex
    instruction_template: |
      {task}
    transitions:
      - condition: done
        next_step: implement

  - name: implement
    agent: coder
    provider: codex
    model: gpt-5.2-codex     # Codex model example
    instruction_template: |
      {task}
    transitions:
      - condition: done
        next_step: review
      - condition: blocked
        next_step: ABORT

  - name: review
    agent: architect
    model: sonnet            # Model alias (no provider = uses global default)
    transitions:
      - condition: approved
        next_step: COMPLETE
      - condition: rejected
        next_step: implement

Built-in Workflows

TAKT ships with several built-in workflows:

Workflow	Description
`default`	Full development workflow: plan → implement → architect review → AI review → security review → supervisor approval. Includes fix loops for each review stage.
`simple`	Simplified version of default: plan → implement → architect review → AI review → supervisor. No intermediate fix steps.
`research`	Research workflow: planner → digger → supervisor. Autonomously researches topics without asking questions.
`expert-review`	Comprehensive review with domain experts: CQRS+ES, Frontend, AI, Security, QA reviews with fix loops.
`magi`	Deliberation system inspired by Evangelion. Three AI personas (MELCHIOR, BALTHASAR, CASPER) analyze and vote.

Switch between workflows with takt /switch.

Built-in Agents

coder - Implements features and fixes bugs
architect - Reviews code and provides feedback
supervisor - Final verification and approval
planner - Task analysis and implementation planning
ai-reviewer - AI-generated code quality review
security - Security vulnerability assessment

Custom Agents

Define custom agents in .takt/agents.yaml:

agents:
  - name: my-reviewer
    prompt_file: .takt/prompts/reviewer.md
    allowed_tools: [Read, Glob, Grep]
    provider: claude             # Optional: claude or codex
    model: opus                  # Claude: opus/sonnet/haiku or full name (claude-opus-4-5-20251101)
    status_patterns:
      approved: "\\[APPROVE\\]"
      rejected: "\\[REJECT\\]"

  - name: my-codex-agent
    prompt_file: .takt/prompts/analyzer.md
    provider: codex
    model: gpt-5.2-codex         # Codex: gpt-5.2-codex, gpt-5.1-codex, etc.

Model Selection

Claude Models

You can specify models using either aliases or full model names:

Aliases (recommended for simplicity):

opus - Claude Opus 4.5 (highest reasoning capability)
sonnet - Claude Sonnet 4.5 (balanced, best for most tasks)
haiku - Claude Haiku 4.5 (fast and efficient)
opusplan - Opus for planning, Sonnet for execution
default - Recommended model for your account type

Full model names (recommended for production):

claude-opus-4-5-20251101
claude-sonnet-4-5-20250929
claude-haiku-4-5-20250101

Codex Models

Available Codex models:

gpt-5.2-codex - Latest agentic coding model (default)
gpt-5.1-codex - Previous generation
gpt-5.1-codex-max - Optimized for long-running tasks
gpt-5.1-codex-mini - Smaller, cost-effective version
codex-1 - Specialized model aligned with coding preferences

Project Structure

~/.takt/
├── config.yaml          # Global config (provider, model, workflows, etc.)
├── workflows/           # Workflow definitions
└── agents/              # Agent prompt files

.takt/                   # Project-level config
├── agents.yaml          # Custom agent definitions
├── tasks/               # Pending task files (.yaml, .md)
├── completed/           # Completed tasks with reports
├── worktree-meta/       # Metadata for task branches
├── reports/             # Execution reports (auto-generated)
└── logs/                # Session logs (incremental)
    ├── latest.json      # Pointer to current/latest session
    ├── previous.json    # Pointer to previous session
    └── {sessionId}.json # Full session log per workflow run

Global Configuration

Configure default provider and model in ~/.takt/config.yaml:

# ~/.takt/config.yaml
language: en
default_workflow: default
log_level: info
provider: claude         # Default provider: claude or codex
model: sonnet            # Default model (optional)
trusted_directories:
  - /path/to/trusted/dir

Model Resolution Priority:

Workflow step model (highest priority)
Custom agent model
Global config model
Provider default (Claude: sonnet, Codex: gpt-5.2-codex)

Practical Usage Guide

Resuming Sessions with `-r`

When TAKT prompts for additional input during execution (e.g., "Please provide more details"), use the -r flag to continue the conversation:

# First run - agent might ask for clarification
takt "Fix the login bug"

# Resume the same session to provide the requested information
takt -r "The bug occurs when the password contains special characters"

The -r flag preserves the agent's conversation history, allowing for natural back-and-forth interaction.

Interactive Workflow

When running takt "task", you are prompted to:

Select a workflow - Choose from available workflows (arrow keys, ESC to cancel)
Create an isolated clone (optional) - Optionally run the task in a git clone --shared for isolation

This interactive flow ensures each task runs with the right workflow and isolation level.

Adding Custom Workflows

Create your own workflow by adding YAML files to ~/.takt/workflows/:

# ~/.takt/workflows/my-workflow.yaml
name: my-workflow
description: My custom workflow

max_iterations: 5

steps:
  - name: analyze
    agent: ~/.takt/agents/my-agents/analyzer.md
    instruction_template: |
      Analyze this request: {task}
    transitions:
      - condition: done
        next_step: implement

  - name: implement
    agent: ~/.takt/agents/default/coder.md
    instruction_template: |
      Implement based on the analysis: {previous_response}
    pass_previous_response: true
    transitions:
      - condition: done
        next_step: COMPLETE

Specifying Agents by Path

Agents are specified using file paths in workflow definitions:

# Use built-in agents
agent: ~/.takt/agents/default/coder.md
agent: ~/.takt/agents/magi/melchior.md

# Use project-local agents
agent: ./.takt/agents/my-reviewer.md

# Use absolute paths
agent: /path/to/custom/agent.md

Create custom agent prompts as Markdown files:

# ~/.takt/agents/my-agents/reviewer.md

You are a code reviewer focused on security.

## Your Role
- Check for security vulnerabilities
- Verify input validation
- Review authentication logic

## Output Format
- [REVIEWER:APPROVE] if code is secure
- [REVIEWER:REJECT] if issues found (list them)

Task Management

TAKT supports batch task processing through task files in .takt/tasks/. Both .yaml/.yml and .md file formats are supported.

Adding Tasks with `/add-task`

# Quick add (no isolation)
takt /add-task "Add authentication feature"

# Interactive mode (prompts for isolation, branch, workflow options)
takt /add-task

Task File Formats

YAML format (recommended, supports worktree/branch/workflow options):

# .takt/tasks/add-auth.yaml
task: "Add authentication feature"
worktree: true                  # Run in isolated shared clone
branch: "feat/add-auth"         # Branch name (auto-generated if omitted)
workflow: "default"             # Workflow override (uses current if omitted)

Markdown format (simple, backward compatible):

# .takt/tasks/add-login-feature.md

Add a login feature to the application.

Requirements:
- Username and password fields
- Form validation
- Error handling for failed attempts

Isolated Execution (Shared Clone)

YAML task files can specify worktree to run each task in an isolated git clone --shared, keeping the main working directory clean:

worktree: true - Auto-create a shared clone in a sibling directory (or worktree_dir from config)
worktree: "/path/to/dir" - Create at specified path
branch: "feat/xxx" - Use specified branch (auto-generated as takt/{timestamp}-{slug} if omitted)
Omit worktree - Run in current working directory (default)

Note

: The YAML field is named worktree for backward compatibility. Internally, git clone --shared is used instead of git worktree because git worktrees have a .git file with gitdir: that points back to the main repository, causing Claude Code to recognize the main repo as the project root. Shared clones have an independent .git directory that avoids this issue.

Clones are ephemeral. When a task completes successfully, TAKT automatically commits all changes and pushes the branch to the main repository, then deletes the clone. Use takt /review-tasks to review, try-merge, or delete task branches.

Running Tasks with `/run-tasks`

takt /run-tasks

Tasks are executed in alphabetical order (use prefixes like 001-, 002- for ordering)
Completed tasks are moved to .takt/completed/ with execution reports
New tasks added during execution will be picked up dynamically

Watching Tasks with `/watch`

takt /watch

Watch mode polls .takt/tasks/ for new task files and auto-executes them as they appear. The process stays resident until Ctrl+C. This is useful for:

CI/CD pipelines that generate task files
Automated workflows where tasks are added by external processes
Long-running development sessions where tasks are queued over time

Reviewing Task Branches with `/review-tasks`

takt /review-tasks

Lists all takt/-prefixed branches with file change counts. For each branch you can:

Try merge - Squash merge into main (stage changes without committing)
Instruct - Give additional instructions via a temporary clone
Merge & cleanup - Merge and delete the branch
Delete - Delete the branch without merging

Session Logs

TAKT writes session logs incrementally to .takt/logs/. Logs are saved at workflow start, after each step, and at workflow end — so even if the process crashes mid-execution, partial logs are preserved.

.takt/logs/latest.json - Pointer to the current (or most recent) session
.takt/logs/previous.json - Pointer to the previous session
.takt/logs/{sessionId}.json - Full session log with step history

Agents can read previous.json to pick up context from a prior run (e.g., when resuming with takt "続けて").

Workflow Variables

Available variables in instruction_template:

Variable	Description
`{task}`	Original user request
`{iteration}`	Workflow-wide turn count (total steps executed)
`{max_iterations}`	Maximum iterations allowed
`{step_iteration}`	Per-step iteration count (how many times THIS step has run)
`{previous_response}`	Previous step's output (requires `pass_previous_response: true`)
`{user_inputs}`	Additional user inputs during workflow
`{git_diff}`	Current git diff (uncommitted changes)
`{report_dir}`	Report directory name (e.g., `20250126-143052-task-summary`)

Designing Workflows

Each workflow step requires three key elements:

1. Agent - A Markdown file containing the system prompt:

agent: ~/.takt/agents/default/coder.md    # Path to agent prompt file
agent_name: coder                          # Display name (optional)

2. Status Rules - Define how the agent signals completion. Agents output status markers like [CODER:DONE] or [ARCHITECT:REJECT] that TAKT detects to drive transitions:

status_rules_prompt: |
  Your final output MUST include a status tag:
  - `[CODER:DONE]` if implementation is complete
  - `[CODER:BLOCKED]` if you cannot proceed

3. Transitions - Route to the next step based on status:

transitions:
  - condition: done        # Maps to status tag DONE
    next_step: review      # Go to review step
  - condition: blocked     # Maps to status tag BLOCKED
    next_step: ABORT       # End workflow with failure

Available transition conditions: done, blocked, approved, rejected, improve, answer, always. Special next_step values: COMPLETE (success), ABORT (failure).

Step options:

Option	Default	Description
`pass_previous_response`	`true`	Pass previous step's output to `{previous_response}`
`on_no_status`	-	Behavior when no status is detected: `complete`, `continue`, `stay`
`allowed_tools`	-	List of tools the agent can use (Read, Glob, Grep, Edit, Write, Bash, etc.)
`provider`	-	Override provider for this step (`claude` or `codex`)
`model`	-	Override model for this step
`permission_mode`	`default`	Permission mode: `default`, `acceptEdits`, or `bypassPermissions`

API Usage

import { WorkflowEngine, loadWorkflow } from 'takt';  // npm install takt

const config = loadWorkflow('default');
if (!config) {
  throw new Error('Workflow not found');
}
const engine = new WorkflowEngine(config, process.cwd(), 'My task');

engine.on('step:complete', (step, response) => {
  console.log(`${step.name}: ${response.status}`);
});

await engine.run();

Disclaimer

This project is a personal project developed at my own pace.

Response times: I may not be able to respond to issues immediately
Development style: This project is primarily developed using "vibe coding" (AI-assisted development) - use at your own risk
Pull requests:
- Small, focused PRs (bug fixes, typos, docs) are welcome
- Large PRs, especially AI-generated bulk changes, are difficult to review

See CONTRIBUTING.md for more details.

Docker Support

Docker environment is provided for testing in other environments:

# Build Docker images
docker compose build

# Run tests in container
docker compose run --rm test

# Run lint in container
docker compose run --rm lint

# Build only (skip tests)
docker compose run --rm build

This ensures the project works correctly in a clean Node.js 20 environment.

Documentation

Workflow Guide - Create and customize workflows
Agent Guide - Configure custom agents
Changelog - Version history
Security Policy - Vulnerability reporting
Blog: TAKT - AI Agent Orchestration - Design philosophy and practical usage guide (Japanese)

License

MIT - See LICENSE for details.

README.md

TAKT

Requirements

Installation

Quick Start