takt/docs/configuration.md

Configuration

日本語

This document is a reference for all TAKT configuration options. For a quick start, see the main README.

Global Configuration

Configure TAKT defaults in ~/.takt/config.yaml. This file is created automatically on first run. All fields are optional.

# ~/.takt/config.yaml
language: en                  # UI language: 'en' or 'ja'
default_piece: default        # Default piece for new projects
logging:
  level: info                 # Log level: debug, info, warn, error
provider: claude              # Default provider: claude, codex, opencode, cursor, or copilot
model: sonnet                 # Default model (optional, passed to provider as-is)
branch_name_strategy: romaji  # Branch name generation: 'romaji' (fast) or 'ai' (slow)
prevent_sleep: false          # Prevent macOS idle sleep during execution (caffeinate)
notification_sound: true      # Enable/disable notification sounds
notification_sound_events:    # Optional per-event toggles
  iteration_limit: false
  piece_complete: true
  piece_abort: true
  run_complete: true          # Enabled by default; set false to disable
  run_abort: true             # Enabled by default; set false to disable
concurrency: 1                # Parallel task count for takt run (1-10, default: 1 = sequential)
task_poll_interval_ms: 500    # Polling interval for new tasks during takt run (100-5000, default: 500)
interactive_preview_movements: 3  # Movement previews in interactive mode (0-10, default: 3)
# auto_fetch: false            # Fetch remote before cloning (default: false)
# base_branch: main            # Base branch for clone creation (default: remote default branch)

# Runtime environment defaults (applies to all pieces unless piece_config.runtime overrides)
# runtime:
#   prepare:
#     - gradle    # Prepare Gradle cache/config in .runtime/
#     - node      # Prepare npm cache in .runtime/

# Per-persona provider/model overrides (optional)
# Route specific personas to different providers and models without duplicating pieces
# persona_providers:
#   coder:
#     provider: codex        # Run coder on Codex
#     model: o3-mini         # Use o3-mini model (optional)
#   ai-antipattern-reviewer:
#     provider: claude       # Keep reviewers on Claude

# Provider-specific permission profiles (optional)
# Priority: project override > global override > project default > global default > required_permission_mode (floor)
# provider_profiles:
#   codex:
#     default_permission_mode: full
#     movement_permission_overrides:
#       ai_review: readonly
#   claude:
#     default_permission_mode: edit

# API Key configuration (optional)
# Can be overridden by environment variables TAKT_ANTHROPIC_API_KEY / TAKT_OPENAI_API_KEY / TAKT_OPENCODE_API_KEY / TAKT_CURSOR_API_KEY / TAKT_COPILOT_GITHUB_TOKEN
# anthropic_api_key: sk-ant-...  # For Claude (Anthropic)
# openai_api_key: sk-...         # For Codex (OpenAI)
# opencode_api_key: ...          # For OpenCode
# cursor_api_key: ...            # For Cursor Agent (optional; login session fallback is also supported)
# copilot_github_token: ...      # For Copilot (GitHub token)

# CLI path overrides (optional)
# Override provider CLI binaries (must be absolute paths to executable files)
# Can be overridden by environment variables TAKT_CLAUDE_CLI_PATH / TAKT_CODEX_CLI_PATH / TAKT_CURSOR_CLI_PATH / TAKT_COPILOT_CLI_PATH
# claude_cli_path: /usr/local/bin/claude
# codex_cli_path: /usr/local/bin/codex
# cursor_cli_path: /usr/local/bin/cursor-agent
# copilot_cli_path: /usr/local/bin/github-copilot-cli

# Builtin piece filtering (optional)
# builtin_pieces_enabled: true           # Set false to disable all builtins
# disabled_builtins: [magi]              # Disable specific builtin pieces

# Pipeline execution configuration (optional)
# Customize branch names, commit messages, and PR body.
# pipeline:
#   default_branch_prefix: "takt/"
#   commit_message_template: "feat: {title} (#{issue})"
#   pr_body_template: |
#     ## Summary
#     {issue_body}
#     Closes #{issue}

Global Config Field Reference

Field	Type	Default	Description
language	"en" | "ja"	"en"	UI language
default_piece	string	"default"	Default piece for new projects
logging.level	"debug" | "info" | "warn" | "error"	"info"	Log level
provider	"claude" | "codex" | "opencode" | "cursor" | "copilot"	"claude"	Default AI provider
model	string	-	Default model name (passed to provider as-is)
branch_name_strategy	"romaji" | "ai"	"romaji"	Branch name generation strategy
prevent_sleep	boolean	false	Prevent macOS idle sleep (caffeinate)
notification_sound	boolean	true	Enable notification sounds
notification_sound_events	object	-	Per-event notification sound toggles
concurrency	number (1-10)	1	Parallel task count for takt run
task_poll_interval_ms	number (100-5000)	500	Polling interval for new tasks
interactive_preview_movements	number (0-10)	3	Movement previews in interactive mode
worktree_dir	string	-	Directory for shared clones (defaults to ../{clone-name})
auto_pr	boolean	-	Auto-create PR after worktree execution
verbose	boolean	-	Verbose output mode
minimal_output	boolean	false	Suppress AI output (for CI)
runtime	object	-	Runtime environment defaults (e.g., prepare: [gradle, node])
persona_providers	object	-	Per-persona provider/model overrides (e.g., coder: { provider: codex, model: o3-mini })
provider_options	object	-	Global provider-specific options
provider_profiles	object	-	Provider-specific permission profiles
anthropic_api_key	string	-	Anthropic API key for Claude
openai_api_key	string	-	OpenAI API key for Codex
opencode_api_key	string	-	OpenCode API key
cursor_api_key	string	-	Cursor API key (optional; login session fallback supported)
copilot_github_token	string	-	GitHub token for Copilot CLI authentication
codex_cli_path	string	-	Codex CLI binary path override (absolute)
cursor_cli_path	string	-	Cursor Agent CLI binary path override (absolute)
copilot_cli_path	string	-	Copilot CLI binary path override (absolute)
enable_builtin_pieces	boolean	true	Enable builtin pieces
disabled_builtins	string[]	[]	Specific builtin pieces to disable
pipeline	object	-	Pipeline template settings
bookmarks_file	string	-	Path to bookmarks file
auto_fetch	boolean	false	Fetch remote before cloning to keep clones up-to-date
base_branch	string	-	Base branch for clone creation (defaults to remote default branch)
piece_categories_file	string	-	Path to piece categories file

Project Configuration

Configure project-specific settings in .takt/config.yaml. This file is created when you first use TAKT in a project directory.

# .takt/config.yaml
piece: default                # Current piece for this project
provider: claude              # Override provider for this project
model: sonnet                 # Override model for this project
auto_pr: true                 # Auto-create PR after worktree execution
verbose: false                # Verbose output mode
concurrency: 2                # Parallel task count for takt run in this project (1-10)
# base_branch: main           # Base branch for clone creation (overrides global, default: remote default branch)

# Provider-specific options (overrides global, overridden by piece/movement)
# provider_options:
#   codex:
#     network_access: true

# Provider-specific permission profiles (project-level override)
# provider_profiles:
#   codex:
#     default_permission_mode: full
#     movement_permission_overrides:
#       ai_review: readonly

Project Config Field Reference

Field	Type	Default	Description
piece	string	"default"	Current piece name for this project
provider	"claude" | "codex" | "opencode" | "cursor" | "copilot" | "mock"	-	Override provider
model	string	-	Override model name (passed to provider as-is)
auto_pr	boolean	-	Auto-create PR after worktree execution
verbose	boolean	-	Verbose output mode
concurrency	number (1-10)	1 (from global)	Parallel task count for takt run
base_branch	string	-	Base branch for clone creation (overrides global, default: remote default branch)
provider_options	object	-	Provider-specific options
provider_profiles	object	-	Provider-specific permission profiles

Project config values override global config when both are set.

API Key Configuration

TAKT supports five providers. Claude/Codex/OpenCode use API keys, Cursor can use either API key or existing cursor-agent login session, and Copilot uses a GitHub token.

Environment Variables (Recommended)

# For Claude (Anthropic)
export TAKT_ANTHROPIC_API_KEY=sk-ant-...

# For Codex (OpenAI)
export TAKT_OPENAI_API_KEY=sk-...

# For OpenCode
export TAKT_OPENCODE_API_KEY=...

# For Cursor Agent (optional if cursor-agent login session exists)
export TAKT_CURSOR_API_KEY=...

# For GitHub Copilot CLI
export TAKT_COPILOT_GITHUB_TOKEN=ghp_...

Config File

# ~/.takt/config.yaml
anthropic_api_key: sk-ant-...  # For Claude
openai_api_key: sk-...         # For Codex
opencode_api_key: ...          # For OpenCode
cursor_api_key: ...            # For Cursor Agent (optional)
copilot_github_token: ghp_...  # For GitHub Copilot CLI

Priority

Environment variables take precedence over config.yaml settings.

Provider	Environment Variable	Config Key
Claude (Anthropic)	TAKT_ANTHROPIC_API_KEY	anthropic_api_key
Codex (OpenAI)	TAKT_OPENAI_API_KEY	openai_api_key
OpenCode	TAKT_OPENCODE_API_KEY	opencode_api_key
Cursor Agent	TAKT_CURSOR_API_KEY	cursor_api_key
GitHub Copilot CLI	TAKT_COPILOT_GITHUB_TOKEN	copilot_github_token

Security

• If you write API keys in config.yaml, be careful not to commit this file to Git.
• Consider using environment variables instead.
• Add ~/.takt/config.yaml to your global .gitignore if needed.
• Cursor provider can run without API key when cursor-agent login is already configured.
• If you set an API key, installing the corresponding CLI tool (Claude Code, Codex, OpenCode) is not necessary. TAKT directly calls the respective API.
• Copilot provider requires the copilot CLI to be installed. The GitHub token is used for authentication.

CLI Path Overrides

You can override provider CLI binary paths using environment variables or config:

export TAKT_CLAUDE_CLI_PATH=/usr/local/bin/claude
export TAKT_CODEX_CLI_PATH=/usr/local/bin/codex
export TAKT_CURSOR_CLI_PATH=/usr/local/bin/cursor-agent
export TAKT_COPILOT_CLI_PATH=/usr/local/bin/github-copilot-cli

# ~/.takt/config.yaml
claude_cli_path: /usr/local/bin/claude
codex_cli_path: /usr/local/bin/codex
cursor_cli_path: /usr/local/bin/cursor-agent
copilot_cli_path: /usr/local/bin/github-copilot-cli

Provider	Environment Variable	Config Key
Claude	TAKT_CLAUDE_CLI_PATH	claude_cli_path
Codex	TAKT_CODEX_CLI_PATH	codex_cli_path
Cursor Agent	TAKT_CURSOR_CLI_PATH	cursor_cli_path
Copilot	TAKT_COPILOT_CLI_PATH	copilot_cli_path

Paths must be absolute paths to executable files. Environment variables take precedence over config file values. These can also be set at the project level in .takt/config.yaml.

Model Resolution

The model used for each movement is resolved with the following priority order (highest first):

1. Piece movement model - Specified in the movement definition in piece YAML
2. Global config model - Default model in ~/.takt/config.yaml
3. Provider default - Falls back to the provider's built-in default (Claude: sonnet, Codex: codex, OpenCode: provider default, Cursor: CLI default, Copilot: CLI default)

Provider-specific Model Notes

Claude Code supports aliases (opus, sonnet, haiku, opusplan, default) and full model names (e.g., claude-sonnet-4-5-20250929). The model field is passed directly to the provider CLI. Refer to the Claude Code documentation for available models.

Codex uses the model string as-is via the Codex SDK. If unspecified, defaults to codex. Refer to Codex documentation for available models.

OpenCode requires a model in provider/model format (e.g., opencode/big-pickle). Omitting the model for the OpenCode provider will result in a configuration error.

Cursor Agent forwards model directly to cursor-agent --model <model>. If omitted, Cursor CLI default is used.

GitHub Copilot CLI forwards model directly to copilot --model <model>. If omitted, Copilot CLI default is used.

Example

# ~/.takt/config.yaml
provider: claude
model: opus     # Default model for all movements (unless overridden)

# piece.yaml - movement-level override takes highest priority
movements:
  - name: plan
    model: opus       # This movement uses opus regardless of global config
    ...
  - name: implement
    # No model specified - falls back to global config (opus)
    ...

Provider Profiles

Provider profiles allow you to set default permission modes and per-movement permission overrides for each provider. This is useful when running different providers with different security postures.

Permission Modes

TAKT uses three provider-independent permission modes:

Mode	Description	Claude	Codex	OpenCode	Cursor Agent	Copilot
readonly	Read-only access, no file modifications	default	read-only	read-only	default flags (no --force)	no permission flags
edit	Allow file edits with confirmation	acceptEdits	workspace-write	workspace-write	default flags (no --force)	--allow-all-tools --no-ask-user
full	Bypass all permission checks	bypassPermissions	danger-full-access	danger-full-access	--force	--yolo

Configuration

Provider profiles can be set at both global and project levels:

# ~/.takt/config.yaml (global) or .takt/config.yaml (project)
provider_profiles:
  codex:
    default_permission_mode: full
    movement_permission_overrides:
      ai_review: readonly
  claude:
    default_permission_mode: edit
    movement_permission_overrides:
      implement: full

Permission Resolution Priority

Permission mode is resolved in the following order (first match wins):

1. Project provider_profiles.<provider>.movement_permission_overrides.<movement>
2. Global provider_profiles.<provider>.movement_permission_overrides.<movement>
3. Project provider_profiles.<provider>.default_permission_mode
4. Global provider_profiles.<provider>.default_permission_mode
5. Movement required_permission_mode (acts as a minimum floor)

The required_permission_mode on a movement sets the minimum floor. If the resolved mode from provider profiles is lower than the required mode, the required mode is used instead. For example, if a movement requires edit but the profile resolves to readonly, the effective mode will be edit.

Persona Providers

Route specific personas to different providers and models without duplicating pieces:

# ~/.takt/config.yaml
persona_providers:
  coder:
    provider: codex        # Run coder persona on Codex
    model: o3-mini         # Use o3-mini model (optional)
  ai-antipattern-reviewer:
    provider: claude       # Keep reviewers on Claude

Both provider and model are optional. model resolution priority: movement YAML model > persona_providers[persona].model > global model.

This allows mixing providers and models within a single piece. The persona name is matched against the persona key in the movement definition.

Piece Categories

Organize pieces into categories for better UI presentation in takt switch and piece selection prompts.

Configuration

Categories can be configured in:

• builtins/{lang}/piece-categories.yaml - Default builtin categories
• ~/.takt/config.yaml or a separate categories file specified by piece_categories_file

# ~/.takt/config.yaml or dedicated categories file
piece_categories:
  Development:
    pieces: [default, simple]
    children:
      Backend:
        pieces: [dual-cqrs]
      Frontend:
        pieces: [dual]
  Research:
    pieces: [research, magi]

show_others_category: true         # Show uncategorized pieces (default: true)
others_category_name: "Other Pieces"  # Name for uncategorized category

Category Features

• Nested categories - Unlimited depth for hierarchical organization
• Per-category piece lists - Assign pieces to specific categories
• Others category - Automatically collects uncategorized pieces (can be disabled via show_others_category: false)
• Builtin piece filtering - Disable all builtins via enable_builtin_pieces: false, or selectively via disabled_builtins: [name1, name2]

Resetting Categories

Reset piece categories to builtin defaults:

takt reset categories

Pipeline Templates

Pipeline mode (--pipeline) supports customizable templates for branch names, commit messages, and PR bodies.

Configuration

# ~/.takt/config.yaml
pipeline:
  default_branch_prefix: "takt/"
  commit_message_template: "feat: {title} (#{issue})"
  pr_body_template: |
    ## Summary
    {issue_body}
    Closes #{issue}

Template Variables

Variable	Available In	Description
{title}	Commit message	Issue title
{issue}	Commit message, PR body	Issue number
{issue_body}	PR body	Issue body
{report}	PR body	Piece execution report

Pipeline CLI Options

Option	Description
--pipeline	Enable pipeline (non-interactive) mode
--auto-pr	Create PR after execution
--skip-git	Skip branch creation, commit, and push (piece-only)
--repo <owner/repo>	Repository for PR creation
-q, --quiet	Minimal output mode (suppress AI output)

Debugging

Debug Logging

Enable debug logging by setting logging.debug: true in ~/.takt/config.yaml:

logging:
  debug: true

Debug logs are written to .takt/runs/debug-{timestamp}/logs/debug.log in NDJSON format.

Verbose Mode

Set verbose: true in your config:

# ~/.takt/config.yaml or .takt/config.yaml
verbose: true

You can also force verbose output via environment variable:

TAKT_VERBOSE=true

This also enables logging.debug, logging.trace, and sets logging.level to debug.