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

docs: 全ドキュメントに copilot プロバイダーを追加し、Claude Code 寄りの記述をプロバイダー中立に修正

Browse Source
This commit is contained in:
nrslib 2026-03-02 13:14:08 +09:00
parent 532b1961a7
commit 0201056f34
11 changed files with 64 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
README.md
View File

@ -4,7 +4,7 @@
**T**AKT **A**gent **K**oordination **T**opology — Give your AI coding agents structured review loops, managed prompts, and guardrails — so they deliver quality code, not just code.
TAKT runs AI agents (Claude Code, Codex, OpenCode, Cursor, Copilot) through YAML-defined workflows with built-in review cycles. You talk to AI to define what you want, queue tasks, and let TAKT handle the execution — planning, implementation, multi-stage review, and fix loops — all governed by declarative piece files.
TAKT runs AI agents (Claude Code, Codex, OpenCode, Cursor, GitHub Copilot CLI) through YAML-defined workflows with built-in review cycles. You talk to AI to define what you want, queue tasks, and let TAKT handle the execution — planning, implementation, multi-stage review, and fix loops — all governed by declarative piece files.
TAKT is built with TAKT itself (dogfooding).
@ -22,8 +22,8 @@ TAKT is built with TAKT itself (dogfooding).
Choose one:
- **Provider CLIs**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [OpenCode](https://opencode.ai), [Cursor Agent](https://docs.cursor.com/), or [GitHub Copilot](https://github.com/features/copilot) installed
- **Direct API**: Anthropic / OpenAI / OpenCode / Cursor API Key (no CLI required)
- **Provider CLIs**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [OpenCode](https://opencode.ai), [Cursor Agent](https://docs.cursor.com/), or [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) installed
- **Direct API**: Anthropic / OpenAI / OpenCode API Key (no CLI required)
Optional:
@ -44,8 +44,9 @@ $ takt
Select piece:
❯ 🎼 default (current)
📁 Development/
📁 Research/
📁 🚀 Quick Start/
📁 🎨 Frontend/
📁 ⚙️ Backend/
> Add user authentication with JWT
@ -155,13 +156,14 @@ model: sonnet # passed directly to provider
language: en # en or ja
```
Or use API keys directly (no CLI installation required):
Or use API keys directly (no CLI installation required for Claude, Codex, OpenCode):
```bash
export TAKT_ANTHROPIC_API_KEY=sk-ant-... # Anthropic (Claude)
export TAKT_OPENAI_API_KEY=sk-... # OpenAI (Codex)
export TAKT_OPENCODE_API_KEY=... # OpenCode
export TAKT_CURSOR_API_KEY=... # Cursor Agent (optional if logged in)
export TAKT_COPILOT_GITHUB_TOKEN=ghp_... # GitHub Copilot CLI
```
See the [Configuration Guide](./docs/configuration.md) for all options, provider profiles, and model resolution.

9
docs/README.ja.md
View File

@ -4,7 +4,7 @@
**T**AKT **A**gent **K**oordination **T**opology — AI コーディングエージェントにレビューループ・プロンプト管理・ガードレールを与え、「とりあえず動くコード」ではなく「品質の高いコード」を出させるツールです。
AI と会話してやりたいことを決め、タスクとして積み、`takt run` で実行します。計画・実装・レビュー・修正のループは YAML の piece ファイルで定義されており、エージェント任せにはしません。Claude Code、Codex、OpenCode、Cursor、Copilot に対応しています。
AI と会話してやりたいことを決め、タスクとして積み、`takt run` で実行します。計画・実装・レビュー・修正のループは YAML の piece ファイルで定義されており、エージェント任せにはしません。Claude Code、Codex、OpenCode、Cursor、GitHub Copilot CLI に対応しています。
TAKT は TAKT 自身で開発しています（ドッグフーディング）。
@ -22,8 +22,8 @@ TAKT は TAKT 自身で開発しています（ドッグフーディング）。
次のいずれかが必要です。
- **プロバイダー CLI**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[Codex](https://github.com/openai/codex)、[OpenCode](https://opencode.ai)、[Cursor Agent](https://docs.cursor.com/)、[GitHub Copilot](https://github.com/features/copilot) のいずれか
- **API Key 直接利用**: Anthropic / OpenAI / OpenCode / Cursor の API Key があれば CLI は不要です
- **プロバイダー CLI**: [Claude Code](https://docs.anthropic.com/en/docs/claude-code)、[Codex](https://github.com/openai/codex)、[OpenCode](https://opencode.ai)、[Cursor Agent](https://docs.cursor.com/)、[GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) のいずれか
- **API Key 直接利用**: Anthropic / OpenAI / OpenCode の API Key があれば CLI は不要です
任意:
@ -167,13 +167,14 @@ model: sonnet # プロバイダーにそのまま渡されます
language: ja # en or ja
```
API Key を直接使う場合は、CLI のインストールは不要です。
API Key を直接使う場合は、CLI のインストールは不要です（Claude、Codex、OpenCode が対象）。
```bash
export TAKT_ANTHROPIC_API_KEY=sk-ant-... # Anthropic (Claude)
export TAKT_OPENAI_API_KEY=sk-... # OpenAI (Codex)
export TAKT_OPENCODE_API_KEY=... # OpenCode
export TAKT_CURSOR_API_KEY=... # Cursor Agent（login 済みなら省略可）
export TAKT_COPILOT_GITHUB_TOKEN=ghp_... # GitHub Copilot CLI
```
全設定項目・プロバイダープロファイル・モデル解決の詳細は [Configuration Guide](./configuration.ja.md) を参照してください。

12
docs/ci-cd.ja.md
View File

@ -66,7 +66,7 @@ Pipeline モードでは、`--auto-pr` を明示的に指定しない限り PR
| `--skip-git` | ブランチ作成、コミット、プッシュをスキップ（pipeline モード、piece のみ実行） |
| `--repo <owner/repo>` | リポジトリを指定（PR 作成用） |
| `-q, --quiet` | 最小出力モード: AI 出力を抑制（CI 向け） |
| `--provider <name>` | エージェント provider を上書き（claude\|codex\|opencode\|mock） |
| `--provider <name>` | エージェント provider を上書き（claude\|codex\|opencode\|cursor\|copilot\|mock） |
| `--model <name>` | エージェントモデルを上書き |
### コマンド例
@ -161,15 +161,21 @@ export TAKT_OPENAI_API_KEY=sk-...
# OpenCode 用
export TAKT_OPENCODE_API_KEY=...
# Cursor Agent 用（cursor-agent login 済みなら省略可）
export TAKT_CURSOR_API_KEY=...
# GitHub Copilot CLI 用
export TAKT_COPILOT_GITHUB_TOKEN=ghp_...
```
優先順位: 環境変数は `config.yaml` の設定よりも優先されます。
> **注意**: 環境変数で API キーを設定すれば、Claude Code、Codex、OpenCode CLI のインストールは不要です。TAKT が対応する API を直接呼び出します。
> **注意**: 環境変数で API キーを設定すれば、対応する CLI（Claude Code、Codex、OpenCode）のインストールは不要です。TAKT が対応する API を直接呼び出します。Cursor と Copilot は CLI のインストールが必要です。
## コストに関する注意
TAKT は AI API（Claude または OpenAI）を使用するため、特に CI/CD 環境でタスクが自動実行される場合、大きなコストが発生する可能性があります。次の点に注意してください。
TAKT は AI API（Anthropic、OpenAI など）を使用するため、特に CI/CD 環境でタスクが自動実行される場合、大きなコストが発生する可能性があります。次の点に注意してください。
- **API 使用量の監視**: 予期しない請求を避けるため、AI provider で課金アラートを設定してください。
- **`--quiet` モードの使用**: 出力量は削減されますが、API 呼び出し回数は減りません。

12
docs/ci-cd.md
View File

@ -66,7 +66,7 @@ In pipeline mode, PRs are **not** created unless `--auto-pr` is explicitly speci
| `--skip-git` | Skip branch creation, commit, and push (pipeline mode, piece-only) |
| `--repo <owner/repo>` | Specify repository (for PR creation) |
| `-q, --quiet` | Minimal output mode: suppress AI output (for CI) |
| `--provider <name>` | Override agent provider (claude\|codex\|opencode\|mock) |
| `--provider <name>` | Override agent provider (claude\|codex\|opencode\|cursor\|copilot\|mock) |
| `--model <name>` | Override agent model |
### Command Examples
@ -161,15 +161,21 @@ export TAKT_OPENAI_API_KEY=sk-...
# For OpenCode
export TAKT_OPENCODE_API_KEY=...
# For Cursor Agent (optional if cursor-agent login session exists)
export TAKT_CURSOR_API_KEY=...
# For GitHub Copilot CLI
export TAKT_COPILOT_GITHUB_TOKEN=ghp_...
```
Priority: Environment variables take precedence over `config.yaml` settings.
> **Note**: If you set an API key via environment variable, installing Claude Code, Codex, or OpenCode CLI is not necessary. TAKT directly calls the respective API.
> **Note**: If you set an API key via environment variable, installing the corresponding CLI (Claude Code, Codex, OpenCode) is not necessary. TAKT directly calls the respective API. Cursor and Copilot require their CLIs to be installed.
## Cost Considerations
TAKT uses AI APIs (Claude or OpenAI), which can incur significant costs, especially when tasks are auto-executed in CI/CD environments. Take the following precautions:
TAKT uses AI APIs (Anthropic, OpenAI, etc.), which can incur significant costs, especially when tasks are auto-executed in CI/CD environments. Take the following precautions:
- **Monitor API usage**: Set up billing alerts with your AI provider to avoid unexpected charges.
- **Use `--quiet` mode**: Reduces output volume but does not reduce API calls.

18
docs/configuration.ja.md
View File

@ -114,8 +114,7 @@ interactive_preview_movements: 3 # インタラクティブモードでの move
| `openai_api_key` | string | - | Codex 用 OpenAI API キー |
| `opencode_api_key` | string | - | OpenCode API キー |
| `cursor_api_key` | string | - | Cursor API キー（省略時は login セッションへフォールバック） |
| `copilot_github_token` | string | - | Copilot 認証用 GitHub トークン |
| `claude_cli_path` | string | - | Claude Code CLI バイナリパス上書き（絶対パス） |
| `copilot_github_token` | string | - | Copilot CLI 認証用 GitHub トークン |
| `codex_cli_path` | string | - | Codex CLI バイナリパス上書き（絶対パス） |
| `cursor_cli_path` | string | - | Cursor Agent CLI バイナリパス上書き（絶対パス） |
| `copilot_cli_path` | string | - | Copilot CLI バイナリパス上書き（絶対パス） |
@ -172,7 +171,7 @@ concurrency: 2 # このプロジェクトでの takt run 並列
## API キー設定
TAKT は5つの provider をサポートしています。Claude/Codex/OpenCode は API キーを使い、Cursor は API キーまたは `cursor-agent login` セッションで認証でき、Copilot は GitHub トークンで認証します。
TAKT は5つの provider をサポートしています。Claude/Codex/OpenCode は API キーを使い、Cursor は API キーまたは `cursor-agent login` セッションで認証でき、Copilot は GitHub トークンを使います。
### 環境変数（推奨）
@ -189,8 +188,8 @@ export TAKT_OPENCODE_API_KEY=...
# Cursor Agent 用（cursor-agent login 済みなら省略可）
export TAKT_CURSOR_API_KEY=...
# Copilot 用（GitHub トークン）
export TAKT_COPILOT_GITHUB_TOKEN=...
# GitHub Copilot CLI 用
export TAKT_COPILOT_GITHUB_TOKEN=ghp_...
```
### 設定ファイル
@ -201,7 +200,7 @@ anthropic_api_key: sk-ant-... # Claude 用
openai_api_key: sk-... # Codex 用
opencode_api_key: ... # OpenCode 用
cursor_api_key: ... # Cursor Agent 用（省略可）
copilot_github_token: ... # Copilot 用（GitHub トークン）
copilot_github_token: ghp_... # GitHub Copilot CLI 用
```
### 優先順位
@ -214,7 +213,7 @@ copilot_github_token: ... # Copilot 用（GitHub トークン）
| Codex (OpenAI) | `TAKT_OPENAI_API_KEY` | `openai_api_key` |
| OpenCode | `TAKT_OPENCODE_API_KEY` | `opencode_api_key` |
| Cursor Agent | `TAKT_CURSOR_API_KEY` | `cursor_api_key` |
| Copilot | `TAKT_COPILOT_GITHUB_TOKEN` | `copilot_github_token` |
| GitHub Copilot CLI | `TAKT_COPILOT_GITHUB_TOKEN` | `copilot_github_token` |
### セキュリティ
@ -223,6 +222,7 @@ copilot_github_token: ... # Copilot 用（GitHub トークン）
- 必要に応じて `~/.takt/config.yaml` をグローバル `.gitignore` に追加してください。
- Cursor provider は `cursor-agent login` が済んでいれば API キーなしでも動作できます。
- API キーを設定すれば、対応する CLI ツール（Claude Code、Codex、OpenCode）のインストールは不要です。TAKT が対応する API を直接呼び出します。
- Copilot provider は `copilot` CLI のインストールが必要です。GitHub トークンは認証に使用されます。
### CLI パス上書き
@ -258,7 +258,7 @@ copilot_cli_path: /usr/local/bin/github-copilot-cli
1. **Piece movement の `model`** - piece YAML の movement 定義で指定
2. **グローバル設定の `model`** - `~/.takt/config.yaml` のデフォルトモデル
3. **Provider デフォルト** - provider のビルトインデフォルトにフォールバック（Claude: `sonnet`、Codex: `codex`、OpenCode: provider デフォルト、Cursor: CLI デフォルト）
3. **Provider デフォルト** - provider のビルトインデフォルトにフォールバック（Claude: `sonnet`、Codex: `codex`、OpenCode: provider デフォルト、Cursor: CLI デフォルト、Copilot: CLI デフォルト）
### Provider 固有のモデルに関する注意
@ -270,7 +270,7 @@ copilot_cli_path: /usr/local/bin/github-copilot-cli
**Cursor Agent** は `model` を `cursor-agent --model <model>` にそのまま渡します。省略時は Cursor CLI のデフォルトが使用されます。
**Copilot** は `model` を Copilot CLI の `--model <model>` フラグにそのまま渡します。省略時は Copilot CLI のデフォルトが使用されます。
**GitHub Copilot CLI** は `model` を `copilot --model <model>` にそのまま渡します。省略時は Copilot CLI のデフォルトが使用されます。
### 設定例

16
docs/configuration.md
View File

@ -114,8 +114,7 @@ interactive_preview_movements: 3 # Movement previews in interactive mode (0-10,
| `openai_api_key` | string | - | OpenAI API key for Codex |
| `opencode_api_key` | string | - | OpenCode API key |
| `cursor_api_key` | string | - | Cursor API key (optional; login session fallback supported) |
| `copilot_github_token` | string | - | GitHub token for Copilot authentication |
| `claude_cli_path` | string | - | Claude Code CLI binary path override (absolute) |
| `copilot_github_token` | string | - | GitHub token for Copilot CLI authentication |
| `codex_cli_path` | string | - | Codex CLI binary path override (absolute) |
| `cursor_cli_path` | string | - | Cursor Agent CLI binary path override (absolute) |
| `copilot_cli_path` | string | - | Copilot CLI binary path override (absolute) |
@ -189,8 +188,8 @@ export TAKT_OPENCODE_API_KEY=...
# For Cursor Agent (optional if cursor-agent login session exists)
export TAKT_CURSOR_API_KEY=...
# For Copilot (GitHub token)
export TAKT_COPILOT_GITHUB_TOKEN=...
# For GitHub Copilot CLI
export TAKT_COPILOT_GITHUB_TOKEN=ghp_...
```
### Config File
@ -201,7 +200,7 @@ anthropic_api_key: sk-ant-... # For Claude
openai_api_key: sk-... # For Codex
opencode_api_key: ... # For OpenCode
cursor_api_key: ... # For Cursor Agent (optional)
copilot_github_token: ... # For Copilot (GitHub token)
copilot_github_token: ghp_... # For GitHub Copilot CLI
```
### Priority
@ -214,7 +213,7 @@ Environment variables take precedence over `config.yaml` settings.
| Codex (OpenAI) | `TAKT_OPENAI_API_KEY` | `openai_api_key` |
| OpenCode | `TAKT_OPENCODE_API_KEY` | `opencode_api_key` |
| Cursor Agent | `TAKT_CURSOR_API_KEY` | `cursor_api_key` |
| Copilot | `TAKT_COPILOT_GITHUB_TOKEN` | `copilot_github_token` |
| GitHub Copilot CLI | `TAKT_COPILOT_GITHUB_TOKEN` | `copilot_github_token` |
### Security
@ -223,6 +222,7 @@ Environment variables take precedence over `config.yaml` settings.
- Add `~/.takt/config.yaml` to your global `.gitignore` if needed.
- Cursor provider can run without API key when `cursor-agent login` is already configured.
- If you set an API key, installing the corresponding CLI tool (Claude Code, Codex, OpenCode) is not necessary. TAKT directly calls the respective API.
- Copilot provider requires the `copilot` CLI to be installed. The GitHub token is used for authentication.
### CLI Path Overrides
@ -258,7 +258,7 @@ The model used for each movement is resolved with the following priority order (
1. **Piece movement `model`** - Specified in the movement definition in piece YAML
2. **Global config `model`** - Default model in `~/.takt/config.yaml`
3. **Provider default** - Falls back to the provider's built-in default (Claude: `sonnet`, Codex: `codex`, OpenCode: provider default, Cursor: CLI default)
3. **Provider default** - Falls back to the provider's built-in default (Claude: `sonnet`, Codex: `codex`, OpenCode: provider default, Cursor: CLI default, Copilot: CLI default)
### Provider-specific Model Notes
@ -270,7 +270,7 @@ The model used for each movement is resolved with the following priority order (
**Cursor Agent** forwards `model` directly to `cursor-agent --model <model>`. If omitted, Cursor CLI default is used.
**Copilot** forwards `model` directly to the Copilot CLI `--model <model>` flag. If omitted, Copilot CLI default is used.
**GitHub Copilot CLI** forwards `model` directly to `copilot --model <model>`. If omitted, Copilot CLI default is used.
### Example

19
docs/data-flow.md
View File

@ -288,10 +288,10 @@ TAKTのデータフローは以下の7つの主要なレイヤーで構成され
│ ▼ │
│ ┌────────────────────────────────────────┐ │
│ │ Provider.call() │ │
│ │ (ClaudeProvider / CodexProvider) │ │
│ │ (Claude / Codex / OpenCode / etc.) │ │
│ │ │ │
│ │ - Build system prompt │ │
│ │ - Call SDK (callClaude / callCodex) │ │
│ │ - Call SDK (provider-specific) │ │
│ │ - Stream handling (onStream callback) │ │
│ │ - Error propagation │ │
│ │ │ │
@ -669,7 +669,7 @@ const match = await detectMatchedRule(step, response.content, tagContent, {...})
- プロンプトファイル (`.md`)
2. **プロバイダー取得**:
- `getProvider(providerType)`: ClaudeProvider / CodexProvider / MockProvider
- `getProvider(providerType)`: Claude / Codex / OpenCode / Cursor / Copilot / Mock
3. **エージェント呼び出し**:
- `provider.call(agentName, instruction, options)`
@ -696,11 +696,14 @@ const match = await detectMatchedRule(step, response.content, tagContent, {...})
#### 7.2 Provider (`src/infra/providers/`)
**役割**: AIプロバイダー(Claude, Codex)とのSDK通信
**役割**: AIプロバイダー(Claude, Codex, OpenCode, Cursor, Copilot)とのSDK通信
**主要なプロバイダー**:
- `ClaudeProvider`: Claude Code SDK (`@anthropic-ai/claude-agent-sdk`)
- `CodexProvider`: Codex API
- `CodexProvider`: Codex SDK (`@openai/codex-sdk`)
- `OpenCodeProvider`: OpenCode SDK (`@opencode-ai/sdk`)
- `CursorProvider`: Cursor Agent CLI
- `CopilotProvider`: GitHub Copilot CLI
- `MockProvider`: テスト用
**主要メソッド**:
@ -716,7 +719,7 @@ async call(
**処理内容**:
1. システムプロンプト構築
2. SDK呼び出し (`callClaude()` / `callCodex()`)
2. SDK呼び出し（プロバイダー固有）
3. ストリーミング処理 (`onStream` callback)
4. エラーハンドリング
5. レスポンス変換
@ -1000,9 +1003,9 @@ function determineNextStepByRules(
### 7. Provider Response → AgentResponse
**場所**: `src/infra/providers/claude.ts`, `src/infra/providers/codex.ts`
**場所**: `src/infra/providers/` (各プロバイダー実装)
**入力**: SDKレスポンス (`ClaudeResult`)
**入力**: SDKレスポンス（プロバイダー固有）
**処理**:
- `status` 変換

2
docs/pieces.md
View File

@ -193,7 +193,7 @@ output_contracts:
| `edit` | - | Whether the movement can edit project files (`true`/`false`) |
| `pass_previous_response` | `true` | Pass previous movement's output to `{previous_response}` |
| `allowed_tools` | - | List of tools the agent can use (Read, Glob, Grep, Edit, Write, Bash, etc.) |
| `provider` | - | Override provider for this movement (`claude`, `codex`, or `opencode`) |
| `provider` | - | Override provider for this movement (`claude`, `codex`, `opencode`, `cursor`, or `copilot`) |
| `model` | - | Override model for this movement |
| `required_permission_mode` | - | Required minimum permission mode: `readonly`, `edit`, or `full` |
| `output_contracts` | - | Report file configuration (name, format) |

2
docs/provider-sandbox.md
View File

@ -9,6 +9,8 @@ TAKT supports configuring sandbox settings for AI agent providers. This document
| **Claude Code** | macOS Seatbelt / Linux bubblewrap | Gradle/JVM blocked in `edit` mode | `provider_options.claude.sandbox` |
| **Codex CLI** | macOS Seatbelt / Linux Landlock+seccomp | npm/maven/pytest failures (widespread) | `provider_options.codex.network_access` |
| **OpenCode CLI** | None (no native sandbox) | No constraints (no security either) | N/A |
| **Cursor Agent** | None (relies on Cursor IDE sandbox) | No known issues | N/A |
| **GitHub Copilot CLI** | None (no native sandbox) | No constraints | N/A |
## Claude Code Sandbox

2
docs/task-management.ja.md
View File

@ -263,7 +263,7 @@ takt list --non-interactive --action try --branch takt/my-branch
TAKT は `git worktree` の代わりに `git clone --shared` を使用して、独立した `.git` ディレクトリを持つ軽量クローンを作成します。これが重要な理由は次の通りです。
- **独立した `.git`**: 共有クローンは独自の `.git` ディレクトリを持ち、エージェントツール（Claude Code など）が `gitdir:` 参照をたどってメインリポジトリに戻ることを防ぎます。
- **独立した `.git`**: 共有クローンは独自の `.git` ディレクトリを持ち、エージェントツールが `gitdir:` 参照をたどってメインリポジトリに戻ることを防ぎます。
- **完全な隔離**: エージェントはクローンディレクトリ内でのみ作業し、メインリポジトリを認識しません。
> **注意**: YAML フィールド名は後方互換性のため `worktree` のままです。内部的には `git worktree` ではなく `git clone --shared` を使用しています。

2
docs/task-management.md
View File

@ -263,7 +263,7 @@ Specifying `worktree` in task configuration executes each task in an isolated cl
TAKT uses `git clone --shared` instead of `git worktree` to create lightweight clones with an independent `.git` directory. This is important because:
- **Independent `.git`**: Shared clones have their own `.git` directory, preventing agent tools (like Claude Code) from traversing `gitdir:` references back to the main repository.
- **Independent `.git`**: Shared clones have their own `.git` directory, preventing agent tools from traversing `gitdir:` references back to the main repository.
- **Full isolation**: Agents work entirely within the clone directory, unaware of the main repository.
> **Note**: The YAML field name remains `worktree` for backward compatibility. Internally, it uses `git clone --shared` instead of `git worktree`.