Codens Help — agent から Codens family を完全利用するためのガイド

1. 利用経路 — 3 つの選択肢

Codens は 3 つの経路で利用できます。MCP 経由が最も簡単で、Claude Code / Cursor / Cline などの MCP 対応クライアントから自動的に全 tools が利用可能になります。

経路	対象	特徴	推奨
MCP 経由	Claude Code, Cursor, Cline ほか MCP 対応 agent	`codens-mcp` をインストールし、`~/.claude/settings.json` に登録するだけで全 30 tools が利用可能。OAuth フローで認証、credit / billing は自動連携。	推奨
REST API 直叩き	独自 agent / CI ジョブ / バックエンド統合	`https://api.purple.codens.ai` ほか各サービスの OpenAPI を直接呼ぶ。Bearer token は Auth Codens 経由で取得。Idempotency-Key ヘッダ対応。	—
Stripe Projects auto-signup	将来：未契約状態の agent / 個人ユーザー	Stripe Customer Portal から従量課金で onboard。最初の credit grant が自動付与され、即座に Codens を利用開始できる予定。	将来提供

2. Quick Start (MCP 経由)

3 ステップで Codens の全 tools が agent から呼べる状態になります。

Step 1. インストール

pip install codens-mcp

Step 2. `~/.claude/settings.json` に登録

{
  "mcpServers": {
    "codens": {
      "command": "codens-mcp",
      "args": ["serve"],
      "env": {
        "CODENS_AUTH_URL": "https://auth.codens.ai"
      }
    }
  }
}

Cursor / Cline でも同じ MCP サーバ設定が利用できます。各クライアントの設定ファイル形式に合わせてください。

Step 3. 初回認証 — `purple_login` tool

agent から以下を呼ぶと、ブラウザが起動して OAuth フローが始まります。完了後、token は OS の secure store に保存され、以降の tool 呼び出しは自動認証されます。

// agent からの呼び出し例
await tools.purple_login({});

// 戻り値
{
  "ok": true,
  "user_id": "u_01H...",
  "organization_id": "org_01H...",
  "credits_remaining_jpy": 5000
}

これで完了です

以降、Purple / Red / Blue / Green / Auth の全 tool が agent から呼び出せます。次の「4 ユースケース」で実例を確認してください。

3. 4 つの実用ユースケース

代表的なシナリオを 4 つ紹介します。各ユースケースは agent との会話例 + 実際に呼ばれる tool の流れで示します。

A. 開発タスクを Codens に投げて自動実装 — Purple Codens

手元のリポジトリで実装タスクを切り出し、Purple Codens の VPS 上で Claude Code が自動実装 → PR 作成までを行います。複数タスクの並行実行も可能です。

User: 「auth-codens の login API に rate limiting を追加して、PR を出してほしい」

Agent: → purple_workflow_create({
    repo: "Corevice/auth-codens",
    title: "Add rate limiting to login API",
    description: "Apply 10 req/min per IP using Redis-backed limiter. Add tests.",
    base_branch: "develop"
  })
  → purple_workflow_status({ workflow_id }) で進捗確認
  → 完了通知後、PR URL を user に共有

B. バグ報告 → 自動修正 PR — Red → Purple chain

Sentry / 手動報告から検知したエラーを Red Codens で解析し、修正 PR を Purple Codens で生成します。Red 単独でも PR は作れますが、複雑な fix は Purple chain が高品質です。

User: 「Sentry の issue ABC-123 を直して」

Agent: → red_analyze_error({ sentry_issue_id: "ABC-123" })
  → 戻り値の suggested_fix を確認
  → red_generate_fix_pr({
       sentry_issue_id: "ABC-123",
       use_purple_chain: true   // 高品質モード
     })
  → PR URL: https://github.com/Corevice/.../pull/512

C. E2E テストを AI で自動生成 + 実行 — Blue Codens

PRD や issue から E2E テストシナリオを自動生成し、CI と連動して実行します。失敗時はトレースを Red Codens に渡して自動修正も可能です。

User: 「green-codens の checkout flow に E2E テストを追加して」

Agent: → blue_generate_e2e_tests({
    repo: "Corevice/green-codens",
    feature: "checkout-flow",
    framework: "playwright"
  })
  → blue_run_e2e({ test_suite_id })
  → 戻り値: { passed: 12, failed: 0, video_url, trace_url }

D. 相談 → PRD 化 → 実装まで — Green → Purple

曖昧な要望を Green Codens が構造化 PRD に整形し、そのまま Purple Codens に渡して実装まで自動化します。Notion 同期もデフォルトで有効です。

User: 「課金画面に年額プランの選択肢を増やしたい。要件整理から実装まで頼む」

Agent: → green_prd_create({
    title: "年額プラン選択 UI",
    raw_input: "課金画面に年額プランの選択肢を増やしたい..."
  })
  → green_prd_finalize({ prd_id })  // AI が要件を構造化
  → purple_workflow_create({
       repo: "Corevice/billing-control-plane",
       prd_id,
       base_branch: "develop"
     })
  → 完了後、PR URL を user に共有

4. 全 30 tools 一覧

Codens family が提供する全 30 tools です。MCP server を有効化すれば、すべて agent から直接呼び出せます。

Purple Codens (16 tools) — AI 開発オーケストレーション

Tool	説明
`purple_login`	OAuth フローで Codens にログイン。token を secure store に保存。
`purple_logout`	保存した token を破棄。
`purple_whoami`	現在の user / organization / 残 credit を返す。
`purple_workflow_create`	新規 workflow（タスク）を作成し VPS 上で実行開始。
`purple_workflow_status`	workflow の現在 step / progress / 残時間を取得。
`purple_workflow_list`	org の workflow 一覧を取得。filter: status / repo / created_at。
`purple_workflow_logs`	指定 workflow の実行ログを stream / batch で取得。
`purple_workflow_cancel`	実行中の workflow を中断。
`purple_workflow_retry`	失敗 step から再実行。原因 PR 修正後の再キックに使用。
`purple_task_create`	workflow 内の単一 task を直接作成（手動分割用）。
`purple_task_attach_file`	task に追加コンテキスト（PRD / 仕様書）を添付。
`purple_repo_register`	新規 repo を Codens project に登録。useWorktree 設定も指定可。
`purple_repo_list`	登録済み repo 一覧を返す。
`purple_credit_balance`	credit 残高 / 直近 7 日の消費量 / next reset を返す。
`purple_credit_grant`	(admin) 任意 org に credit を付与。
`purple_billing_portal_url`	Stripe Customer Portal の signed URL を返す。

Red Codens (4 tools) — エラー検知 → 自動修正 PR

Tool	説明
`red_analyze_error`	Sentry issue / stack trace を解析し、原因と修正方針を返す。
`red_generate_fix_pr`	修正 PR を自動生成。`use_purple_chain` で高品質モード。
`red_list_recent_fixes`	直近の自動修正 PR 一覧と各 PR の merge 状態を返す。
`red_run_3retry_loop`	テスト結果を feedback ループに渡しながら最大 3 回まで修正試行。

Blue Codens (4 tools) — QA 自動化

Tool	説明
`blue_generate_unit_tests`	指定 module / function に対して unit test を自動生成。
`blue_generate_e2e_tests`	機能 / PRD から E2E テスト scenario を自動生成（Playwright / Cypress）。
`blue_run_e2e`	E2E テスト suite を実行し、video / trace / network log を返す。
`blue_analyze_failure`	失敗トレースから根本原因を解析し、Red Codens にチェイン可能な report を返す。

Green Codens (4 tools) — PRD 作成 / 管理

Tool	説明
`green_prd_create`	raw input から PRD draft を作成（Claude が構造化）。
`green_prd_finalize`	draft を確定。Notion / GitHub Issue に同期。
`green_prd_list`	PRD 一覧（status / owner / 関連 repo で filter 可）。
`green_prd_link_workflow`	PRD と Purple workflow を紐付け、進捗を双方向同期。

Auth Codens (2 tools) — 認証 / 組織管理

Tool	説明
`auth_token_refresh`	access token を refresh。期限切れ前の自動更新に使用。
`auth_org_switch`	複数 org に所属する user の active org を切り替え。

合計：Purple 16 + Red 4 + Blue 4 + Green 4 + Auth 2 = 30 tools

5. Error envelope 仕様

すべての REST / MCP エンドポイントは、エラー時に共通の envelope を返します。error_code は agent が自動 retry / fallback を判定するための機械可読 enum です。

共通エラー形式

{
  "ok": false,
  "error_code": "RATE_LIMITED",
  "message": "Rate limit exceeded for org_01H... (30 req/min)",
  "details": { "retry_after_seconds": 12, "limit": 30 },
  "trace_id": "trc_01H...",
  "retryable": true
}

9 つの `error_code` enum と retry semantics

error_code	意味	retry semantics
`RATE_LIMITED`	rate limit 超過。`details.retry_after_seconds` を respect。	retryable: true（指数バックオフ）
`BUDGET_EXCEEDED`	org の月次 budget 上限到達。`purple_billing_portal_url` で増額。	retryable: false
`CREDIT_INSUFFICIENT`	credit 残高不足。`purple_credit_balance` で確認。	retryable: false
`WORKFLOW_NOT_FOUND`	指定 workflow_id が存在しない / 別 org の所有。	retryable: false
`UNAUTHORIZED`	token 無効 / 期限切れ。`auth_token_refresh` 後に再試行。	retryable: true（refresh 後）
`IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD`	同じ Idempotency-Key が異なる payload で再送された。	retryable: false
`INTERNAL_ERROR`	サーバ側の予期せぬエラー。trace_id を含めて support に連絡。	retryable: true（短い backoff）
`VALIDATION_ERROR`	request body / query parameter のバリデーション失敗。	retryable: false
`RESOURCE_NOT_FOUND`	repo / PRD / task など対象リソースが存在しない。	retryable: false

Idempotency-Key の運用

workflow / PR 作成系の write エンドポイントは Idempotency-Key ヘッダ必須です。同じキー + 同じ payload なら同じ結果を返し、payload が異なる場合は IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD でエラーになります。

6. Pricing

Codens は credit 制（前払い）と従量課金のハイブリッドです。詳細な料金は Pricing ページを参照してください。agent が機械可読で取得する場合は以下の endpoint を使用します。

機械可読 Pricing endpoint

GET https://api.purple.codens.ai/v1/public/pricing
Accept: application/json

// 戻り値
{
  "currency": "JPY",
  "plans": [
    { "id": "starter",      "monthly_credit_jpy":   3000, "price_jpy":   3000 },
    { "id": "pro",          "monthly_credit_jpy":  30000, "price_jpy":  25000 },
    { "id": "team",         "monthly_credit_jpy": 150000, "price_jpy": 120000 }
  ],
  "metering": [
    { "tool_prefix": "purple_workflow_*", "unit": "minute_compute", "price_jpy": 5 },
    { "tool_prefix": "red_*",             "unit": "fix_attempt",    "price_jpy": 30 },
    { "tool_prefix": "blue_*",            "unit": "test_run",       "price_jpy": 10 },
    { "tool_prefix": "green_*",           "unit": "prd_finalize",   "price_jpy": 20 }
  ],
  "default_grant_on_signup_jpy": 1000
}

新規 organization には初回サインアップ時に 1,000 JPY 分の credit が自動付与されます。Stripe Projects auto-signup 経由では別途 onboarding bonus が付与される予定です。

7. トラブルシューティング

よくある症状と確認ポイントです。解決しない場合は Contact から trace_id 付きで連絡してください。

症状	確認ポイント
MCP tools が agent から見えない	`~/.claude/settings.json` の `mcpServers.codens.command` が実際にインストールされた `codens-mcp` の絶対パスになっているか確認。`which codens-mcp` の結果を貼ってください。
`UNAUTHORIZED` が連発する	token が期限切れ。`purple_login` を再実行するか、`auth_token_refresh` を agent flow に組み込んでください。
workflow が「pending」のまま動かない	VPS pool が満杯の可能性。`purple_workflow_status` の `queue_position` を確認。15 分以上動かない場合は trace_id を添えて連絡。
credit が想定より早く消費される	`purple_credit_balance` の `recent_consumption` を確認。`tool_breakdown` で消費の多い tool を特定し、必要に応じて `purple_workflow_cancel` で抑制。
PR が作成されたがテストが落ちている	`red_run_3retry_loop` で test feedback を渡しながら 3 回まで自動修正可。それでも落ちる場合は `blue_analyze_failure` で根本原因を解析。
Notion 同期が反映されない (Green)	org の Notion integration が有効か `green_prd_list` の `sync_status` を確認。`integration_disabled` の場合は admin 権限で Auth Codens の連携設定を見直し。

8. リファレンス

より深い情報は以下のリンクから。

PyPI: codens-mcp — 統合 MCP server (全 30 tools、Red / Blue / Green / Auth + Purple)
PyPI: purple-codens-mcp — Purple Codens 専用 MCP (codens-mcp の依存、単体利用可)
料金プラン — 全 5 ティア (1 credit = ¥0.01)
Pricing JSON (機械可読) — agent から直接取得可能 (initial credit grant / 各 tier の単価)
OIDC Discovery — Codens family の認証 metadata
Codens Dashboard — 既存ユーザー向け管理画面 (organization / project / billing 設定)
お問い合わせ — 機能追加リクエスト・バグ報告・契約相談