agent-bot/takt
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

インタラクティブプロンプトの上書き機能を無効化

Browse Source
This commit is contained in:
nrslib 2026-02-03 17:21:58 +09:00
parent ad28dc7438
commit 4565263ca4
3 changed files with 323 additions and 362 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

654
README.md
View File

@ -2,9 +2,9 @@
🇯🇵 [日本語ドキュメント](./docs/README.ja.md) 🇯🇵 [日本語ドキュメント](./docs/README.ja.md)
**T**ask **A**gent **K**oordination **T**ool - Multi-agent orchestration system for Claude Code and OpenAI Codex. **T**ask **A**gent **K**oordination **T**ool - Multi-agent orchestration system for Claude Code and OpenAI Codex
TAKT is built with TAKT (dogfooding). TAKT is built with TAKT itself (dogfooding).
## Requirements ## Requirements
@ -13,11 +13,11 @@ You need one of the following:
- **Anthropic API Key** or **OpenAI API Key** - **Anthropic API Key** or **OpenAI API Key**
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex](https://github.com/openai/codex) installed and configured - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex](https://github.com/openai/codex) installed and configured
Additional requirements: Additionally required:
- [GitHub CLI](https://cli.github.com/) (`gh`) — required only for `takt #N` (GitHub Issue execution) - [GitHub CLI](https://cli.github.com/) (`gh`) — Only needed for `takt #N` (GitHub Issue execution)
**About pricing**: When using API keys, TAKT calls Claude API (Anthropic) or OpenAI API directly. The pricing is the same as using Claude Code or Codex. Be mindful of costs, especially when running tasks automatically in CI/CD environments, as API usage can accumulate quickly. **Pricing Note**: When using API Keys, TAKT directly calls the Claude API (Anthropic) or OpenAI API. This uses the same pricing structure as using Claude Code or Codex. Be mindful of costs, especially when running automated tasks in CI/CD environments, as API usage can accumulate.
TAKT supports both Claude (Anthropic) and Codex (OpenAI) as providers. TAKT supports both Claude (Anthropic) and Codex (OpenAI) as providers.
@ -30,155 +30,225 @@ npm install -g takt
## Quick Start ## Quick Start
```bash ```bash
# Interactive planning — refine task requirements with AI, then execute # Interactive mode - refine task requirements with AI, then execute
takt takt
# You can also provide an initial message to start the conversation # Execute GitHub Issue as task (both work the same)
takt hello
# Run a GitHub issue as a task (both are equivalent)
takt #6 takt #6
takt --issue 6 takt --issue 6
# Pipeline mode (non-interactive, for scripts and CI) # Pipeline execution (non-interactive, for scripts/CI)
takt --pipeline --task "fix the auth bug" --auto-pr takt --pipeline --task "Fix the bug" --auto-pr
``` ```
### What happens when you run a task ## Usage
When you run `takt #6` (GitHub issue reference), TAKT guides you through an interactive flow: ### Interactive Mode
**1. Workflow selection** A mode where you refine task content through conversation with AI before execution. Useful when task requirements are ambiguous or when you want to clarify content while consulting with AI.
```bash
# Start interactive mode (no arguments)
takt
# Specify initial message (short word only)
takt hello
```
**Note:** If you specify a string with spaces, Issue reference (`#6`), or `--task` / `--issue` options, interactive mode will be skipped and the task will be executed directly.
**Flow:**
1. Select workflow
2. Refine task content through conversation with AI
3. Finalize task instructions with `/go` (you can also add additional instructions like `/go additional instructions`)
4. Execute (create worktree, run workflow, create PR)
#### Execution Example
``` ```
$ takt
Select workflow: Select workflow:
(↑↓ to move, Enter to select) ❯ 🎼 default (current)
📁 Development/
❯ default (current) (default) 📁 Research/
expert
expert-cqrs
magi
research
simple
Cancel Cancel
Interactive mode - Enter task content. Commands: /go (execute), /cancel (exit)
> I want to add user authentication feature
[AI confirms and organizes requirements]
> /go
Proposed task instructions:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Implement user authentication feature.
Requirements:
- Login with email address and password
- JWT token-based authentication
- Password hashing (bcrypt)
- Login/logout API endpoints
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Proceed with these task instructions? (Y/n) y
? Create worktree? (Y/n) y
[Workflow execution starts...]
``` ```
**2. Isolated clone** (optional) ### Direct Task Execution
``` When task content is clear, you can skip interactive mode and execute directly.
? Create worktree? (Y/n)
```
Choose `y` to run in a `git clone --shared` isolated environment, keeping your working directory clean.
**3. Execution** — The selected workflow orchestrates multiple agents to complete the task.
**4. PR creation** (after worktree execution)
```
? Create pull request? (y/N)
```
If `--auto-pr` is specified, the PR is created automatically without asking.
### Recommended workflows
| Workflow | Best for |
|----------|----------|
| `default` | Full development tasks. Used for TAKT's own development. Multi-stage review with parallel architect + security review. |
| `minimal` | Quick fixes and simple tasks. Minimal workflow with basic review. |
| `review-fix-minimal` | Review and fix workflow. Focused on iterative improvements with review feedback. |
| `research` | Research and investigation. Autonomous research without asking questions. |
## Commands
### Interactive Mode (default)
The standard mode for everyday development. Workflow selection, worktree creation, and PR creation are handled interactively.
```bash ```bash
# Interactive planning — start AI conversation to refine task requirements # Specify task content directly (string with spaces)
takt takt "Add login feature"
# You can also provide an initial message to start the conversation # Specify task content with --task option
takt hello takt --task "Fix bug"
# Run a GitHub issue as a task (both are equivalent) # Specify workflow
takt "Add authentication" --workflow expert
# Auto-create PR
takt "Fix bug" --auto-pr
```
### GitHub Issue Tasks
You can execute GitHub Issues directly as tasks. Issue title, body, labels, and comments are automatically incorporated as task content.
```bash
# Execute by specifying issue number
takt #6 takt #6
takt --issue 6 takt --issue 6
# Automatically create a PR (skip the confirmation prompt) # Issue + workflow specification
takt #6 --auto-pr takt #6 --workflow expert
# Use --task option to specify task content (alternative to GitHub issue) # Issue + auto-create PR
takt --task "Add login feature" takt #6 --auto-pr
``` ```
When `--auto-pr` is not specified, you will be asked whether to create a PR after a successful worktree execution. **Requirements:** [GitHub CLI](https://cli.github.com/) (`gh`) must be installed and authenticated.
### Pipeline Mode (`--pipeline`) ### Task Management (add / run / watch / list)
Specifying `--pipeline` enters pipeline mode — fully non-interactive, suitable for scripts and CI integration. TAKT automatically creates a branch, runs the workflow, commits, and pushes. Batch processing using task files (`.takt/tasks/`). Useful for accumulating multiple tasks and executing them together later.
#### Add Task (`takt add`)
```bash ```bash
# Run a task in pipeline mode # Refine task requirements through AI conversation, then add task
takt --pipeline --task "fix the auth bug" takt add
# Pipeline mode + automatic PR creation # Add task from GitHub Issue (issue number reflected in branch name)
takt --pipeline --task "fix the auth bug" --auto-pr takt add #28
```
# Attach GitHub issue context #### Execute Tasks (`takt run`)
```bash
# Execute all pending tasks in .takt/tasks/
takt run
```
#### Watch Tasks (`takt watch`)
```bash
# Monitor .takt/tasks/ and auto-execute tasks (resident process)
takt watch
```
#### List Task Branches (`takt list`)
```bash
# List task branches (merge/delete)
takt list
```
### Pipeline Mode (for CI/Automation)
Specifying `--pipeline` enables non-interactive pipeline mode. Automatically creates branch → runs workflow → commits & pushes. Suitable for CI/CD automation.
```bash
# Execute task in pipeline mode
takt --pipeline --task "Fix bug"
# Pipeline execution + auto-create PR
takt --pipeline --task "Fix bug" --auto-pr
# Link issue information
takt --pipeline --issue 99 --auto-pr takt --pipeline --issue 99 --auto-pr
# Specify workflow and branch # Specify workflow and branch
takt --pipeline --task "fix the auth bug" -w magi -b feat/fix-auth takt --pipeline --task "Fix bug" -w magi -b feat/fix-bug
# Specify repository (for PR creation) # Specify repository (for PR creation)
takt --pipeline --task "fix the auth bug" --auto-pr --repo owner/repo takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo
# Run workflow only — skip branch creation, commit, and push # Workflow execution only (skip branch creation, commit, push)
takt --pipeline --task "fix the auth bug" --skip-git takt --pipeline --task "Fix bug" --skip-git
# Minimal output mode (for CI)
takt --pipeline --task "Fix bug" --quiet
``` ```
In pipeline mode, PRs are **not** created unless `--auto-pr` is explicitly specified. In pipeline mode, PRs are not created unless `--auto-pr` is specified.
### Subcommands **GitHub Integration:** When using TAKT in GitHub Actions, see [takt-action](https://github.com/nrslib/takt-action). You can automate PR reviews and task execution. Refer to the [CI/CD Integration](#cicd-integration) section for details.
| Command | Description | ### Other Commands
|---------|-------------|
| `takt run` | Run all pending tasks from `.takt/tasks/` |
| `takt watch` | Watch `.takt/tasks/` and auto-execute tasks (stays resident) |
| `takt add` | Add a new task via AI conversation |
| `takt list` | List task branches (try merge, merge & cleanup, or delete) |
| `takt switch` | Switch workflow interactively |
| `takt clear` | Clear agent conversation sessions |
| `takt eject` | Copy builtin workflow/agents to `~/.takt/` for customization |
| `takt config` | Configure permission mode |
| `takt --help` | Show help |
### Options ```bash
# Interactively switch workflows
takt switch
# Copy builtin workflows/agents to ~/.takt/ for customization
takt eject
# Clear agent conversation sessions
takt clear
# Configure permission mode
takt config
```
### Recommended Workflows
| Workflow | Recommended Use |
|----------|-----------------|
| `default` | Serious development tasks. Used for TAKT's own development. Multi-stage review with parallel reviews (architect + security). |
| `minimal` | Simple fixes and straightforward tasks. Minimal workflow with basic review. |
| `review-fix-minimal` | Review & fix workflow. Specialized for iterative improvement based on review feedback. |
| `research` | Investigation and research. Autonomously executes research without asking questions. |
### Main Options
| Option | Description | | Option | Description |
|--------|-------------| |--------|-------------|
| `--pipeline` | **Enable pipeline (non-interactive) mode** — required for CI/automation | | `--pipeline` | **Enable pipeline (non-interactive) mode** — Required for CI/automation |
| `-t, --task <text>` | Task content (as alternative to GitHub issue) | | `-t, --task <text>` | Task content (alternative to GitHub Issue) |
| `-i, --issue <N>` | GitHub issue number (equivalent to `#N` in interactive mode) | | `-i, --issue <N>` | GitHub issue number (same as `#N` in interactive mode) |
| `-w, --workflow <name or path>` | Workflow name or path to workflow YAML file | | `-w, --workflow <name or path>` | Workflow name or path to workflow YAML file |
| `-b, --branch <name>` | Branch name (auto-generated if omitted) | | `-b, --branch <name>` | Specify branch name (auto-generated if omitted) |
| `--auto-pr` | Create PR after execution (interactive: skip confirmation, pipeline: enable PR) | | `--auto-pr` | Create PR (interactive: skip confirmation, pipeline: enable PR) |
| `--skip-git` | Skip branch creation, commit, and push (pipeline mode, workflow-only) | | `--skip-git` | Skip branch creation, commit, and push (pipeline mode, workflow-only) |
| `--repo <owner/repo>` | Repository for PR creation | | `--repo <owner/repo>` | Specify repository (for PR creation) |
| `--create-worktree <yes\|no>` | Skip worktree confirmation prompt | | `--create-worktree <yes\|no>` | Skip worktree confirmation prompt |
| `-q, --quiet` | Minimal output mode: suppress AI output (for CI) | | `-q, --quiet` | Minimal output mode: suppress AI output (for CI) |
| `--provider <name>` | Override agent provider (claude\|codex\|mock) | | `--provider <name>` | Override agent provider (claude\|codex\|mock) |
| `--model <name>` | Override agent model | | `--model <name>` | Override agent model |
| `--config <path>` | Path to global config file (default: `~/.takt/config.yaml`) |
## Workflows ## Workflows
TAKT uses YAML-based workflow definitions with rule-based routing. Builtin workflows are embedded in the package; user workflows in `~/.takt/workflows/` take priority. Use `takt eject` to copy a builtin to `~/.takt/` for customization. TAKT uses YAML-based workflow definitions and rule-based routing. Builtin workflows are embedded in the package, with user workflows in `~/.takt/workflows/` taking priority. Use `takt eject` to copy builtins to `~/.takt/` for customization.
### Example Workflow ### Workflow Example
```yaml ```yaml
name: default name: default
@ -191,7 +261,7 @@ steps:
model: opus model: opus
edit: false edit: false
rules: rules:
- condition: Plan complete - condition: Planning complete
next: implement next: implement
instruction_template: | instruction_template: |
Analyze the request and create an implementation plan. Analyze the request and create an implementation plan.
@ -203,7 +273,7 @@ steps:
rules: rules:
- condition: Implementation complete - condition: Implementation complete
next: review next: review
- condition: Cannot proceed - condition: Blocked
next: ABORT next: ABORT
instruction_template: | instruction_template: |
Implement based on the plan. Implement based on the plan.
@ -217,12 +287,12 @@ steps:
- condition: Needs fix - condition: Needs fix
next: implement next: implement
instruction_template: | instruction_template: |
Review the implementation for architecture and code quality. Review the implementation from architecture and code quality perspectives.
``` ```
### Agent-less Steps ### Agentless Steps
The `agent` field is optional. When omitted, the step executes using only the `instruction_template` without a system prompt. This is useful for simple tasks where agent behavior customization is not needed. The `agent` field is optional. When omitted, the step executes using only the `instruction_template` without a system prompt. This is useful for simple tasks that don't require agent behavior customization.
```yaml ```yaml
- name: summarize - name: summarize
@ -232,22 +302,22 @@ The `agent` field is optional. When omitted, the step executes using only the `i
- condition: Summary complete - condition: Summary complete
next: COMPLETE next: COMPLETE
instruction_template: | instruction_template: |
Read the reports and provide a brief summary. Read the report and provide a concise summary.
``` ```
You can also provide an inline system prompt as the `agent` value (when the specified file does not exist): You can also write an inline system prompt as the `agent` value (if the specified file doesn't exist):
```yaml ```yaml
- name: review - name: review
agent: "You are a code reviewer. Focus on readability and maintainability." agent: "You are a code reviewer. Focus on readability and maintainability."
edit: false edit: false
instruction_template: | instruction_template: |
Review the code for quality. Review code quality.
``` ```
### Parallel Steps ### Parallel Steps
Steps can execute sub-steps concurrently with aggregate evaluation: Execute sub-steps in parallel within a step and evaluate with aggregate conditions:
```yaml ```yaml
- name: reviewers - name: reviewers
@ -275,65 +345,54 @@ Steps can execute sub-steps concurrently with aggregate evaluation:
- `all("X")`: true if ALL sub-steps matched condition X - `all("X")`: true if ALL sub-steps matched condition X
- `any("X")`: true if ANY sub-step matched condition X - `any("X")`: true if ANY sub-step matched condition X
- Sub-step `rules` define possible outcomes; `next` is optional (parent handles routing) - Sub-step `rules` define possible outcomes, but `next` is optional (parent controls transition)
### Rule Condition Types ### Rule Condition Types
| Type | Syntax | Description | | Type | Syntax | Description |
|------|--------|-------------| |------|--------|-------------|
| Tag-based | `"condition text"` | Agent outputs `[STEP:N]` tag, matched by index | | Tag-based | `"condition text"` | Agent outputs `[STEP:N]` tag, matched by index |
| AI judge | `ai("condition text")` | AI evaluates the condition against agent output | | AI judge | `ai("condition text")` | AI evaluates condition against agent output |
| Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-step results | | Aggregate | `all("X")` / `any("X")` | Aggregates parallel sub-step matched conditions |
## Built-in Workflows ## Builtin Workflows
TAKT ships with several built-in workflows: TAKT includes multiple builtin workflows:
| Workflow | Description | | Workflow | Description |
|----------|-------------| |----------|-------------|
| `default` | Full development workflow: plan → architecture design → implement → AI review → parallel review (architect + security) → supervisor approval. Includes fix loops at each review stage. |
| `minimal` | Quick workflow: plan → implement → review → supervisor. Minimal steps for fast iteration. | | `minimal` | Quick workflow: plan → implement → review → supervisor. Minimal steps for fast iteration. |
| `default` | Full development workflow: plan → implement → AI review → parallel reviewers (architect + security) → supervisor approval. Includes fix loops for each review stage. | | `review-fix-minimal` | Review-focused workflow: review → fix → supervisor. For iterative improvement based on review feedback. |
| `review-fix-minimal` | Review-focused workflow: review → fix → supervisor. For iterative improvements based on review feedback. | | `research` | Research workflow: planner → digger → supervisor. Autonomously executes research without asking questions. |
| `research` | Research workflow: planner → digger → supervisor. Autonomously researches topics without asking questions. | | `expert` | Full-stack development workflow: architecture, frontend, security, QA reviews with fix loops. |
| `expert` | Sequential review with domain experts: Architecture, Frontend, Security, QA reviews with fix loops. | | `expert-cqrs` | Full-stack development workflow (CQRS+ES specialized): CQRS+ES, frontend, security, QA reviews with fix loops. |
| `expert-cqrs` | Sequential review with domain experts: CQRS+ES, Frontend, Security, QA reviews with fix loops. |
| `magi` | Deliberation system inspired by Evangelion. Three AI personas (MELCHIOR, BALTHASAR, CASPER) analyze and vote. | | `magi` | Deliberation system inspired by Evangelion. Three AI personas (MELCHIOR, BALTHASAR, CASPER) analyze and vote. |
| `review-only` | Read-only code review workflow without making any modifications. | | `review-only` | Read-only code review workflow that makes no changes. |
Switch between workflows with `takt switch`. Use `takt switch` to switch workflows.
## Built-in Agents ## Builtin Agents
| Agent | Description | | Agent | Description |
|-------|-------------| |-------|-------------|
| **planner** | Task analysis, spec investigation, and implementation planning | | **planner** | Task analysis, spec investigation, implementation planning |
| **coder** | Implements features and fixes bugs | | **coder** | Feature implementation, bug fixing |
| **ai-antipattern-reviewer** | Reviews for AI-specific anti-patterns (hallucinated APIs, incorrect assumptions, scope creep) | | **ai-antipattern-reviewer** | AI-specific antipattern review (non-existent APIs, incorrect assumptions, scope creep) |
| **architecture-reviewer** | Reviews architecture and code quality, verifies spec compliance | | **architecture-reviewer** | Architecture and code quality review, spec compliance verification |
| **security-reviewer** | Security vulnerability assessment | | **security-reviewer** | Security vulnerability assessment |
| **supervisor** | Final verification, validation, and approval | | **supervisor** | Final validation, approval |
## Custom Agents ## Custom Agents
Define custom agents in `.takt/agents.yaml`: Create agent prompts in Markdown files:
```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)
```
Or create agent prompt files as Markdown:
```markdown ```markdown
# ~/.takt/agents/my-agents/reviewer.md # ~/.takt/agents/my-agents/reviewer.md
You are a code reviewer focused on security. You are a code reviewer specialized in security.
## Your Role ## Role
- Check for security vulnerabilities - Check for security vulnerabilities
- Verify input validation - Verify input validation
- Review authentication logic - Review authentication logic
@ -341,33 +400,36 @@ You are a code reviewer focused on security.
## Model Selection ## Model Selection
The `model` field in workflow steps, agent configs, and global config is passed directly to the provider (Claude Code CLI or Codex SDK). TAKT does not resolve model aliases — the provider handles that. The `model` field (in workflow steps, agent config, or global config) is passed directly to the provider (Claude Code CLI / Codex SDK). TAKT does not resolve model aliases.
### Claude Code ### Claude Code
Claude Code supports aliases (`opus`, `sonnet`, `haiku`, `opusplan`, `default`) and full model names (e.g., `claude-sonnet-4-5-20250929`). See [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code) for available models. Claude Code supports aliases (`opus`, `sonnet`, `haiku`, `opusplan`, `default`) and full model names (e.g., `claude-sonnet-4-5-20250929`). Refer to the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code) for available models.
### Codex ### Codex
The model string is passed to the Codex SDK. Defaults to `codex` if not specified. See Codex documentation for available models. The model string is passed to the Codex SDK. If unspecified, defaults to `codex`. Refer to Codex documentation for available models.
## Project Structure ## Project Structure
``` ```
~/.takt/ ~/.takt/ # Global configuration directory
├── config.yaml # Global config (provider, model, workflows, etc.) ├── config.yaml # Global config (provider, model, workflow, etc.)
├── workflows/ # User workflow definitions (override builtins) ├── workflows/ # User workflow definitions (override builtins)
└── agents/ # User agent prompt files │ └── custom.yaml
└── agents/ # User agent prompt files (.md)
└── my-agent.md
.takt/ # Project-level config .takt/ # Project-level configuration
├── agents.yaml # Custom agent definitions ├── config.yaml # Project config (current workflow, etc.)
├── tasks/ # Pending task files (.yaml, .md) ├── tasks/ # Pending task files (.yaml, .md)
├── completed/ # Completed tasks with reports ├── completed/ # Completed tasks and reports
├── reports/ # Execution reports (auto-generated) ├── reports/ # Execution reports (auto-generated)
└── logs/ # Session logs in NDJSON format │ └── {timestamp}-{slug}/
├── latest.json # Pointer to current/latest session └── logs/ # NDJSON format session logs
├── previous.json # Pointer to previous session ├── latest.json # Pointer to current/latest session
└── {sessionId}.jsonl # NDJSON session log per workflow run ├── previous.json # Pointer to previous session
└── {sessionId}.jsonl # NDJSON session log per workflow execution
``` ```
Builtin resources are embedded in the npm package (`dist/resources/`). User files in `~/.takt/` take priority. Builtin resources are embedded in the npm package (`dist/resources/`). User files in `~/.takt/` take priority.
@ -385,15 +447,15 @@ provider: claude # Default provider: claude or codex
model: sonnet # Default model (optional) model: sonnet # Default model (optional)
# API Key configuration (optional) # API Key configuration (optional)
# Can be overridden by TAKT_ANTHROPIC_API_KEY / TAKT_OPENAI_API_KEY env vars # Can be overridden by environment variables TAKT_ANTHROPIC_API_KEY / TAKT_OPENAI_API_KEY
anthropic_api_key: sk-ant-... # For Claude (Anthropic) anthropic_api_key: sk-ant-... # For Claude (Anthropic)
# openai_api_key: sk-... # For Codex (OpenAI) # openai_api_key: sk-... # For Codex (OpenAI)
trusted_directories: trusted_directories:
- /path/to/trusted/dir - /path/to/trusted/dir
# Pipeline execution settings (optional) # Pipeline execution configuration (optional)
# Customize branch naming, commit messages, and PR body for pipeline mode. # Customize branch names, commit messages, and PR body.
# pipeline: # pipeline:
# default_branch_prefix: "takt/" # default_branch_prefix: "takt/"
# commit_message_template: "feat: {title} (#{issue})" # commit_message_template: "feat: {title} (#{issue})"
@ -403,63 +465,106 @@ trusted_directories:
# Closes #{issue} # Closes #{issue}
``` ```
**API Key configuration:** **API Key Configuration Methods:**
1. **Using environment variables** (recommended): 1. **Set via environment variables**:
```bash ```bash
export TAKT_ANTHROPIC_API_KEY=sk-ant-... # For Claude export TAKT_ANTHROPIC_API_KEY=sk-ant-... # For Claude
# or # or
export TAKT_OPENAI_API_KEY=sk-... # For Codex export TAKT_OPENAI_API_KEY=sk-... # For Codex
``` ```
2. **Using config file**: 2. **Set in config file**:
Add `anthropic_api_key` or `openai_api_key` to `~/.takt/config.yaml` as shown above Write `anthropic_api_key` or `openai_api_key` in `~/.takt/config.yaml` as shown above
Priority: Environment variables > `config.yaml` settings Priority: Environment variables > `config.yaml` settings
**Note**: When API keys are configured, Claude Code or Codex installation is not required. TAKT will call Anthropic API or OpenAI API directly. **Notes:**
- If you set an API Key, installing Claude Code or Codex is not necessary. TAKT directly calls the Anthropic API or OpenAI API.
- **Security**: If you write API Keys in `config.yaml`, be careful not to commit this file to Git. Consider using environment variables or adding `~/.takt/config.yaml` to `.gitignore`.
**Pipeline template variables:** **Pipeline Template Variables:**
| Variable | Available in | Description | | Variable | Available In | Description |
|----------|-------------|-------------| |----------|-------------|-------------|
| `{title}` | commit message | Issue title | | `{title}` | Commit message | Issue title |
| `{issue}` | commit message, PR body | Issue number | | `{issue}` | Commit message, PR body | Issue number |
| `{issue_body}` | PR body | Issue body text | | `{issue_body}` | PR body | Issue body |
| `{report}` | PR body | Workflow execution report | | `{report}` | PR body | Workflow execution report |
**Model Resolution Priority:** **Model Resolution Priority:**
1. Workflow step `model` (highest priority) 1. Workflow step `model` (highest priority)
2. Custom agent `model` 2. Custom agent `model`
3. Global config `model` 3. Global config `model`
4. Provider default (Claude: sonnet, Codex: gpt-5.2-codex) 4. Provider default (Claude: sonnet, Codex: codex)
## Detailed Guides
## Practical Usage Guide ### Task File Formats
### Interactive Workflow TAKT supports batch processing with task files in `.takt/tasks/`. Both `.yaml`/`.yml` and `.md` file formats are supported.
When running `takt` (interactive planning mode) or `takt #6` (GitHub issue), you are prompted to: **YAML format** (recommended, supports worktree/branch/workflow options):
1. **Select a workflow** - Choose from available workflows (arrow keys, ESC to cancel) ```yaml
2. **Create an isolated clone** (optional) - Run the task in a `git clone --shared` for isolation # .takt/tasks/add-auth.yaml
3. **Create a pull request** (after worktree execution) - Create a PR from the task branch task: "Add authentication feature"
worktree: true # Execute in isolated shared clone
branch: "feat/add-auth" # Branch name (auto-generated if omitted)
workflow: "default" # Workflow specification (uses current if omitted)
```
If `--auto-pr` is specified, the PR confirmation is skipped and the PR is created automatically. **Markdown format** (simple, backward compatible):
```markdown
# .takt/tasks/add-login-feature.md
Add login feature to the application.
Requirements:
- Username and password fields
- Form validation
- Error handling on failure
```
#### Isolated Execution with Shared Clone
Specifying `worktree` in YAML task files executes each task in an isolated clone created with `git clone --shared`, keeping your main working directory clean:
- `worktree: true` - Auto-create shared clone in adjacent directory (or location specified by `worktree_dir` 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` - Execute in current directory (default)
> **Note**: The YAML field name remains `worktree` for backward compatibility. Internally, it uses `git clone --shared` instead of `git worktree`. Git worktrees have a `.git` file containing `gitdir:` pointing to the main repository, which Claude Code follows to recognize the main repository as the project root. Shared clones have an independent `.git` directory, preventing this issue.
Clones are ephemeral. After task completion, they auto-commit + push, then delete the clone. Branches are the only persistent artifacts. Use `takt list` to list, merge, or delete branches.
### Session Logs
TAKT writes session logs in NDJSON (`.jsonl`) format to `.takt/logs/`. Each record is atomically appended, so partial logs are preserved even if the process crashes, and you can track in real-time with `tail -f`.
- `.takt/logs/latest.json` - Pointer to current (or latest) session
- `.takt/logs/previous.json` - Pointer to previous session
- `.takt/logs/{sessionId}.jsonl` - NDJSON session log per workflow execution
Record types: `workflow_start`, `step_start`, `step_complete`, `workflow_complete`, `workflow_abort`
Agents can read `previous.json` to inherit context from the previous execution. Session continuation is automatic — just run `takt "task"` to continue from the previous session.
### Adding Custom Workflows ### Adding Custom Workflows
Create your own workflow by adding YAML files to `~/.takt/workflows/`, or use `/eject` to customize a builtin: Add YAML files to `~/.takt/workflows/` or customize builtins with `takt eject`:
```bash ```bash
# Copy the default workflow to ~/.takt/workflows/ for editing # Copy default workflow to ~/.takt/workflows/ and edit
takt eject default takt eject default
``` ```
```yaml ```yaml
# ~/.takt/workflows/my-workflow.yaml # ~/.takt/workflows/my-workflow.yaml
name: my-workflow name: my-workflow
description: My custom workflow description: Custom workflow
max_iterations: 5 max_iterations: 5
initial_step: analyze initial_step: analyze
@ -471,7 +576,7 @@ steps:
- condition: Analysis complete - condition: Analysis complete
next: implement next: implement
instruction_template: | instruction_template: |
Analyze this request thoroughly. Thoroughly analyze this request.
- name: implement - name: implement
agent: ~/.takt/agents/default/coder.md agent: ~/.takt/agents/default/coder.md
@ -479,179 +584,80 @@ steps:
permission_mode: edit permission_mode: edit
pass_previous_response: true pass_previous_response: true
rules: rules:
- condition: Done - condition: Complete
next: COMPLETE next: COMPLETE
instruction_template: | instruction_template: |
Implement based on the analysis. Implement based on the analysis.
``` ```
> **Note**: `{task}`, `{previous_response}`, and `{user_inputs}` are auto-injected into instructions. You only need explicit placeholders if you want to control their position in the template. > **Note**: `{task}`, `{previous_response}`, `{user_inputs}` are automatically injected into instructions. Explicit placeholders are only needed if you want to control their position in the template.
### Specifying Agents by Path ### Specifying Agents by Path
Agents are specified using file paths in workflow definitions: In workflow definitions, specify agents using file paths:
```yaml ```yaml
# Relative to workflow file directory # Relative path from workflow file
agent: ../agents/default/coder.md agent: ../agents/default/coder.md
# Home directory # Home directory
agent: ~/.takt/agents/default/coder.md agent: ~/.takt/agents/default/coder.md
# Absolute paths # Absolute path
agent: /path/to/custom/agent.md agent: /path/to/custom/agent.md
``` ```
### 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 `takt add`
```bash
# Start AI conversation to define and add a task
takt add
# Add task from GitHub issue (issue number reflected in branch name)
takt add #28
```
The `takt add` command starts an AI conversation where you discuss and refine your task requirements. After confirming with `/go`, the AI summarizes the conversation and creates a YAML task file with optional worktree/branch/workflow settings. When using `takt add #N`, the issue number is automatically reflected in the branch name (e.g., `takt/issue-28-...`).
#### Task File Formats
**YAML format** (recommended, supports worktree/branch/workflow options):
```yaml
# .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):
```markdown
# .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 list` to list, try-merge, or delete task branches.
#### Running Tasks with `/run-tasks`
```bash
takt run
```
- 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`
```bash
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
#### Listing Task Branches with `/list-tasks`
```bash
takt list
```
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 in NDJSON (`.jsonl`) format to `.takt/logs/`. Each record is appended atomically, so even if the process crashes mid-execution, partial logs are preserved and logs can be tailed in real-time with `tail -f`.
- `.takt/logs/latest.json` - Pointer to the current (or most recent) session
- `.takt/logs/previous.json` - Pointer to the previous session
- `.takt/logs/{sessionId}.jsonl` - NDJSON session log with step history
Record types: `workflow_start`, `step_start`, `step_complete`, `workflow_complete`, `workflow_abort`.
Agents can read `previous.json` to pick up context from a prior run. Session continuity is automatic — simply run `takt "task"` to continue where the previous session left off.
### Workflow Variables ### Workflow Variables
Available variables in `instruction_template`: Variables available in `instruction_template`:
| Variable | Description | | Variable | Description |
|----------|-------------| |----------|-------------|
| `{task}` | Original user request (auto-injected if not in template) | | `{task}` | Original user request (auto-injected if not in template) |
| `{iteration}` | Workflow-wide turn count (total steps executed) | | `{iteration}` | Workflow-wide turn count (total steps executed) |
| `{max_iterations}` | Maximum iterations allowed | | `{max_iterations}` | Maximum iteration count |
| `{step_iteration}` | Per-step iteration count (how many times THIS step has run) | | `{step_iteration}` | Per-step iteration count (times this step has been executed) |
| `{previous_response}` | Previous step's output (auto-injected if not in template) | | `{previous_response}` | Output from previous step (auto-injected if not in template) |
| `{user_inputs}` | Additional user inputs during workflow (auto-injected if not in template) | | `{user_inputs}` | Additional user inputs during workflow (auto-injected if not in template) |
| `{report_dir}` | Report directory path (e.g., `.takt/reports/20250126-143052-task-summary`) | | `{report_dir}` | Report directory path (e.g., `.takt/reports/20250126-143052-task-summary`) |
| `{report:filename}` | Resolves to `{report_dir}/filename` (e.g., `{report:00-plan.md}`) | | `{report:filename}` | Expands to `{report_dir}/filename` (e.g., `{report:00-plan.md}`) |
### Designing Workflows ### Workflow Design
Each workflow step requires: Elements needed for each workflow step:
**1. Agent** - A Markdown file containing the system prompt: **1. Agent** - Markdown file containing system prompt:
```yaml ```yaml
agent: ../agents/default/coder.md # Path to agent prompt file agent: ../agents/default/coder.md # Path to agent prompt file
agent_name: coder # Display name (optional) agent_name: coder # Display name (optional)
``` ```
**2. Rules** - Define how the step routes to the next step. The instruction builder auto-injects status output rules so agents know what tags to output: **2. Rules** - Define routing from step to next step. The instruction builder auto-injects status output rules, so agents know which tags to output:
```yaml ```yaml
rules: rules:
- condition: "Implementation complete" - condition: "Implementation complete"
next: review next: review
- condition: "Cannot proceed" - condition: "Blocked"
next: ABORT next: ABORT
``` ```
Special `next` values: `COMPLETE` (success), `ABORT` (failure). Special `next` values: `COMPLETE` (success), `ABORT` (failure)
**3. Step options:** **3. Step Options:**
| Option | Default | Description | | Option | Default | Description |
|--------|---------|-------------| |--------|---------|-------------|
| `edit` | - | Whether the step can edit project files (`true`/`false`) | | `edit` | - | Whether step can edit project files (`true`/`false`) |
| `pass_previous_response` | `true` | Pass previous step's output to `{previous_response}` | | `pass_previous_response` | `true` | Pass previous step output to `{previous_response}` |
| `allowed_tools` | - | List of tools the agent can use (Read, Glob, Grep, Edit, Write, Bash, etc.) | | `allowed_tools` | - | List of tools agent can use (Read, Glob, Grep, Edit, Write, Bash, etc.) |
| `provider` | - | Override provider for this step (`claude` or `codex`) | | `provider` | - | Override provider for this step (`claude` or `codex`) |
| `model` | - | Override model for this step | | `model` | - | Override model for this step |
| `permission_mode` | - | Permission mode: `readonly`, `edit`, or `full` (provider-independent) | | `permission_mode` | - | Permission mode: `readonly`, `edit`, `full` (provider-independent) |
| `report` | - | Report file configuration (name, format) for auto-generated reports | | `report` | - | Auto-generated report file settings (name, format) |
## API Usage ## API Usage Example
```typescript ```typescript
import { WorkflowEngine, loadWorkflow } from 'takt'; // npm install takt import { WorkflowEngine, loadWorkflow } from 'takt'; // npm install takt
@ -671,15 +677,15 @@ await engine.run();
## Contributing ## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md) for details. See [CONTRIBUTING.md](../CONTRIBUTING.md) for details.
## CI/CD Integration ## CI/CD Integration
### GitHub Actions ### GitHub Actions
TAKT provides a GitHub Action for automated PR reviews and task execution. See [takt-action](https://github.com/nrslib/takt-action) for details. TAKT provides a GitHub Action for automating PR reviews and task execution. See [takt-action](https://github.com/nrslib/takt-action) for details.
**Example workflow** (see [.github/workflows/takt-action.yml](.github/workflows/takt-action.yml) in this repository): **Workflow example** (see [.github/workflows/takt-action.yml](../.github/workflows/takt-action.yml) in this repository):
```yaml ```yaml
name: TAKT name: TAKT
@ -708,21 +714,21 @@ jobs:
github_token: ${{ secrets.GITHUB_TOKEN }} github_token: ${{ secrets.GITHUB_TOKEN }}
``` ```
**Cost Warning**: TAKT uses AI APIs (Claude or OpenAI) which can incur significant costs, especially in CI/CD environments where tasks run automatically. Monitor your API usage and set billing alerts. **Cost Warning**: TAKT uses AI APIs (Claude or OpenAI), which can incur significant costs, especially when tasks are auto-executed in CI/CD environments. Monitor API usage and set up billing alerts.
### Other CI Systems ### Other CI Systems
For non-GitHub CI systems, use pipeline mode: For CI systems other than GitHub, use pipeline mode:
```bash ```bash
# Install takt # Install takt
npm install -g takt npm install -g takt
# Run in pipeline mode # Run in pipeline mode
takt --pipeline --task "fix bug" --auto-pr --repo owner/repo takt --pipeline --task "Fix bug" --auto-pr --repo owner/repo
``` ```
Set `TAKT_ANTHROPIC_API_KEY` or `TAKT_OPENAI_API_KEY` environment variables for authentication (TAKT-specific prefixed variables). For authentication, set `TAKT_ANTHROPIC_API_KEY` or `TAKT_OPENAI_API_KEY` environment variables (TAKT-specific prefix).
```bash ```bash
# For Claude (Anthropic) # For Claude (Anthropic)
@ -732,34 +738,14 @@ export TAKT_ANTHROPIC_API_KEY=sk-ant-...
export TAKT_OPENAI_API_KEY=sk-... export TAKT_OPENAI_API_KEY=sk-...
``` ```
## Docker Support
Docker environment is provided for testing in other environments:
```bash
# 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 ## Documentation
- [Workflow Guide](./docs/workflows.md) - Create and customize workflows - [Workflow Guide](./docs/workflows.md) - Creating and customizing workflows
- [Agent Guide](./docs/agents.md) - Configure custom agents - [Agent Guide](./docs/agents.md) - Configuring custom agents
- [Changelog](./CHANGELOG.md) - Version history - [Changelog](../CHANGELOG.md) - Version history
- [Security Policy](./SECURITY.md) - Vulnerability reporting - [Security Policy](../SECURITY.md) - Vulnerability reporting
- [Blog: TAKT - AI Agent Orchestration](https://zenn.dev/nrs/articles/c6842288a526d7) - Design philosophy and practical usage guide (Japanese) - [Blog: TAKT - AI Agent Orchestration](https://zenn.dev/nrs/articles/c6842288a526d7) - Design philosophy and practical usage guide (Japanese)
## License ## License
MIT - See [LICENSE](./LICENSE) for details. MIT - See [LICENSE](../LICENSE) for details.

2
docs/README.ja.md
View File

@ -58,7 +58,7 @@ takt hello
**フロー:** **フロー:**
1. ワークフロー選択 1. ワークフロー選択
2. AI との会話でタスク内容を整理 2. AI との会話でタスク内容を整理
3. `/go` でタスク指示を確定 3. `/go` でタスク指示を確定（`/go 追加の指示` のように指示を追加することも可能）
4. 実行（worktree 作成、ワークフロー実行、PR 作成） 4. 実行（worktree 作成、ワークフロー実行、PR 作成）
#### 実行例 #### 実行例

29
src/features/interactive/interactive.ts
View File

@ -11,15 +11,12 @@
*/ */
import * as readline from 'node:readline'; import * as readline from 'node:readline';
import { existsSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import chalk from 'chalk'; import chalk from 'chalk';
import type { Language } from '../../core/models/index.js'; import type { Language } from '../../core/models/index.js';
import { loadGlobalConfig, loadAgentSessions, updateAgentSession } from '../../infra/config/index.js'; import { loadGlobalConfig, loadAgentSessions, updateAgentSession } from '../../infra/config/index.js';
import { isQuietMode } from '../../shared/context.js'; import { isQuietMode } from '../../shared/context.js';
import { getProvider, type ProviderType } from '../../infra/providers/index.js'; import { getProvider, type ProviderType } from '../../infra/providers/index.js';
import { selectOption } from '../../shared/prompt/index.js'; import { selectOption } from '../../shared/prompt/index.js';
import { getLanguageResourcesDir } from '../../infra/resources/index.js';
import { createLogger, getErrorMessage } from '../../shared/utils/index.js'; import { createLogger, getErrorMessage } from '../../shared/utils/index.js';
import { info, error, blankLine, StreamDisplay } from '../../shared/ui/index.js'; import { info, error, blankLine, StreamDisplay } from '../../shared/ui/index.js';
import { getPrompt, getPromptObject } from '../../shared/prompts/index.js'; import { getPrompt, getPromptObject } from '../../shared/prompts/index.js';
@ -41,31 +38,9 @@ function resolveLanguage(lang?: Language): 'en' | 'ja' {
return lang === 'ja' ? 'ja' : 'en'; return lang === 'ja' ? 'ja' : 'en';
} }
function readPromptFile(lang: 'en' | 'ja', fileName: string, fallback: string): string {
const filePath = join(getLanguageResourcesDir(lang), 'prompts', fileName);
if (existsSync(filePath)) {
return readFileSync(filePath, 'utf-8').trim();
}
if (lang !== 'en') {
const enPath = join(getLanguageResourcesDir('en'), 'prompts', fileName);
if (existsSync(enPath)) {
return readFileSync(enPath, 'utf-8').trim();
}
}
return fallback.trim();
}
function getInteractivePrompts(lang: 'en' | 'ja', workflowContext?: WorkflowContext) { function getInteractivePrompts(lang: 'en' | 'ja', workflowContext?: WorkflowContext) {
let systemPrompt = readPromptFile( let systemPrompt = getPrompt('interactive.systemPrompt', lang);
lang, let summaryPrompt = getPrompt('interactive.summaryPrompt', lang);
'interactive-system.md',
getPrompt('interactive.systemPrompt', lang),
);
let summaryPrompt = readPromptFile(
lang,
'interactive-summary.md',
getPrompt('interactive.summaryPrompt', lang),
);
// Add workflow context to prompts if available // Add workflow context to prompts if available
if (workflowContext) { if (workflowContext) {