| English | 日本語 | 简体中文 |
TAKT provides a task management workflow for accumulating multiple tasks and executing them in batch. The basic flow is:
takt add – Refine task requirements through AI conversation and save to .takt/tasks.yamlorder.md files, attach reference materialstakt run – Execute all pending tasks at once (sequential or parallel)takt list – Review results, merge branches, retry failures, or add instructionsEach task executes in an isolated clone (optional), produces reports, and creates a branch that can be merged or discarded via takt list.
takt add)Use takt add to create a new task entry in .takt/tasks.yaml.
# Add a task with inline text
takt add "Implement user authentication"
# Add a task from a GitHub Issue
takt add '#28'
takt add --issue 28
When adding a task, you are prompted for:
main/master, whether to use it as the base branchtakt/{timestamp}-{slug})Create as draft?)When you pass an issue reference (e.g., #28), TAKT fetches the issue title, body, labels, and comments via the GitHub CLI (gh) and uses them as the task content. The issue number is recorded in tasks.yaml and reflected in the branch name.
Requirement: GitHub CLI (gh) must be installed and authenticated.
takt add --pr N and takt add --issue N (also takt add '#N') download GitHub attachment images referenced by Markdown image syntax or HTML <img src> in PR descriptions, conversation comments, review summaries, review thread comments, and Issue bodies and comments. Pipeline supports both --pr N and --issue N.
Successful images are saved under .takt/tasks/<slug>/attachments/ as image-N.png or the corresponding format extension. Duplicate URLs share one file. Numbers follow the first appearance of successfully downloaded and saved images without gaps. The original image syntax remains intact, with [Image #N] added immediately after it. An existing-format ## 添付画像 list is appended to order.md.
During execution, images are copied to the execution directory’s .takt/runs/<run-slug>/context/task/attachments/, and the accompanying order.md references those paths. Pipeline removes its temporary task spec after execution while retaining the run’s images and instruction file.
PNG, JPEG, GIF, and WebP are supported, up to 10 MiB per image. Both Content-Type and magic bytes are checked. External images outside GitHub attachments, code examples, and HTML comments are ignored. Authentication failures, 404 responses, network errors, excessive sizes, and invalid formats produce an image-specific warning and skip; task registration and pipeline execution continue. Failed references receive no placeholder.
Retrieval prioritizes authenticated gh credentials. Private repository attachments may be inaccessible with token authentication in some environments; successful retrieval is not guaranteed. Browser cookies are not used. GitLab attachments and ordinary text input are outside automatic retrieval.
You can also save tasks from interactive mode. After refining requirements through conversation, use /go, review the instruction preview, and select Save as Task to persist the task to tasks.yaml.
Loading Issue #N provides conversation context. Each /go judges whether the latest task is work on that Issue. A related instruction shows Issue: #N immediately after its task heading; only that binding supplies N to execution, task saving, or Issue creation. Saved tasks use N in issue, generated branches (takt/N/{slug}), and PR bodies (Closes #N). Unrelated instructions omit the binding. Choose Continue editing to correct it. /issue replaces the context for subsequent judgments. When Create Issue creates M from an instruction bound to N, the saved task remains bound to N and a link to M is commented on N; without a binding, the task uses the newly created M.
CLI, TUI, and MCP registration allows multiple pending or running tasks for the same Issue, PR, or branch without an extra warning or confirmation. Only workflow automatic enqueue rejects active same-target duplicates under the storage lock. Direct takt add '#N' still records N without requiring an instruction binding line.
Automatically generated branch names are checked against local refs, remote-tracking refs, all configured remotes (including branches not yet fetched), and ownership metadata for other task clones. Collisions use checked suffixes (-2, -3, …) and create a new branch from the base. If ownership publication races with another creator, the new clone’s branch is renamed and published without replacing existing metadata. A query or storage failure stops creation. Explicit branch names retain the existing fetch and reuse behavior.
In ordinary interactive mode, press Escape at any worktree-settings prompt after selecting Save as Task to cancel that save and return to the action menu. The confirmed instruction and its attachments stay in the same conversation. Selecting Save as Task again starts the settings questions from the beginning without reusing answers from the cancelled attempt.
MCP clients can use the takt-mcp stdio server to save pending tasks, inspect task/run state, and send additional instructions to running worktree-clone tasks without invoking shell commands. takt_enqueue_task writes a pending record to .takt/tasks.yaml; takt_list_tasks returns compact summaries, takt_get_run reads one run’s details, and takt_tell_run rechecks and writes only to a running clone. If saving fails after issue creation and the issue number was resolved, the issue remains open and the MCP error result returns its number for retry. If number extraction fails, the result can provide the issue URL instead. The tools require an absolute cwd inside the server’s allowed project root; enqueue and tell also require non-empty task content. Use takt run to execute pending tasks or takt watch to monitor and execute them continuously. See CLI Reference for setup and tool input details.
The ordinary assistant conversation receives only the read-only task-state tools when its provider supports MCP. Use /go for a new task, /tell to select, review, and confirm an additional instruction for a running worktree clone, or /requeue and /retry to return a failed task to the queue. A provider without MCP support keeps the conversation available but cannot look up task state.
TAKT stores task metadata in .takt/tasks.yaml and each task’s detailed specification in .takt/tasks/{slug}/.
tasks.yaml Schematasks:
- name: add-auth-feature
status: pending
task_dir: .takt/tasks/20260201-015714-implement-user-authentication
workflow: default
created_at: "2026-02-01T01:57:14.000Z"
started_at: null
completed_at: null
Fields:
| Field | Description |
|---|---|
name |
AI-generated task slug |
status |
pending, running, completed, failed, exceeded, or pr_failed (workflow succeeded but PR creation/push failed) |
task_dir |
Path to the task directory containing order.md |
workflow |
Workflow name to use for execution |
worktree |
true (auto), a path string, or omitted (run in current directory) |
branch |
Branch name (auto-generated if omitted) |
base_branch |
Base branch for the clone and PR (set when chosen at takt add) |
auto_pr |
Whether to auto-create a PR after execution |
draft_pr |
Whether the auto-created PR is opened as a draft |
issue |
Issue number from the configured issue provider (if applicable) |
run_slug |
Slug of the latest run directory under .takt/runs/ |
failure |
Failure details (step, error, last_message) recorded for failed tasks |
created_at |
ISO 8601 timestamp |
started_at |
ISO 8601 timestamp (set when execution begins) |
completed_at |
ISO 8601 timestamp (set when execution finishes) |
tasks.yaml may also contain additional fields (slug, source_run_slug, resume_mode, owner_pid, auto_requeue_count, exceeded_*, etc.) that TAKT manages internally.
.takt/
tasks/
20260201-015714-implement-user-authentication/
order.md # Task specification (auto-generated, editable)
schema.sql # Attached reference materials (optional)
wireframe.png # Attached reference materials (optional)
tasks.yaml # Task metadata records
runs/
20260201-020152-implement-user-authentication-x7k2pq/
reports/ # Execution reports (auto-generated)
logs/ # NDJSON session logs
context/ # Snapshots (previous_responses, etc.)
operations/ # Operation journal (journal.json)
meta.json # Run metadata
The run directory slug is generated separately for each execution by appending a random 6-character suffix, so it differs from the task directory slug. To locate a task’s run directory, check the run_slug field in tasks.yaml or the newest directory under .takt/runs/.
takt add creates .takt/tasks/{slug}/order.md automatically and saves the task_dir reference to tasks.yaml. You can freely edit order.md and add supplementary files (SQL schemas, wireframes, API specs, etc.) to the task directory before execution.
takt run)Execute all pending tasks from .takt/tasks.yaml:
takt run
# Ignore workflow max_steps and continue until another stop condition occurs
takt run --ignore-exceed
The run command claims pending tasks and executes them through the configured workflow. Each task goes through:
worktree is set)auto_pr is set)tasks.yaml (completed, failed, or exceeded)When a workflow reaches max_steps, the default takt run behavior stops the task with exceeded status and saves retry metadata such as exceeded_max_steps, exceeded_current_iteration, and resume_point. Passing --ignore-exceed makes takt run ignore only that iteration limit, continue the workflow, and skip writing exceeded retry metadata.
MCP clients can enqueue tasks, inspect task/run state, and send additional instructions to running clone tasks. Use takt run to execute pending tasks or takt watch for continuous monitoring and execution.
Both takt run and takt watch use the same worker pool and run sequentially by default (concurrency: 1). Configure parallel execution in ~/.takt/config.yaml:
concurrency: 3 # Concurrent tasks in takt run / takt watch (1-10)
task_poll_interval_ms: 500 # Task polling in takt run / takt watch (100-5000ms)
When concurrency is greater than 1, TAKT uses a worker pool that:
If takt run is interrupted (e.g., process crash, Ctrl+C), tasks left in running status are automatically marked as failed on the next takt run or takt watch invocation. Requeue them explicitly to run them again.
When auto_requeue_max_attempts is set, takt run and takt watch requeue eligible failed workflow tasks once at startup and after execution failures, up to the saved attempt limit. Watch does not repeat the startup scan while resident; after SIGINT, it neither claims nor requeues tasks. Both commands pause task claims while waiting for user input. The default is 0 (manual requeue only). See the Configuration Guide for details.
takt watch)Run a resident process that monitors .takt/tasks.yaml and auto-executes tasks as they appear:
takt watch
# Ignore workflow max_steps and continue until another stop condition occurs
takt watch --ignore-exceed
The watch command:
tasks.yaml for new pending tasksconcurrencytask_poll_interval_ms (default: 500ms)running tasks as failed on startupThis is useful for a “producer-consumer” workflow where you add tasks with takt add in one terminal and let takt watch execute them automatically in another.
takt list)List and manage task branches interactively:
takt list
The list view shows all tasks organized by status (pending, running, completed, failed, exceeded, pr_failed) with creation dates and summaries. Selecting a task shows available actions depending on its status. The bottom of the list also has an All Delete entry that deletes all tasks at once.
| Action | Description |
|---|---|
| View diff | Show full diff against the default branch in a pager |
| Instruct | Open an AI conversation to craft additional instructions, then re-execute |
| Create PR | Commit, push, and create a pull request from the task branch |
| Merge from root | Merge the root branch HEAD into the task branch; conflicts are auto-resolved with AI |
| Pull from remote | Pull the latest changes from remote origin (fast-forward only) |
| Try merge | Squash merge (stages changes without committing, for manual review) |
| Merge & cleanup | Squash merge and delete the branch |
| Delete | Discard all changes and delete the branch |
| Action | Description |
|---|---|
| Requeue | Select a resume or restart position and return the task to pending without a conversation |
| Retry | Open a retry conversation with failure context, review the revised instruction, then queue it as pending |
| Instruct | Open an AI conversation against the run’s working tree to craft additional instructions, then requeue |
| Create PR | Commit, push, and create a pull request from the failed run’s changes |
| Delete | Remove the failed task record |
In CLI/TUI assistant and grill-me conversations, /requeue [guidance] resolves a failed or exceeded task from the conversation. The guidance is appended as the final user turn for both task and start-position selection, rather than mechanically matched to a task name. If the AI cannot identify a task or its selection fails, TAKT asks you to choose from the eligible tasks. If the start position cannot be determined, you can choose from the available positions. TAKT then shows the task name, summary, workflow, and start position and asks for Y/n confirmation. Approval returns the task to pending without changing its order.md. Cancelling selection or confirmation leaves the task unchanged and records that result in the conversation. Successful requeue results also remain in the conversation with the task name. /retry [guidance] retains its existing behavior: it resolves a failed task and shows a complete revised order with Save task and Continue choices. Save task archives the previous order and returns the task to pending; Continue makes no task changes and returns to the conversation. Ambiguous /retry targets or start positions, and an empty candidate set for either command, return a notice. Neither command starts a worker. Both require an interactive terminal; without a TTY, neither selection nor task changes occur. Persona conversations and the Web UI treat these strings as ordinary messages. The direct-run /retry flow in takt resume remains separate.
| Action | Description |
|---|---|
| Delete | Remove the pending task from tasks.yaml |
| Action | Description |
|---|---|
| Mark as failed | Mark a stuck running task as failed |
Selecting a running task with a worktree clone opens the ordinary assistant conversation with that task as the initial /tell target. The conversation can inspect other tasks or discuss a new task. /tell rechecks the selected task after confirmation and writes only to that task; completed, missing, mismatched, and non-clone runs are not candidates or recipients.
Running merge tasks started by takt merge, or by takt run / takt watch after requeue or retry, are also /tell targets when they have a worktree clone. CLI/TUI conversations, conversations opened from takt list, and MCP’s takt_tell_run use the same target resolution. Merge run metadata and interventions are stored in the original project’s .takt/runs/<slug>/. Instructions are delivered at the next agent step, including agent steps inside a child workflow; system steps do not consume them.
| Action | Description |
|---|---|
| Requeue | Return the task to pending, resuming from where it stopped |
| Delete | Remove the task permanently |
/requeue can also target an exceeded task. Inline guidance selects either continuing the saved execution or restarting at a specified step, including a child workflow step. Confirmation shows that operation and position. Continuing retains the saved execution information; restarting clears the old checkpoint and iteration limit information. If an explicit position is unavailable or cannot be determined by the AI, TAKT asks you to choose an available start position. Without inline guidance, the saved stopping position is preserved. The command does not revise the order or start a worker. The task-list Requeue action continues to use the saved stopping position.
Tasks with pr_failed status (workflow succeeded but PR creation or push failed) show the publishing error and offer the same actions as completed tasks, including Create PR. The workflow result, local branch, and commit are preserved. A failed push skips automatic PR creation and reports the branch, commit, and retry action.
TAKT-managed remote pushes disable Git’s HTTPS terminal and askpass prompts, and Git Credential Manager interaction. Configure authentication before retrying, for example with gh auth login and gh auth setup-git, or your credential helper. Custom credential helpers and SSH authentication must also be configured for unattended use.
After fixing authentication or the reported push error, tasks that need a PR can use Create PR in takt list. It commits any remaining changes, pushes the branch, and reuses an existing PR for that branch or creates one without rerunning the workflow. A successful retry changes pr_failed to completed, records the PR URL, and clears the publishing error. Cancelled or failed retries preserve pr_failed and the local results.
If saving the task state fails after publishing the PR, TAKT displays the published PR URL and the save error. Check the task in takt list; if it is still pr_failed, retry Create PR. The retry reuses the existing PR and saves the task state again.
For tasks that only push without creating a PR, fix authentication and manually push the reported branch to origin from the project repository. This manual push does not update the task status.
When you select Instruct on a completed task, TAKT opens an interactive conversation loop with the AI. The conversation is pre-loaded with:
You can discuss what additional changes are needed, and the AI helps refine the instructions. When ready, use /go; after the instruction is generated, choose:
pending with the new instructions for later executionTo re-execute immediately, use /accept (use the latest assistant response) or /replay (resubmit the previous order). Use /cancel to discard and return to the list.
Instruct on a failed task uses the same conversation, targeting the run’s uncommitted working tree instead of a committed branch. Its conversation is additionally pre-loaded with a summary of the final adjudication report (fulfilled requirements, unresolved findings, unverified gates) and an overview of the working-tree diff.
When you select Retry on a failed task, TAKT:
Requeue uses the same workflow and start-position selection, but saves the task as pending without opening a conversation. The start-position prompt presents the workflow as a tree: when a valid resume position exists, the top row is Resume failed position (continue from the failure point, preserving execution state), and every authored step is listed below as a selectable leaf. workflow_call sub-workflows appear as non-selectable headings that indent their child steps, so you always confirm a leaf step — a sub-workflow itself cannot be chosen. When a valid Resume position is available, the Resume row is initially selected; otherwise the preferred selectable leaf for the failed root step is initially selected. Choosing any leaf restarts a new execution from that step.
The Resume row uses a short label such as Resume failed position: "review" (default) with a dimmed path description directly below it. The path starts with the root workflow, groups each call as "call step" → "child workflow", and ends with the failed step, for example "takt-default" > "develop" → "development-core" > "review". At 80 columns or wider, the description wraps to show the full path. At 60 columns, only the description is truncated from the end, preserving the root side, while the failed step and default marker remain visible in the label. The Web UI dropdown and the Selected start position: … confirmation log include both the label and the full path.
After a requeue, execution uses a new namespace, so its ledger is not inherited and starts empty.
After /go, the retry conversation shows the revised instruction and offers Save as Task first (the default) or Continue editing. Saving updates the existing task and returns it to pending; it does not start a worker immediately. /retry, /replay, and immediate execution choices are unavailable in this Retry conversation. Use /cancel to abort without changing the task.
--non-interactive)For CI/CD scripts, use non-interactive mode:
# List all tasks as text
takt list --non-interactive
# List all tasks as JSON
takt list --non-interactive --format json
# Show diff stat for a specific branch
takt list --non-interactive --action diff --branch takt/my-branch
# Merge a specific branch
takt list --non-interactive --action merge --branch takt/my-branch
# Delete a branch (requires --yes)
takt list --non-interactive --action delete --branch takt/my-branch --yes
# Try merge (stage without commit)
takt list --non-interactive --action try --branch takt/my-branch
Available actions: diff, sync, try, merge, delete.
The recommended end-to-end workflow:
takt add – Create a task. A pending record is added to .takt/tasks.yaml and order.md is generated in .takt/tasks/{slug}/.order.md – Open the generated file and add detailed specifications, reference materials, or supplementary files as needed.takt run (or takt watch) – Execute pending tasks from tasks.yaml. Each task runs through the configured workflow..takt/runs/{run_slug}/reports/. The run slug is assigned per execution; find it via the run_slug field in tasks.yaml or the newest directory under .takt/runs/.takt list – Review results, merge successful branches, retry failures, or add further instructions.caccia)The merge builtins execute Caccia explicitly: merge-review runs review → caccia → wait_ci → evaluation comment, while merge-review-fix and merge-review-fix-simple run review/fix → commit_and_push → caccia → wait_ci → merge_pr. success and skipped continue to CI on the returned head. limit comments with the unresolved thread count and ends COMPLETE without merging. An effect error comments with error and ends ABORT. Push, task post-processing, and Pipeline no longer start Caccia implicitly. With merge.auto_start: true, PR publication starts the merge workflow, whose explicit effect owns Caccia.
Caccia waits for CodeRabbit, then processes only unresolved threads started by coderabbitai. Each iteration runs the configured workflow in a temporary clone, preserves its decision report under .takt/runs/, pushes successful fixes, resolves only the threads evaluated in that iteration, and waits for CodeRabbit to review the pushed commit. Human-started threads remain open. Caccia does not reply to reviews. Successes and iteration-limit results are logged and sent through the configured notification path.
wait_timeout_ms bounds the initial review wait and each pushed-commit review wait, including a retry request. If a CodeRabbit rate-limit notice gives a retry time before the deadline, Caccia posts one @coderabbitai review request when that time arrives; a retry time at or beyond the deadline skips Caccia immediately. A review still incomplete at the deadline after a rate-limit notice also skips Caccia. Without a rate-limit notice, an initial timeout returns skipped and a pushed-commit timeout returns an effect error; standalone takt caccia exits non-zero on a skip or error.
Effect progress, workflow output, results, and failures follow the parent task’s display mode. Parallel tasks keep the same task prefix and color; silent mode produces no screen output. The workflow awaits the effect result before selecting its next step.
Run the same feature manually with takt caccia <PR-number>. See the CLI reference and configuration reference for command results and settings.
Specifying worktree in task configuration executes each task in an isolated clone created with git clone, keeping your main working directory clean.
| Setting | Description |
|---|---|
worktree: true |
Auto-create clone under {project}/../takt-worktrees (or the location specified by worktree_dir config; falls back to .takt/worktrees inside the project when the parent directory is not writable) |
worktree: "/path/to/dir" |
Create clone at the specified path |
branch: "feat/xxx" |
Use specified branch (auto-generated as takt/{timestamp}-{slug} if omitted) |
(omit worktree) |
Execute in current directory (default) |
TAKT uses git clone --reference <main-repo> --dissociate instead of git worktree to create clones with an independent .git directory (when the reference repository is shallow, it falls back to a plain git clone). This is important because:
.git: Clones have their own .git directory, preventing agent tools from traversing gitdir: references back to the main repository.Note: The YAML field name remains
worktreefor backward compatibility. Internally, it usesgit cloneinstead ofgit worktree.
Clones follow an ephemeral lifecycle:
origin happens only when auto_pr or similar publishing options are set)takt list to merge or deleteDuring worktree execution, TAKT maintains two directory references:
| Directory | Purpose |
|---|---|
cwd (clone path) |
Where agents run, where reports are written |
projectCwd (project root) |
Where logs and session data are stored |
Reports are written to cwd/.takt/runs/{slug}/reports/ (inside the clone) to prevent agents from discovering the main repository path. Session resume is skipped when cwd !== projectCwd to avoid cross-directory contamination.
TAKT writes session logs in NDJSON (Newline-Delimited JSON, .jsonl) format. Each record is atomically appended, so partial logs are preserved even if the process crashes.
.takt/runs/{slug}/
logs/{sessionId}.jsonl # NDJSON session log per workflow execution
meta.json # Run metadata (task, workflow, start/end, status, etc.)
operations/
journal.json # Operation journal (internal execution records)
context/
previous_responses/
latest.md # Latest previous response (inherited automatically)
When observability is enabled, meta.json also includes observability.traceDiscovery with the Tempo TraceQL queries that TAKT printed after completion or abort.
| Record Type | Description |
|---|---|
workflow_start |
Workflow initialization with task and workflow name |
step_start |
Step execution start |
step_complete |
Step result with status, content, matched rule info |
workflow_complete |
Successful workflow completion |
workflow_abort |
Abort with reason |
You can monitor logs in real-time during execution:
tail -f .takt/runs/{slug}/logs/{sessionId}.jsonl