\n\n**Stop babysitting AI coding agents.**\n\nTAKT is an open-source CLI that turns AI coding agents into repeatable development workflows. Define planning, implementation, review, fix loops, human checkpoints, permissions, and output contracts in YAML, then run tasks with isolated worktrees and traceable logs.\n\nInstead of asking one agent to remember the whole process, TAKT gives each step its own role, context, and transition rules. Agents can code, but the workflow decides what happens next.\n\n\n\n- Run plan → implement → review → fix loops as explicit workflow steps\n- Keep context focused with step-specific personas, policies, knowledge, instructions, and output contracts\n- Execute queued tasks in isolated worktrees and inspect logs and reports afterward\n- Use Claude Code, Claude SDK, Codex SDK, OpenCode SDK, Pi SDK, the official DeepSeek Harness SDK, Cursor, GitHub Copilot CLI, or Kiro as providers\n\n**T**AKT **A**gent **K**oordination **T**opology orchestrates multiple AI agents with review loops, managed prompts, and per-step permissions.\n\nTalk to AI to define what you want, queue it as a task, and run it with `takt run`. Planning, implementation, review, and fix loops are defined in YAML workflow files, so the process is not left to the agent's discretion. TAKT coordinates Claude Code, Codex, OpenCode, Pi, the official DeepSeek Harness SDK, Cursor, GitHub Copilot CLI, and Kiro CLI as agents with different roles, permissions, and context.\n\nTAKT is built primarily for AI coding workflows, but the same model applies beyond coding: any task where multiple AI agents need to coordinate, or where review, judgment, and feedback loops can improve task quality.\n\nTAKT is built with TAKT itself (dogfooding).\n\n## Why TAKT\n\nAI coding agents do not automatically create a stable development process. In long-running work, they forget instructions, accumulate polluted context, blur implementation and review responsibilities, and often force humans to repeat the same feedback again and again.\n\nAdding more rules to prompts, `CLAUDE.md`, or skills can help, but it cannot enforce the process. Whether the rules are followed is still left to the agent's behavior.\n\nTAKT treats AI agents as something to be controlled from the outside, not simply trusted.\n\nWorkflows define the phases, and each step receives its own persona, policy, knowledge, instruction, and output contract. TAKT manages implementation, review, fix, and re-review flows declaratively. By separating responsibilities, knowledge, and constraints, then giving each agent only what it needs for the current step, TAKT improves task quality without bloating context.\n\nReviews cannot be silently skipped. Findings route work back to fix steps, and human judgment can be requested when needed. Tasks run in isolated worktrees, and each step leaves logs and reports so the path from task to PR remains traceable.\n\nTAKT runs all of this as a reusable agent process built from roles, phases, judgments, and feedback loops, so the development process stays reviewable and reproducible without constant human intervention.\n\n## Try It in 5 Minutes\n\nFrom a Git repository with at least one commit:\n\n```bash\nnpm install -g takt\n\n# Install the SDK for the default provider (claude-sdk)\ntakt install claude-sdk\n\n# Talk to AI, describe a task, use /go, then choose \"Save as Task\"\ntakt\n\n# Execute queued tasks in isolated worktrees\ntakt run\n\n# Review diffs, merge, retry, requeue, or delete task branches\ntakt list\n```\n\nIf this is your first run, configure a provider in `~/.takt/config.yaml` or use the API key environment variables listed in [Configuration](#configuration). SDK-based providers (`claude-sdk`, `codex`, `opencode`, `pi`, and `deepseek-harness`) run with Node.js; run `takt install ` once before using one. CLI-based providers require their external CLIs.\n\n## CodeRabbit Review Loop\n\nOn GitHub, run `takt caccia ` to wait for CodeRabbit reviews, handle unresolved bot threads in isolated clones, and keep a decision report for each iteration. Merge workflows call the loop through an explicit `caccia` effect. `caccia.enabled` controls whether that effect waits for CodeRabbit and defaults to false. Push and PR publication do not start Caccia implicitly. See the [CLI reference](./docs/cli-reference.md#takt-caccia) and [configuration guide](./docs/configuration.md#caccia-review-loop).\n\n### Video Tutorial\n\nFollow the [written tutorial](./docs/tutorial.md) with these hands-on walkthroughs:\n\n| Chapter 1 | Chapter 2 |\n|-----------|-----------|\n| [](https://youtu.be/HUcFFvOy39I) | [](https://youtu.be/UIlM2iM-rmA) |\n\n## TAKT vs Plain AI Coding Agents\n\n| Plain AI coding agents | TAKT |\n|------------------------|------|\n| The prompt asks the agent to follow a process | The YAML workflow owns the process |\n| Review steps can be forgotten or skipped | Review and fix loops are explicit transitions |\n| One long context keeps growing | Each step receives only the context it needs |\n| Implementation and review responsibilities blur | Personas, permissions, and output contracts separate responsibilities |\n| Work often lands directly in the current tree | Queued tasks run in isolated worktrees by default |\n| The path from task to result is hard to audit | Logs and reports preserve the path from task to PR |\n| The same process must be recreated by memory | Workflows are reusable, reviewable, and versionable |\n\n## Requirements\n\nTAKT requires Node.js `>=22.22.0` and Git `>=2.38` (goal completion compares trees with `git merge-tree --write-tree`).\n\nThe provider you choose determines whether you need to install an external CLI or can run on Node.js alone via a TypeScript SDK.\n\nThe default provider is `claude-sdk` (Claude Agent SDK). `claude` is an alias for `claude-sdk`.\n\nTo continue using the Claude Code CLI, select `claude-headless` in your provider configuration or pass `--provider claude-headless`. Move any provider permission profile to the selected provider name; the default is now `claude-sdk`, so an old `provider_profiles.claude` setting may no longer apply. Existing sessions labeled `claude` start fresh. See [permission resolution](./docs/configuration.md#permission-resolution-priority) for the migration details.\n\nThese providers run via SDK (no CLI required, Node.js only). The SDK is not bundled with TAKT; run `takt install ` once before use, and `takt update` after upgrading TAKT. In a terminal, TAKT offers to install a missing SDK; in CI and other non-interactive runs, install it beforehand. See [Managed SDK installation and updates](./docs/cli-reference.md#managed-sdk-installation-and-updates).\n\n- `claude-sdk` — `@anthropic-ai/claude-agent-sdk`\n- `codex` — `@openai/codex-sdk`\n- `pi` — `@earendil-works/pi-coding-agent`\n\nThe `deepseek-harness` provider uses the official TypeScript SDK and its runtime. Run `takt install deepseek-harness` before use. It supports Linux x64/arm64 with glibc `>= 2.28` and macOS arm64 `>= 14.0`. Sessions cannot restore history after the runtime exits; start a new TAKT session or run after changing its settings. See the [configuration guide](./docs/configuration.md#deepseek-harness-deepseek-harness) for credentials, supported tools, permissions, migration, and recovery.\n\nThese providers require an external CLI:\n\n- `opencode` — [OpenCode](https://opencode.ai/) CLI, plus `takt install opencode` for its SDK. v2 is the default; select v1 explicitly ([migration settings](./docs/configuration.md#opencode-v1v2-selection)).\n- `claude-headless` — [Claude Code](https://claude.ai/code)\n- `claude-terminal` — [Claude Code](https://claude.ai/code) driven in an interactive terminal session (also requires [`tmux`](https://github.com/tmux/tmux))\n- `copilot` — [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli)\n- `cursor` — [Cursor Agent](https://docs.cursor.com/)\n- `kiro` — [Kiro CLI](https://kiro.dev/docs/cli/headless/)\n- `devin` — [Devin CLI](https://devin.ai/)\n\nOptional:\n\n- [GitHub CLI](https://cli.github.com/) (`gh`) — for `takt #N` (GitHub Issue tasks)\n- [GitLab CLI](https://gitlab.com/gitlab-org/cli) (`glab`) — for GitLab Issue/MR integration (auto-detected from remote URL)\n- Java 17 or later (`java` on `PATH`) — for the model-checking stages of `/verify` in formal specification mode (`quint verify` and the Alloy Analyzer). The Quint CLI itself is bundled with TAKT; see [Formal Specification Verification](./docs/formal-verification.md) for what is downloaded on first use\n\n> **OAuth usage:** Whether OAuth is permitted varies by provider and use case. Check each provider's terms of service before using TAKT.\n\n## Quick Start\n\n### Install\n\n```bash\nnpm install -g takt\ntakt install claude-sdk # or codex, opencode, pi, deepseek-harness\n```\n\nWith Nix flakes:\n\n```bash\nnix run github:nrslib/takt\nnix profile install github:nrslib/takt\n```\n\nThe Nix package installs the TAKT CLI itself. External CLI providers, `git`, and `gh`/`glab` still need to be installed and available on `PATH` or configured separately as described in [Requirements](#requirements).\n\n### Talk to AI and queue tasks\n\n```\n$ takt\n\nSelect workflow:\n ❯ 🎼 default (current)\n 📁 🚀 Quick Start/\n 📁 🛠️ Development/\n 📁 🔍 Review/\n\n> Add user authentication with JWT\n\n[AI clarifies requirements and organizes the task]\n\n> /go\n\nProposed task:\n ...\n\nWhat would you like to do?\n ❯ Save as Task # ← normal flow and initial selection\n Create Issue\n Execute here now\n Continue editing\n```\n\nChoosing \"Save 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.\n\n\"Create Issue\" asks \"Save as a task too? [Y/n]\" before creating anything. Y or Enter creates the Issue and continues through the existing task-saving and worktree settings flow. n creates only the Issue. Esc returns to the same menu without creating an Issue or task. The Issue option is hidden in `--pr` sessions.\n\nIn an ordinary assistant conversation, use `/issue 123` or `/issue 12 34` to replace the current Issue context and continue the same conversation. The next message and `/go` use the fetched Issue content.\n\n```bash\n# Execute queued tasks\ntakt run\n\n# You can also queue from GitHub Issues\ntakt add '#6'\ntakt add '#12'\n\n# Execute all pending tasks\ntakt run\n```\n\n> **\"Execute here now\"** first explains that this TUI will be unavailable until the workflow finishes and that the normal flow is to save the task and use `takt run`. The confirmation defaults to No (`[y/N]`): only y starts the existing execution flow in the current directory without worktree isolation. N, Enter, or Esc returns to the menu with the selection preserved. Esc in the menu returns to conversation input.\n\n### Manage results\n\n```bash\n# List task branches — merge, retry, requeue, stop, force-fail, or delete\ntakt list\n```\n\n**Stop** requests a stop for one running task; the worker interrupts itself and determines the final state. **Mark as failed** only changes status and does not stop the worker.\n\n## How It Works\n\nThe 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.\n\nA 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:\n\n```yaml\nname: plan-implement-review\ninitial_step: plan\nmax_steps: 10\n\nsteps:\n - name: plan\n persona: planner\n edit: false\n rules:\n - condition: Planning complete\n next: implement\n\n - name: implement\n persona: coder\n edit: true\n required_permission_mode: edit\n rules:\n - condition: Implementation complete\n next: review\n\n - name: review\n persona: reviewer\n edit: false\n rules:\n - condition: Approved\n next: COMPLETE\n - condition: Needs fix\n next: implement # ← fix loop\n```\n\nRules determine the next step. `COMPLETE` ends the workflow successfully, `ABORT` ends with failure. See the [Workflow Guide](./docs/workflows.md) for the full schema, parallel steps, and rule condition types.\n\nReusable step definitions can be stored in `.takt/steps/` and expanded with `uses` before validation. See the Workflow Guide for fragment lookup and override rules.\n\nWorkflow files live in `workflows/` as the official directory name.\n\nWhen the same workflow name exists in multiple locations, TAKT resolves in this order: `.takt/workflows/` → `~/.takt/workflows/` → builtins.\n\n## Recommended Workflows\n\n| Workflow | Use Case |\n|-------|----------|\n| `default` | Standard development workflow. Scenario-based planning and test-first development with dynamic implementation companions, multi-perspective parallel peer review, adjudication, and a convergent fix loop. |\n| `maintenance` | A `default` variant for existing codebases: preserves contracts outside the change scope and limits work to causally related changes. |\n| `simple` | Lightweight workflow with the same minimal structure as `pure`; TAKT selects applicable domain facets per change, always including AI antipattern and architecture guidance. |\n| `pure` | Minimal workflow with no injected domain facets — trusts the model's own judgment and skill selection. |\n| `takt-default` | The workflow used to develop TAKT itself. Directly applicable to other CLI tool development. |\n| `takt-default-team` | A `takt-default` variant that runs implementation and remediation through Team Leader task decomposition. |\n| `review` | Multi-perspective review with dynamic reviewer selection and supervisor synthesis, without modifying code. |\n| `review-fix` | Multi-perspective review with dynamic reviewer selection, followed by the default workflow's adjudicated, verified remediation loop and final requirement check. |\n\nDomain-specific families (`simple-*` / `frontend` / `backend` / `dual` / CQRS / `*-mini` variants) remain available under the 📦 Legacy category.\n\nSee the [Builtin Catalog](./docs/builtin-catalog.md) for all workflows and personas.\n\n## Key Commands\n\n| Command | Description |\n|---------|-------------|\n| `takt` | Talk to AI, refine requirements, execute or queue tasks |\n| `takt exec` | Start instant Assistant/Worker/Review agent mode without writing workflow YAML |\n| `takt make` | Start Workflow Maker to create or revise an isolated workflow bundle interactively |\n| `takt add` | Refine a task through AI conversation and queue it (also from GitHub Issues) |\n| `takt run` | Execute all pending tasks |\n| `takt watch` | Monitor the task queue and auto-execute pending tasks (resident process) |\n| `takt ui` | Open the experimental Viewer-first Web UI on `http://127.0.0.1:20525` |\n| `takt manager` | Open the experimental goal conversation TUI connected to the daemon. Use `Ctrl+R` for inquiries and `Ctrl+G` for ongoing goals; both keys work while manager is processing. Type `/make-goal` in the input box and press `Enter` to create a goal proposal from the current conversation. Even when a proposal is already displayed, this only regenerates it; it does not register the goal. Use `↑↓` to choose **Register goal** or **Return to conversation without registering**, then press `Enter`. The default returns to the conversation and dismisses the proposal. Select **Register goal** to register it. Typing `/` shows `/make-goal` as a completion candidate; `Tab` accepts it. Other input starting with `/` is sent as a regular message. If material is insufficient, continue the conversation. To add, remove, or rename a managed repository, ask in the conversation. Behavior, settings, and saved data formats may change without notice. Automatically queues and runs tasks, incurring provider API costs. With claude (claude-sdk) or codex, AI reviews tool use before execution. On startup, manager starts the daemon if needed and waits until it is ready; the daemon admits, saves, routes, and observes events; each conversation has a child process for its turns. Stop the daemon with `takt daemon stop` |\n| `takt director` | Open the experimental conversation TUI for oversight across managers; see [Director](#director-experimental) |\n| `takt list` | Manage task branches (merge, retry, requeue, stop, force-fail, instruct, delete) |\n| `takt #N` | Use a GitHub Issue as the initial input for a task |\n| `takt merge` | Review, fix, and merge pull requests with a workflow |\n| `takt install ` | Install the SDK for an SDK-based provider |\n| `takt update` | Update installed provider SDKs to the versions pinned by TAKT |\n| `takt eject` | Copy builtin workflows/facets for customization |\n| `takt workflow init` | Create a new workflow scaffold |\n| `takt workflow doctor` | Validate workflow definitions |\n| `takt workflow inspect` | Inspect a workflow's configuration and resolution sources |\n| `takt repertoire add` | Install a repertoire package from GitHub |\n\nManager conversations run in the daemon; the TUI sends requests and displays results. Once a turn is accepted, it continues in the daemon even if you close the TUI. Reopening manager for the same repository or workspace, or opening a second TUI for that assignment, connects to the same conversation. Any goal proposal awaiting approval is shown again and can be registered by selecting **Register goal** and pressing `Enter`.\n\nPrevious messages and replies are not redisplayed when you reopen the TUI. Conversation history is managed by the provider's session. TAKT saves message text and full results in `daemon-events` and retains them after completion. These records are not automatically deleted. Pending goal summaries and goal records are saved separately.\n\nThe daemon is event driven. It has two queues: human input and other events. Human input takes priority when starting the next turn; each queue preserves acceptance order. A conversation shares one session, retaining context learned from events for later human messages. Messages, approvals, and inquiry answers can be accepted and saved while a turn is running; snapshot reads and interruption remain available. accepted means durable admission, not completion. Interrupting the active turn preserves waiting input. After failure or interruption, manager checks current state and side effects, then decides whether to resume, correct and retry, or submit new work.\n\nThe daemon does not exit automatically while a TUI is connected or an accepted conversation operation is running. To stop it explicitly, use `takt daemon stop`.\n\n**Slack conversations:** You can also talk to the same manager conversation from a configured Slack channel. Replies stay in the thread where you sent the message; TUI replies are not forwarded to Slack. See [Slack conversations with manager](./docs/configuration.md#slack-conversations-with-manager) for the Socket Mode App manifest, token environment variables, repository settings, and how to answer inquiries. Completion notices continue to use the separate `TAKT_NOTIFY_WEBHOOK` Incoming Webhook.\n\nIn a conversation thread, send `/make-goal` to create a proposal. Use **Register goal** or **Return to conversation without registering**; buttons on an outdated proposal no longer work.\n\nSee the [CLI Reference](./docs/cli-reference.md) for all commands and options.\n\n`takt list --non-interactive --action delete` accepts `--status ` to select one or more of `pending`, `completed`, `failed`, `exceeded`, and `pr_failed`. `running` is not allowed because running tasks cannot be deleted. `--goal ` selects tasks belonging to that goal. `--branch ` is also available; when used alone, it targets only `completed` tasks.\n\nAt least one of `--status`, `--goal`, or `--branch` is required. Without a filter, the command exits with an error without deleting anything. Without `--yes`, it lists the matching task names, statuses, branches, and goals, then exits successfully without deleting anything. Only `--yes` performs deletion. Use `--format json` to return the preview as JSON; JSON output includes `goal_id`.\n\nDeletion removes the task's working clone, worktree session files, clone metadata, branch, and record in `.takt/tasks.yaml`, matching deletion from the interactive list. Clone tasks also delete the branch with the same name in the original repository with `git branch -d` after cleanup. If Git refuses deletion because the branch is not fully merged or for another reason, the branch is retained with a warning while clone and task-record deletion succeed.\n\n```bash\n# Preview matching tasks, then delete them after checking the list\ntakt list --non-interactive --action delete --status failed pr_failed\ntakt list --non-interactive --action delete --status failed pr_failed --yes\n\n# Preview as JSON\ntakt list --non-interactive --action delete --status failed pr_failed --format json\n```\n\nThe Web UI defaults to Japanese. Use the language control in the header to switch\nbetween Japanese and English; the selection is saved in the browser for the next\nvisit. Viewer focuses on execution status, the observed execution path, live logs,\nand reports. Create a task opens the dedicated conversation surface for `/setup`\nand `/go`.\n\nTAKT also ships two client-integration entrypoints: `takt-acp` runs TAKT as an [Agent Client Protocol](./docs/cli-reference.md#acp-agent) agent over stdio JSON-RPC, and `takt-mcp` runs it as a stdio [MCP server](./docs/cli-reference.md#mcp-server) so an MCP client (Codex, Claude Code, …) can enqueue tasks, inspect task/run state, and send additional instructions to running worktree-clone tasks. Use `takt run` or `takt watch` to execute pending tasks.\n\n`takt_cleanup_tasks` previews filtered tasks before deletion. It requires an absolute `cwd` and a `reason`. Optional inputs are `statuses` (one or more of `pending`, `completed`, `failed`, `exceeded`, and `pr_failed`; `running` is not allowed), `goalId`, `branch`, and `confirm` (default `false`). At least one of `statuses`, `goalId`, or `branch` is required.\n\nOmitting `confirm` or setting it to `false` returns only the matching list without deleting anything. Only `confirm: true` deletes tasks, with the same deletion scope as `takt list`. This tool is available only in the `all` tool set, not in `read-only` or `manager`; `manager` has the separate `takt_remove_goal_task` tool.\n\n`takt_stop_goal_task` is available in the `manager` and `all` tool sets. Pass an absolute `cwd`. From one task item returned by `takt_list_tasks`, pass its `name` value as `taskName` and use its `goalId` and `executionId`. The owner PID must be alive. When an owner start time is saved, the current start time must be available and match it. Without a saved start time, matching goalId, taskName and executionId, running status, and a live owner PID are sufficient to accept the request. Mismatched identities, non-running tasks, and ended owners are rejected with a reason and no stop request is saved. The tool only saves the request; the task stays `running` while its worker polls every 500 ms and aborts itself. After execution and cleanup finish, the worker saves `failed` with a task stop reason, distinct from a goal abort. Other tasks and the goal remain active. Repeated requests return the saved request only if the same execution is still `running` and its owner can be verified when the request is evaluated; retries use a new execution ID.\n\nBefore processing each project's events, the daemon recovers interrupted tasks to `failed` and creates goal-task completion events, even when no pending tasks exist. Recovery requires an absent or dead owner PID, or a known mismatch between the saved and current owner start times. A live PID with unavailable saved or current owner identity is left running.\n\nThe ordinary `takt` assistant conversation has the same read-only task-state view when its provider supports MCP. Use `/go` to turn a new task into an execution or queued task, `/tell` to select and confirm an additional instruction for a running worktree clone, and `/requeue` or `/retry` to return a failed task to the queue after confirmation.\n\n### Manager judgment and work\n\nManager is an engineer familiar with TAKT, responsible for completing assigned goals. It investigates, implements, verifies, performs Git operations and delegates when useful. It uses normal provider tools and assigned MCP servers, preserving configured provider options. Permissions default to `auto`. For Claude (`claude` / `claude-sdk`) and Codex, set `manager.permission` or provider-specific `manager.provider_permissions` to `full` for unrestricted execution. Other providers behave like `full` under `auto`. A provider-specific `manager.provider_permissions` entry takes precedence over `manager.permission`, so an `auto` entry keeps that provider in `auto` even when `manager.permission: full` is set. There is no separate manager-specific permission judge, read-scope review or execution control based on saved approvals. Use `manager.workflows` and `manager.default_workflow` to select the workflows available for new development tasks; see the [configuration guide](./docs/configuration.md#manager-task-workflows).\n\nFacet policy requires explicit human instructions identifying the target and effect for integration into a target branch, force pushes, deletion of remote branches or unsaved results, goal aborts and new posts outside the requested scope. Direct messages, director relays and saved continuing instructions are supported. PR creation, ordinary pushes and configured notifications are part of requested work. PR merge instructions include deletion of that PR branch; instructions already given are not reconfirmed. Reading secret values requires a human instruction covering that need, and secret values must not appear in responses, records or artifacts.\n\nLegacy `manager.sensitive_paths` and runtime `provider.targets.internal_agents.manager-permission-judge` are deprecated. Existing configuration files remain readable, but these settings are ignored and have no effect. Old permission Markdown and approval answers do not decide execution. Historical inquiry records remain readable and withdrawable.\n\n\n### Instant exec mode\n\n`takt exec` starts TAKT's interactive task-entry mode. The Assistant agent clarifies the request, `/go` turns the conversation into a generated workflow, Worker agent(s) implement the task, Review agent(s) review the result, the Replanning agent asks the user for direction when needed, and loop detection prevents repeated unproductive cycles.\n\nExec starts from the previous exec configuration, or the default configuration on first run; pass a preset name to start from that preset. Use `/setup` during the conversation to edit agents, loop detection thresholds, presets, and referenced facets. When `/go` runs, TAKT generates `.takt/exec/workflow.yaml` and executes it through the normal workflow engine; use `/cancel` to exit without running. Image attachments are supported while editing input (`/paste-image`, `Ctrl+V`, or an OSC 1337 inline-image paste).\n\nSee [Instant Exec Mode](./docs/cli-reference.md#instant-exec-mode) in the CLI Reference for preset resolution order, `/setup` persistence, image handling limits, and `session_key` behavior.\n\n## Director (experimental)\n\nOpen the director conversation TUI in an interactive terminal:\n\n```bash\ntakt director\ntakt director --help\n```\n\nThe daemon owns the conversation. Close and reopen the TUI to continue it; starting from another assigned repository connects to the same conversation. Previous messages and replies are not redisplayed. Director is experimental: behavior and saved data formats may change without notice. Human and event turns call the provider and incur costs; a clock alone does not trigger a model call.\n\nManager advances goals within its repository or workspace, submits tasks, integrates results, and requests completion. Director checks goals and unanswered inquiries across all managers, notifies the human when attention is needed, and communicates through manager conversations. Human decisions remain with the human: director only relays an explicit request to merge to the responsible manager and never performs the merge itself.\n\nMessages sent through `takt_tell_manager` are saved even while manager is busy. The tool returns an operation ID and manager as soon as the message is saved, without waiting for a reply; messages are processed in saved order. Replies, failures, and interruptions are saved and shown later in the director TUI with the same operation ID. Manager listing reports unreadable projects with reasons and continues with readable managers.\n\nSet `director.slack.channel_id` and `director.slack.allowed_user_ids` in global `~/.takt/config.yaml`. See the [global config field reference](./docs/configuration.md#global-config-field-reference).\n\n**Director on Slack:** Use the same Slack App and `TAKT_SLACK_APP_TOKEN` / `TAKT_SLACK_BOT_TOKEN` as manager, invite the bot to the director channel, and restart the daemon after changing Slack settings. Configuring `director.slack` enables grouped notices and conversations with permitted users; replies stay in the original thread. See [Slack conversations with director](./docs/configuration.md#slack-conversations-with-director) for setup and [Director responsibilities](./docs/goal-management.md#director-responsibilities) for the full responsibilities and restrictions.\n\n## Configuration\n\nMinimal `~/.takt/config.yaml`:\n\n```yaml\nprovider: claude-sdk # claude-sdk, claude (alias), claude-headless, claude-terminal, codex, opencode, deepseek-harness, cursor, copilot, kiro, devin, pi, or mock\nmodel: sonnet # passed directly to provider\nlanguage: en # en or ja\n```\n\nRun metadata, sessions, traces, reports, and other run artifacts remain ordinary\nfiles under `.takt/runs//`. Resume and requeue preserve the applicable run\nstate and reports.\n\nTo select providers or models for individual steps, configure auto routing. Run `takt telemetry enable` to record routing decisions locally. See the [Configuration Guide](./docs/configuration.md) for details.\n\nOr use provider credentials directly (SDK-based providers require `takt install `; OpenCode also requires its CLI):\n\n```bash\nexport TAKT_ANTHROPIC_API_KEY=sk-ant-... # Anthropic (Claude)\nexport TAKT_OPENAI_API_KEY=sk-... # OpenAI (Codex)\nexport TAKT_OPENCODE_API_KEY=... # OpenCode\nexport TAKT_CURSOR_API_KEY=... # Cursor Agent (optional if logged in)\nexport TAKT_COPILOT_GITHUB_TOKEN=ghp_... # GitHub Copilot CLI\nexport TAKT_KIRO_API_KEY=... # Kiro CLI\nexport DEEPSEEK_API_KEY=... # Official DeepSeek Harness SDK\n# Optional: export DEEPSEEK_BASE_URL=https://...\n# Pi uses its SDK credential store or provider-native environment variables.\n```\n\nSee the [Configuration Guide](./docs/configuration.md) for all options, provider profiles, and model resolution.\n\nOpenCode calls have a 60-minute provider-event inactivity limit by default: the\ntimer resets on each provider event, so a healthy call can run longer while\nevents continue to arrive. Raise the limit with\n`provider_options.opencode.guards.call_timeout_ms` (up to 86,400,000 ms). Guard\nprofiles and per-model overrides are described in\n[Provider inactivity deadline and OpenCode execution guards](./docs/configuration.md#provider-inactivity-deadline-and-opencode-execution-guards).\n\n### Dedicated provider configuration (`runtime.yaml`)\n\nYou can keep provider, model, and routing settings in `~/.takt/runtime.yaml`\nor `/.takt/runtime.yaml`; the project settings take precedence. Use\nthis to keep execution settings separate from workflow definitions. When\nswitching to `runtime.yaml`, do not mix in legacy provider settings. See the\n[Configuration Guide](./docs/configuration.md) for migration steps.\n\nCompanion reviewers are disabled by default. Enable them with the top-level\n`companion.enabled: true` policy in `runtime.yaml`; global and project policies\ncombine with logical AND, so a global `false` cannot be re-enabled by a project\nsetting. See [docs/configuration.md](docs/configuration.md) for the schema, the\nmigration table, and companion policy details.\n\n## Customization\n\n### Custom workflows\n\n```bash\ntakt workflow init my-flow # Create a new workflow scaffold\ntakt workflow doctor my-flow # Validate a workflow definition\ntakt eject default # Copy builtin workflow to ~/.takt/workflows/ and edit\n```\n\n### Custom personas\n\nCreate a Markdown file in `~/.takt/facets/personas/`:\n\n```markdown\n# ~/.takt/facets/personas/my-reviewer.md\nYou are a code reviewer specialized in security.\n```\n\nReference it in your workflow: `persona: my-reviewer`\n\n`~/.takt/personas/` still works as a compatibility path, but `takt catalog` only scans the `facets/` directories.\n\nSee the [Workflow Guide](./docs/workflows.md) for details. The list of builtin personas is in the [Builtin Catalog](./docs/builtin-catalog.md).\n\n## CI/CD\n\nTAKT provides [takt-action](https://github.com/nrslib/takt-action) for GitHub Actions:\n\n```yaml\n- uses: nrslib/takt-action@main\n with:\n anthropic_api_key: ${{ secrets.TAKT_ANTHROPIC_API_KEY }}\n github_token: ${{ secrets.GITHUB_TOKEN }}\n```\n\nFor other CI systems, use pipeline mode:\n\n```bash\ntakt --pipeline --task \"Fix the bug\" --auto-pr\n```\n\nSee the [CI/CD Guide](./docs/ci-cd.md) for full setup instructions.\n\n## Project Structure\n\n```\n~/.takt/ # Global config\n├── config.yaml # Provider, model, language, etc.\n├── workflows/ # User workflow definitions\n├── facets/ # User facets (personas, policies, knowledge, etc.)\n└── repertoire/ # Installed repertoire packages\n\n.takt/ # Project-level\n├── config.yaml # Project config\n├── workflows/ # Project workflow overrides\n├── facets/ # Project facets\n├── tasks.yaml # Pending tasks\n├── tasks/ # Task specifications\n└── runs/ # Execution reports, logs, context\n```\n\nWorkflow definitions are stored under `workflows/`.\n\n## Adopting Spec-Driven Development\n\nTAKT workflows can express SDD stages with output contracts and review steps.\n\nThe community project [j5ik2o/takt-sdd](https://github.com/j5ik2o/takt-sdd) provides workflows and facets for requirements, implementation, and validation. It supports Claude and Codex. Install it with:\n\n```bash\nnpm install -g takt-sdd\n```\n\nSee [External Integrations](./docs/external-integrations.md) for other community integrations.\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Tutorial](./docs/tutorial.md) | Improve one example over three phases while queuing, running, and inspecting tasks |\n| [CLI Reference](./docs/cli-reference.md) | All commands and options |\n| [Configuration](./docs/configuration.md) | Global and project settings |\n| [Observability](./docs/observability.md) | Phase-level usage events and analysis workflow |\n| [Workflow Guide](./docs/workflows.md) | Creating and customizing workflows |\n| [Builtin Catalog](./docs/builtin-catalog.md) | All builtin workflows and personas |\n| [Faceted Prompting](./docs/faceted-prompting.md) | Prompt design methodology |\n| [Token Saving](./docs/token-saving.md) | Measuring and reducing token consumption |\n| [Formal Specification Verification](./docs/formal-verification.md) | Checking agreed requirements with Quint and Alloy via `/verify` |\n| [Repertoire Packages](./docs/repertoire.md) | Installing and sharing packages |\n| [Task Management](./docs/task-management.md) | Task queuing, execution, isolation |\n| [CI/CD Integration](./docs/ci-cd.md) | GitHub Actions and pipeline mode |\n| [External Integrations](./docs/external-integrations.md) | Community examples that extend TAKT without modifying core (audit trails, etc.) |\n| [Changelog](./CHANGELOG.md) ([日本語](./docs/CHANGELOG.ja.md)) | Version history |\n\n### Simplified Chinese documentation\n\nSimplified Chinese documentation uses the `.zh-CN.md` suffix so it can coexist with the English and Japanese pages. Start with the [Chinese documentation index](./docs/README.zh-CN.md).\n\nTranslated coverage includes the onboarding path (README, tutorial, configuration, and CLI reference), workflow authoring, provider/external integrations, and task management. Other guides are available in English or Japanese.\n\n## Sponsors\n\nTAKT is supported by [CodeRabbit](https://coderabbit.link/nrslib) through its Open Source Support Program.\n\n\n \n \n \n \n \n\n\n## Community\n\nJoin the [TAKT Discord](https://discord.gg/R2Xz3uYWxD) for questions, discussions, and updates.\n\n## Contributing\n\nPRs that accompany an issue are especially welcome. For bug fixes and small improvements, feel free to submit a PR without waiting for a maintainer response or for discussion to conclude.\n\nFor large refactoring or features that affect the project's design or compatibility, we recommend discussing the approach in an issue before implementation to avoid rework.\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for details.\n\n## License\n\nMIT — See [LICENSE](./LICENSE) for details.\n","readmeFilename":"README.md"}
![\"TAKT](\"./docs/assets/takt-logo-dark.svg\"){kind=logo}
\n ![\"npm](\"https://img.shields.io/npm/v/takt?label=npm\")
![\"GitHub](\"https://img.shields.io/github/stars/nrslib/takt?logo=github&label=stars\")
![\"CI\"](\"https://github.com/nrslib/takt/actions/workflows/ci.yml/badge.svg?branch=main\"){kind=icon}
\n ![\"license\"](\"https://img.shields.io/github/license/nrslib/takt\")
![\"Discord](\"https://img.shields.io/badge/dynamic/json?label=discord&query=approximate_member_count&url=https%3A%2F%2Fdiscord.com%2Fapi%2Fv10%2Finvites%2FR2Xz3uYWxD%3Fwith_counts%3Dtrue&suffix=%20members&logo=discord&logoColor=white&color=5865F2\"){kind=icon}
![\"TAKT](\"./docs/assets/tutorial-preview.gif\")
\n \n![\"CodeRabbit\"](\"https://victorious-bubble-f69a016683.media.strapiapp.com/Orange_Typemark_43bf516c9d.svg\")
\n