TaskGuild

TaskGuild は、AI エージェントによるタスク自動実行を実現するワークフローオートメーションシステムです。

Workflow にステータスを定義し、各ステータスに Agent をバインドすることで、タスクのステータス変更をトリガーとして Agent が自動的にタスクを実行します。

Architecture

┌─────────────┐       ┌──────────────────┐       ┌─────────────────┐
│   Frontend   │──────▶│  Backend Server   │◀──────│  Agent Manager  │
│ (React SPA)  │  RPC  │  (Go / Connect)  │ Stream │  (taskguild-    │
│              │       │                  │        │   agent)        │
└─────────────┘       └──────────────────┘       └────────┬────────┘
                              │                           │
                              │                    ┌──────▼──────┐
                              │                    │ Claude Agent │
                              │                    │  (SDK-based) │
                              ▼                    └─────────────┘
                       ┌──────────────┐
                       │   Storage    │
                       │ (Local/S3)   │
                       └──────────────┘

Component	Description
Backend Server	Connect RPC ベースの API サーバー。Project / Workflow / Task / Agent の管理と、Agent Manager への Task 配信を行う
Agent Manager	プロジェクトのリポジトリ内で起動する常駐プロセス。Backend から Task を受信し、Claude Agent を起動してタスクを実行する
Frontend	React + TanStack ベースの Web UI。タスク管理、Workflow 設計、Agent 定義、Interaction 対応を行う

Getting Started

1. Backend Server のセットアップ

Backend Server はグローバルにアクセス可能な場所にデプロイします（HTTPS 推奨）。VPN 環境内に配置することも可能です。

環境変数

変数名	必須	デフォルト	説明
`TASKGUILD_API_KEY`	Yes	-	API 認証キー。十分に複雑なランダム文字列を使用してください
`TASKGUILD_HTTP_HOST`	No	`""` (all interfaces)	バインドするホスト
`TASKGUILD_HTTP_PORT`	No	`3100`	リッスンポート
`TASKGUILD_ENV`	No	`local`	環境 (`local` / `production`)
`TASKGUILD_LOG_LEVEL`	No	`debug`	ログレベル (`debug` / `info` / `warn` / `error`)
`TASKGUILD_STORAGE_TYPE`	No	`local`	ストレージ種別 (`local` / `s3`)
`TASKGUILD_STORAGE_BASE_DIR`	No	`.taskguild/data`	ローカルストレージのパス
`TASKGUILD_S3_BUCKET`	No	-	S3 バケット名 (`s3` 選択時)
`TASKGUILD_S3_PREFIX`	No	`taskguild/`	S3 プレフィックス
`TASKGUILD_S3_REGION`	No	`ap-northeast-1`	S3 リージョン
`TASKGUILD_PUBLIC_URL`	No	`http://localhost:3100`	外部からアクセス可能な Backend の URL。プッシュ通知のアクションボタンからの API コールに使用
`TASKGUILD_VAPID_PUBLIC_KEY`	No	-	Web Push 用 VAPID 公開鍵（プッシュ通知を使用する場合は必須）
`TASKGUILD_VAPID_PRIVATE_KEY`	No	-	Web Push 用 VAPID 秘密鍵（プッシュ通知を使用する場合は必須）
`TASKGUILD_VAPID_CONTACT`	No	`admin@taskguild.dev`	VAPID の連絡先メールアドレス

ビルドと起動

cd backend

# ビルド
make build

# 起動
TASKGUILD_API_KEY="your-secure-random-api-key" ./bin/taskguild-server

API Key について: TASKGUILD_API_KEY はすべてのクライアント（Frontend / Agent Manager）が使用する共通の認証キーです。openssl rand -hex 32 などで十分に長いランダム文字列を生成してください。

Cloudflare Tunnel を使った公開（推奨）

Backend Server をインターネットからアクセス可能にする方法として、Cloudflare Tunnel が便利です。

# 1. cloudflared をインストール
# macOS
brew install cloudflared

# Linux
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared
chmod +x /usr/local/bin/cloudflared

# 2. Cloudflare にログイン
cloudflared tunnel login

# 3. Tunnel を作成
cloudflared tunnel create taskguild

# 4. DNS ルーティングを設定 (例: taskguild-api.example.com)
cloudflared tunnel route dns taskguild taskguild-api.example.com

# 5. config.yml を作成
cat > ~/.cloudflared/config.yml << 'EOF'
tunnel: <tunnel-id>
credentials-file: /home/<user>/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: taskguild-api.example.com
    service: http://localhost:3100
  - service: http_status:404
EOF

# 6. Tunnel を起動（Backend Server と同じマシンで実行）
cloudflared tunnel run taskguild

2. Frontend の利用

Frontend は https://taskguild.cc で公開されています。

初回アクセス時に以下を設定してください：

API Base URL: Backend Server の URL（例: https://taskguild-api.example.com）
API Key: Backend Server に設定した TASKGUILD_API_KEY

設定はブラウザの localStorage に保存されます。

3. プッシュ通知のセットアップ（オプション）

スマートフォン（Android / iOS）やデスクトップのブラウザにプッシュ通知を送信できます。Agent が Permission Request や Question を作成すると、登録済みのデバイスに自動で通知が届きます。

前提条件: HTTPS 環境が必要です。Service Worker と Push API は HTTPS（または localhost）でのみ動作します。

VAPID キーペアの生成

npx web-push generate-vapid-keys

出力される Public Key と Private Key を環境変数に設定してください。

環境変数の設定

TASKGUILD_VAPID_PUBLIC_KEY="<生成された Public Key>"
TASKGUILD_VAPID_PRIVATE_KEY="<生成された Private Key>"
TASKGUILD_PUBLIC_URL="https://taskguild-api.example.com"

4. Agent Manager のセットアップ

Agent Manager は プロジェクトのリポジトリ内で起動 します。

cd backend

# ビルド
make build-agent

# プロジェクトのリポジトリに移動
cd /path/to/your-project

# Agent Manager を起動
TASKGUILD_API_KEY="your-secure-random-api-key" \
TASKGUILD_SERVER_URL="https://taskguild-api.example.com" \
/path/to/bin/taskguild-agent

Agent Manager の環境変数

変数名	必須	デフォルト	説明
`TASKGUILD_API_KEY`	Yes	-	Backend と同じ API Key
`TASKGUILD_SERVER_URL`	No	`http://localhost:3100`	Backend Server の URL
`TASKGUILD_AGENT_MANAGER_ID`	No	自動生成 (ULID)	Agent Manager の一意な ID
`TASKGUILD_MAX_CONCURRENT_TASKS`	No	`10`	同時実行可能なタスク数
`TASKGUILD_WORK_DIR`	No	`.` (カレントディレクトリ)	タスク実行時の作業ディレクトリ
`TASKGUILD_PROJECT_NAME`	No	作業ディレクトリ名	バインド先のプロジェクト名

Agent Manager は起動すると Backend に Subscribe し、タスク配信を待ち受けます。

Core Concepts

Project

Project は TaskGuild における管理単位です。リポジトリと 1:1 で対応します。

Frontend から Project を作成する際に name を設定します。Agent Manager は起動時の作業ディレクトリ名（または TASKGUILD_PROJECT_NAME）で Project とマッチングされます。

Agent

Agent は、タスクを実行する AI エージェントの定義です。プロジェクトのリポジトリ内に .claude/agents/ ディレクトリを作成し、Markdown ファイルで定義します。Agent Manager 起動時に自動的に Backend に同期されます。

your-project/
├── .claude/
│   └── agents/
│       ├── architect.md
│       ├── software-engineer.md
│       └── senior-engineer.md
└── ...

Agent 定義ファイルのフォーマット

YAML フロントマターとプロンプト本文で構成されます。

---
name: software-engineer
description: ソフトウェアエンジニア。タスクの内容を読み実装を行う。
tools: Read, Write, Glob, Grep, Bash, WebSearch, Task
model: opus
permissionMode: acceptEdits
skills: [create-pr, investigate-logs]
memory: project
---

あなたはソフトウェアエンジニアです。タスクの内容をよく読み実装してください。

フロントマターのフィールド

フィールド	型	説明
`name`	string	Agent の識別名（ファイル名から自動設定も可能）
`description`	string	Agent の説明
`tools`	string / list	使用可能なツール（カンマ区切り or YAML リスト）
`disallowedTools`	string / list	使用禁止のツール
`model`	string	使用モデル: `sonnet` / `opus` / `haiku` / `inherit`
`permissionMode`	string	権限モード: `default` / `acceptEdits` / `dontAsk` / `bypassPermissions` / `plan` / `auto`
`skills`	list	プリロードするスキル
`memory`	string	メモリスコープ: `user` / `project` / `local`

Workflow

Workflow はタスクが辿るステータスの流れを定義します。各ステータスに Agent をバインドすることで、タスクのステータス遷移に応じた自動実行が可能になります。

Workflow: "Development Flow"
├── Draft        (is_initial: true)
│   └── transitions_to: [Plan]
├── Plan         (agent: architect, permission_mode: plan)
│   └── transitions_to: [Develop]
├── Develop      (agent: software-engineer, inherit_session_from: Plan)
│   └── transitions_to: [Review]
├── Review       (agent: senior-engineer, inherit_session_from: Develop)
│   └── transitions_to: [Develop, Closed]
└── Closed       (is_terminal: true)

Status のフィールド

フィールド	説明
`name`	ステータス名（Workflow 内で一意）
`order`	表示順序
`is_initial`	`true` の場合、タスク作成時のデフォルトステータス（1つのみ）
`is_terminal`	`true` の場合、タスクの終了状態
`transitions_to`	遷移可能な次のステータス名のリスト
`agent_id`	このステータスにバインドする Agent の ID
`permission_mode`	このステータスでの権限モード（Agent 設定より優先）
`inherit_session_from`	前ステータスのセッションを直接 resume するための設定
`hooks`	このステータスで実行するフック（スキル/スクリプト）
`enable_skill_harness`	Skill ファイルの自動更新（デフォルト有効）

Task

Task はワークフロー上で実行される作業単位です。

Task のライフサイクル

Task 作成 (Initial Status, UNASSIGNED)
    │
    ▼
[Status with Agent] ── Orchestrator が検知 → PENDING → Agent が Claim → ASSIGNED
    │
    │  Agent がタスクを実行（複数ターン）
    │    ├── Tool 使用 → 権限チェック → TaskLog に記録
    │    ├── NEXT_STATUS 出力 → ステータス遷移
    │    ├── CREATE_TASK 出力 → サブタスク作成
    │    └── TASK_DESCRIPTION 出力 → タスク説明更新
    │
    ▼
[Next Status] → 次の Agent が自動実行 ... → [Terminal Status]

Task のフィールド

フィールド	説明
`title`	タスクのタイトル
`description`	タスクの詳細説明（Agent への指示内容）
`workflow_id`	使用する Workflow の ID
`status_id`	現在のステータス
`metadata`	カスタムメタデータ（key-value）
`use_worktree`	`true` の場合、Agent が git worktree を使用して作業

Interaction

Agent がタスク実行中にユーザーの入力や承認を必要とする場合、Interaction が作成されます。

タイプ	説明
Permission Request	ツール使用の許可要求（Bash コマンド等）
Question	Agent からの質問（プラン承認等）
Notification	ステータス変更通知
User Message	ユーザーからの追加指示

Frontend の Chat 画面やタスク詳細画面でリアルタイムに確認・応答が可能です。プッシュ通知を設定すればスマートフォンからも応答できます。

Agent Directives

Agent はタスク実行中に以下のディレクティブを出力に含めることで、タスクの制御を行います。これらは Agent の出力テキストから自動的にパースされます。

NEXT_STATUS

タスクのステータスを遷移させます。出力の最終行に記述します。

NEXT_STATUS: Review

遷移可能なステータスが 1 つだけの場合、Agent が NEXT_STATUS を指定しなくても自動的に遷移します。

CREATE_TASK

サブタスクを作成します。

CREATE_TASK_START
title: サブタスクのタイトル
status: Develop
use_worktree: true
worktree: existing-worktree-name

サブタスクの説明文。
親タスクのコンテキストを引き継ぐ。
CREATE_TASK_END

サブタスクは親タスクのセッション ID を引き継ぎ、同じ会話コンテキストで実行を開始できます。

TASK_DESCRIPTION

タスクの説明を更新します。

TASK_DESCRIPTION_START
更新後のタスク説明。
Agent が作業の進捗に合わせて説明を更新する際に使用。
TASK_DESCRIPTION_END

TASK_METADATA

タスクのメタデータを更新します。

TASK_METADATA: pr_url=https://github.com/owner/repo/pull/123

Session Management

TaskGuild はステータス別のセッション ID（session_id_{StatusName}）を使用して Claude のセッションを管理します。

セッションの Resume

同一ステータス内の複数ターン: Turn 0 で作成されたセッションを Turn 1 以降で直接 resume します
ステータス遷移 (inherit): inherit_session_from が設定されている場合、前ステータスのセッションを直接 resume します（fork しません）
サブタスク: 親タスクのセッション ID を引き継ぎ、直接 resume します

セッションの Fork

以下のケースでのみセッションが fork されます：

Hook/スキル実行: after_task_execution 等のフックは、メインタスクのセッションに影響を与えないよう fork して実行されます
Agent MD ハーネス: タスク完了後の Agent 定義ファイル自動更新は fork して実行されます

セッション ID の保持

ステータス別セッション ID（session_id_Plan、session_id_Develop 等）はすべての遷移を通じて保持され、消去されることはありません。これにより、どのステータスのセッションでも後から参照・引き継ぎが可能です。

Worktree

use_worktree: true のタスクは、git worktree を使用して独立したブランチで作業します。

Worktree の動作

タスク開始時に .claude/worktrees/{name}/ ディレクトリと worktree-{name} ブランチが作成されます
Agent は worktree ディレクトリ内で作業します
タスク完了後、worktree は保持されます（手動で削除可能）

同時実行制御

同一 worktree では一度に 1 つのタスクのみ実行可能です。

ClaimTask 時にサーバーサイドで worktree の占有状態をチェックします
同じ worktree で既に ASSIGNED のタスクがある場合、新しいタスクの claim は拒否されます
タスクが完了（UNASSIGNED）すると、同じ worktree で待機中の PENDING タスクが自動的にリブロードキャストされます

これにより、同一ブランチ上での複数 Agent の同時書き込みによる git 競合を防ぎます。

Hooks

Workflow の各ステータスにフック（スキルまたはスクリプト）を設定できます。

トリガー

トリガー	タイミング	セッション
`before_task_execution`	タスク開始前	セッションなし
`after_task_execution`	タスク完了後	メインセッションを fork
`before_worktree_creation`	Worktree 作成前	セッションなし
`after_worktree_creation`	Worktree 作成後	メインセッションを fork

フックの種類

スキル: .claude/skills/{name}/SKILL.md で定義された再利用可能なプロンプト
スクリプト: シェルスクリプト（.taskguild/scripts/ に配置）

フックは順序付きで順次実行されます。個々のフックの失敗はメインタスクをブロックしません。

Skills

スキルは再利用可能なプロンプトテンプレートです。.claude/skills/{name}/SKILL.md に配置します。

---
name: create-pr
description: PR を作成または既存 PR に push する
allowedTools: [Bash, Read, Grep]
model: inherit
context: inline
userInvocable: true
argumentHint: "[branch-name]"
---

## Create PR

PR の作成手順...

スキルは以下の場面で使用されます：

Workflow のフックとして自動実行
Agent にプリロードして利用可能にする（skills フロントマター）

Skill Harness

タスク完了時に自動的に実行される Skill ファイルの更新機能です。

タスクの実行結果を分析し、関連する Skill ファイル（.claude/skills/{name}/SKILL.md）に失敗パターンや学びを追記します
コードベースの構造知識やプロセス改善の知見が蓄積され、次回以降のタスク実行効率が向上します
メインセッションを fork して独立に実行されるため、タスクの実行には影響しません

ステータスごとに enable_skill_harness で有効/無効を切り替えられます（デフォルト有効）。

Task Logs (Append-Only)

タスクの実行ログは追記型の TaskLog として時系列で記録されます。メタデータの上書きは行いません。

ログカテゴリ

カテゴリ	説明
`TURN_START` / `TURN_END`	Claude ターンの開始/終了
`TOOL_USE`	ツール使用（入力・出力を記録）
`AGENT_OUTPUT`	Agent のテキスト出力
`DIRECTIVE`	ディレクティブの検出（NEXT_STATUS, CREATE_TASK 等）
`RESULT`	タスク結果（summary / error / plan / description）
`STATUS_CHANGE`	ステータス変更
`HOOK`	フック実行
`SYSTEM`	システムイベント
`ERROR`	エラー
`STDERR`	標準エラー出力

Result ログ

タスクの結果は RESULT カテゴリの TaskLog として記録されます。result_type で種別を区別します：

summary: タスク完了時の結果サマリー
error: エラーメッセージ
plan: プラン承認後のプラン内容
description: タスク説明の更新内容

タスク詳細ページでは、これらの Result ログが時系列で表示されます。

Frontend

ページ構成

ページ	パス	説明
プロジェクト一覧	`/`	プロジェクトの選択・作成
プロジェクトボード	`/projects/:id`	タスクのカンバンボード表示
タスク詳細	`/projects/:id/tasks/:taskId`	タスクの実行ログ・Interaction・結果表示
プロジェクトチャット	`/projects/:id/chat`	プロジェクト内の Interaction と Result の時系列表示
グローバルチャット	`/global-chat`	全プロジェクトの統合タイムライン
ワークフロー	`/projects/:id/workflows`	ステータス・遷移・フック・Agent バインドの設定
Agent 管理	`/projects/:id/agents`	Agent 定義の編集・同期
スキル管理	`/projects/:id/skills`	スキルの編集・同期
スクリプト管理	`/projects/:id/scripts`	スクリプトの編集・実行
パーミッション	`/projects/:id/permissions`	ツール使用の許可ルール設定
Worktree 管理	`/projects/:id/worktrees`	Worktree の一覧・削除・git pull
テンプレート	`/templates`	タスクテンプレートの管理

リアルタイム更新

タスクの作成・更新・ステータス変更・Interaction 作成などのイベントをリアルタイムに受信し、UI を自動更新します。

Example: 開発ワークフローのセットアップ

Step 1: Agent を定義

.claude/agents/architect.md:

---
name: architect
description: システムアーキテクト。タスクの計画を立案する。
model: opus
permissionMode: plan
---

あなたはシステムアーキテクトです。タスクの要件を分析し、実装計画を立ててください。

.claude/agents/software-engineer.md:

---
name: software-engineer
description: ソフトウェアエンジニア。計画に基づいて実装する。
tools: Read, Write, Glob, Grep, Bash, WebSearch, Task
model: opus
permissionMode: acceptEdits
skills: [create-pr]
---

あなたはソフトウェアエンジニアです。計画に従って実装してください。

.claude/agents/senior-engineer.md:

---
name: senior-engineer
description: シニアエンジニア。コードレビューを行う。
tools: Read, Glob, Grep, Bash
model: opus
permissionMode: default
---

あなたはシニアエンジニアです。変更内容をレビューしてください。

Step 2: Workflow を作成

Frontend から以下の Workflow を作成します：

Status	Initial	Terminal	Transitions	Agent	Inherit Session
Draft	Yes	No	Plan	-	-
Plan	No	No	Develop	architect	-
Develop	No	No	Review	software-engineer	Plan
Review	No	No	Develop, Closed	senior-engineer	Develop
Closed	No	Yes	-	-	-

inherit_session_from により、Develop は Plan のセッションを直接 resume し、Review は Develop のセッションを直接 resume します。これにより、各 Agent は前ステータスの会話コンテキストを完全に引き継いで作業できます。

Step 3: Agent Manager を起動

cd /path/to/your-project

TASKGUILD_API_KEY="your-api-key" \
TASKGUILD_SERVER_URL="https://taskguild-api.example.com" \
taskguild-agent

Step 4: Task を作成して実行

Frontend で Task を作成（Draft ステータスで作成される）
Task のステータスを Plan に変更
architect Agent が自動的に計画を立案
完了すると Develop に自動遷移（Plan のセッションを resume）
software-engineer Agent が計画に基づいて実装
完了すると Review に自動遷移（Develop のセッションを resume）
senior-engineer Agent がコードレビューを実行
レビュー結果に応じて Develop（修正が必要）or Closed（完了）に遷移

API Authentication

すべての API リクエストには認証が必要です。以下のいずれかのヘッダーで API Key を送信します：

X-API-Key: <your-api-key>
Authorization: Bearer <your-api-key>

Storage

Backend Server はデータを YAML ファイルとして保存します。

Local Storage (デフォルト): .taskguild/data/ ディレクトリに保存
S3 Storage: Amazon S3 バケットに保存（TASKGUILD_STORAGE_TYPE=s3 で有効化）

Technology Stack

Layer	Technology
Backend	Go, Connect RPC
Agent	Go, Claude Agent SDK
Frontend	React 19, TypeScript, TanStack Router/Query, Tailwind CSS 4
Storage	YAML (local) / S3
Build	Make (backend), Vite (frontend)

License

See LICENSE for details.

Name		Name	Last commit message	Last commit date
cmd		cmd
frontend		frontend
internal		internal
pkg		pkg
proto		proto
.gitignore		.gitignore
.golangci.yml		.golangci.yml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum

Latest commit

History

Folders and files

Repository files navigation