# Codens — Agent Reference (full)

This is a single-file plain-text dump of every page on
https://help.codens.ai/ for direct ingestion into LLM context windows.
Updated 2026-05-23.

The live help portal is split across the following pages:
- /                           (top portal)
- /getting-started.html       (signup / org / first project)
- /setup-mcp.html             (codens-mcp install + Device Code Flow)
- /purple.html                (Purple Codens setup)
- /red.html                   (Red Codens setup)
- /blue.html                  (Blue Codens setup)
- /green.html                 (Green Codens setup)
- /auth.html                  (Auth Codens overview)
- /usecases.html              (4 representative use cases)
- /tools.html                 (all 38 tools)
- /errors.html                (error envelope)
- /pricing.html               (pricing tiers)
- /troubleshooting.html       (common issues)

The text below covers the same material in flat form.

## What is Codens?

Codens is a suite of five integrated AI-native products that automate
the entire software development lifecycle:

- Purple Codens: AI development orchestration. A deterministic workflow
  engine that runs Claude Code on Codens-managed Fargate / VPS workers,
  supports parallel execution, and provides real-time monitoring.
- Red Codens: AI-driven automatic code repair. Detects errors via
  Sentry / webhook, analyzes them, and generates fix plans handed to
  Purple for the actual PR.
- Blue Codens: AI-driven QA automation. Generates Playwright E2E tests
  from natural-language requirements, executes them, and surfaces
  failure traces.
- Green Codens: AI-powered PRD / Plan / Kickoff platform. Bridges
  business requirements and engineering through consultations,
  structured PRDs, kickoff wizards, and a one-click handoff to Purple
  for implementation. Notion link / unlink is supported.
- Yellow Codens: AI-powered engineering activity ledger. Aggregates
  GitHub / Notion activities, computes evaluation signals, dashboards.

All products share a unified Auth Codens (OAuth2 / OIDC). Pricing is
credit-based (1 credit = ¥0.01) with five monthly tiers from a free
trial through Enterprise. New organizations receive an initial credit
grant (current default exposed in the pricing JSON).

## Access paths

There are two ways to use Codens from an AI agent:

1. MCP — recommended. `pip install codens-mcp`, register in your
   agent's MCP config, and all 38 tools become available. Works with
   Claude Code, Cursor, Cline, and any other MCP client.

2. REST API — for custom integrations and environments without MCP
   support. Endpoints under api.{red,blue,green,purple,auth}.codens.ai.
   Same auth and error envelope as MCP.

## Quick Start (MCP)

Three steps to get every Codens tool callable from your agent.

### Step 1. Install

    pip install codens-mcp

### Step 2. Register in `~/.claude/settings.json`

    {
      "mcpServers": {
        "codens": {
          "command": "codens-mcp",
          "args": []
        }
      }
    }

Running `codens-mcp` with no arguments starts the MCP server (the
default `serve` subcommand). The same configuration works for Cursor
and Cline — adjust the file location and JSON shape for each client.

### Step 3. First-time authentication (CLI recommended)

Authentication uses Device Code Flow (RFC 8628). Because MCP runs over
stdio transport it can't open a browser redirect — Device Code Flow
lets remote, SSH, and headless environments authenticate using the
same procedure.

The most reliable path is to run the CLI from a terminal:

    $ codens-mcp login

    ============================================================
      Device Authorization Required
    ============================================================

      1. Open this URL on any device:
         https://auth.codens.ai/device

      2. Enter this code when prompted:
         ABCD-1234

      Waiting for authorization (expires in 15 minutes)...
    ============================================================

    ✓ Authorized as you@example.com
      Token saved to ~/.purple-codens/credentials.json (mode 0600)

Steps (complete within 15 minutes):

1. Open https://auth.codens.ai/device in any browser.
2. Paste the `user_code` (e.g. ABCD-1234) into the input field and
   click "Authorize".
3. Sign in to Codens if prompted, then approve the access request.
4. The CLI polls automatically; on success it stores the token at
   `~/.purple-codens/credentials.json` (mode 0600). The same token
   works across Red / Blue / Green / Purple / Auth.
5. Verify with `codens-mcp whoami`.

For non-default environments use `--auth-url` and `--api-url`, e.g.
`codens-mcp login --auth-url https://api.dev.auth.codens.ai --api-url
https://api.dev.purple.codens.ai`.

If you see `expired_token`: the user_code is valid for ~15 minutes.
Rerun `codens-mcp login` to get a fresh code, and authorize promptly.
If this keeps expiring, open https://auth.codens.ai/device in your
browser BEFORE running the CLI, then paste the code as soon as it
appears.

If a terminal isn't available, you can call `purple_auth` from the
agent:

    purple_auth({
      action: "login",
      use_device_code: true,
      auth_service_url: "https://api.auth.codens.ai"
    })

This is sometimes unreliable because the MCP server's polling and
stdio buffering can interact badly and the call may appear to hang.
Prefer the CLI whenever you have access to a terminal.

## Use cases

### A. Throw a development task to Codens for auto-implementation (Purple)

User: "Add rate limiting to the auth-codens login API and open a PR."

Agent flow (organization_id is auto-resolved from credentials):

    purple_project({ action: "list_projects" })
    purple_workflow({
      action: "create_workflow",
      project_id: "...",
      name: "Add rate limiting to login API",
      spec: {
        repository: "Corevice/auth-codens",
        base_branch: "develop",
        description: "Apply 10 req/min per IP using Redis-backed limiter. Add tests."
      }
    })
    → purple_workflow({ action: "get_run_status", run_id: "..." })
       // status: pending → running → succeeded / failed
    → on completion, share the PR URL

Multiple workflow runs execute in parallel on separate workers.

### B. Bug report to fix PR (Red → Purple)

User: "Fix the auth-codens error I just hit."

Agent flow:

    red_bug_report({
      action: "create",
      project_id: "...",
      title: "Login endpoint returns 500 on empty password",
      description: "...",
      severity: "high",
      auto_analyze: true
    })
    red_bug_fix_plan({ action: "generate", bug_id: "..." })
    red_bug_fix_plan({ action: "submit_to_purple", plan_id: "..." })
    → PR URL: https://github.com/Corevice/.../pull/512

Red can produce a fix proposal on its own (`red_fix_proposal`); the
Purple chain produces higher-quality fixes for non-trivial bugs.

### C. AI-generated E2E tests (Blue)

User: "Add E2E tests for the green-codens checkout flow."

Agent flow:

    blue_e2e_test({
      action: "generate",
      project_id: "...",
      requirement: "Verify that a user can complete a checkout flow with an annual plan.",
      language: "playwright"
    })
    blue_e2e_test({ action: "run", e2e_test_id: "..." })
    blue_e2e_test({ action: "get_results", e2e_test_id: "..." })
    → { run_status, passed, failed, video_url, trace_url, ... }

Failure traces can be routed back through Red Codens by filing a bug
report and submitting a fix plan to Purple.

### D. Idea to PRD to PR (Green → Purple)

User: "Add an annual plan option to the billing page. Take this from
requirements all the way to implementation."

Agent flow:

    green_consultation({
      action: "create_with_message",
      project_id: "...",
      title: "Annual plan selector UI",
      content: "Add an annual plan option to the billing page..."
    })
    green_consultation({
      action: "convert_to_prd",
      consultation_id: "...",
      template_id: "..."
    })
    green_plan({ action: "generate_from_prd", prd_id: "..." })
    green_plan({ action: "submit_to_purple", plan_id: "..." })
    → on completion, share the PR URL

Notion is supported via `green_notion({ action: "link"|"unlink"|"status" })`.

## Tools (38 total, action-dispatch)

The 2026-05-18 refactor (PR #1065) collapsed 181 fine-grained tools
into 38 action-dispatch tools. Every tool takes an
`action: Literal[...]` parameter that selects the actual operation.
`organization_id` is auto-resolved from your credentials in
codens-mcp v0.7.5+, so single-org callers can omit it.

### Purple (7)
- `purple_auth` — actions: login, whoami.
- `purple_project` — actions: analyze_repo, list_projects, init_project.
- `purple_repository` — actions: add, list.
- `purple_instruction` — actions: import, list, sync.
- `purple_workflow` — actions: create_workflow, get_run_status,
  list_runs, cancel_run, inject_message.
- `purple_sse` — actions: subscribe_run_events.
- `purple_log` — actions: get_run_logs, get_task_log_url. Returns S3
  presigned URLs valid for 1 hour.

### Red (4)
- `red_bug_report` — actions: create, create_full, list, get, update,
  analyze, retry_analyze. `auto_analyze=true` runs analysis at
  creation time.
- `red_bug_fix_plan` — actions: generate, get, get_by_bug,
  submit_to_purple, resubmit.
- `red_fix_proposal` — actions: create, list, get, get_by_error.
- `red_external_task` — actions: list, get, execute.

### Blue (1)
- `blue_e2e_test` — actions: list, generate, run, get_results. Returns
  run_status, passed/failed, video_url, trace_url, etc.

### Green (24)
- `green_consultation` — actions: create, create_with_message, list,
  get, update, delete, send_message, attach_repo, close, reopen,
  convert_to_prd, convert_to_kickoff, convert_to_bug_report, list_my.
- `green_prd` — actions: create, list, get, update, delete,
  update_section, approve, submit_for_review, request_changes,
  archive, unarchive, link_notion, unlink_notion, check_consistency.
- `green_prd_ai` — actions: generate, generate_sync, regenerate,
  regenerate_section, get_status.
- `green_prd_translate` — translation support.
- `green_prd_template` — actions: list_org, create, create_default,
  list, get, update, set_default, reorder_sections, delete.
- `green_prd_comment` — actions: create, list, get, list_replies,
  update, resolve, unresolve, delete, get_translation.
- `green_prd_review` — actions: create, list, get, respond, cancel,
  list_my, list_my_requested.
- `green_prd_attachment` — actions: get_upload_url, confirm_upload,
  direct_upload, list, get, update, delete.
- `green_plan` — actions: create, list, list_by_project, get, update,
  create_version, generate_from_prd, submit_to_purple.
- `green_plan_task` — task management under a plan.
- `green_plan_monitoring` — actions: trigger, stop, update_settings,
  list_snapshots.
- `green_task` — general-purpose task management.
- `green_project` — actions: create, list, get, update, delete,
  get_tasks_db_id, update_tasks_db_id, setup_tasks_db_columns.
- `green_repository` — Green project ↔ GitHub repo linking.
- `green_organization` — actions: list, get, list_members,
  update_member, remove_member, list_invitations.
- `green_knowledge` — org knowledge management.
- `green_notion` — actions: link, unlink, status.
- `green_kickoff` — Kickoff CRUD.
- `green_kickoff_wizard` — actions: start_vision, start_scope,
  start_tech, start_milestones, update_step, regenerate_step.
- `green_kickoff_generate` — actions: generate_prds, generate_ui,
  generate_prototype.
- `green_kickoff_refine` — actions: refine_prototype, refine_mockup.
- `green_kickoff_prototype` — actions: get, refresh_url, list_versions.
- `green_kickoff_preview` — actions: list, get, regenerate.
- `green_kickoff_mockup` — actions: list_versions.

### Auth (1)
- `auth_agent` — actions: signup (capability_token via existing API
  key), get_pricing (machine-readable pricing.json).

### Cross-product (1)
- `codens_register_project_unified` — Register the same GitHub repo as
  a project across Purple / Red / Blue / Green in one call (best-effort,
  returns per-product IDs and any errors).

## Error envelope

Every REST and MCP endpoint returns a uniform JSON error envelope on
failure:

    HTTP/1.1 429 Too Many Requests
    Retry-After: 12
    Content-Type: application/json

    {
      "detail": "Rate limit exceeded",
      "error_code": "RATE_LIMITED",
      "category": "transient",
      "retry_after_seconds": 12,
      "suggested_action": "exponential_backoff"
    }

- `error_code` is a stable machine-readable enum used by agents to
  decide whether to retry or fall back.
- `category` is one of `permanent`, `transient`, `unauthorized`,
  `budget_exceeded`.
- `suggested_action` is an agent hint: `refresh_token`,
  `top_up_credit`, `exponential_backoff`, `fix_request_payload`.
- Respect the `Retry-After` header / `retry_after_seconds` value when
  set.

Main error codes:

- `VALIDATION_ERROR` (400 / 422) — `detail` identifies offending
  fields. Not retryable; fix the request.
- `UNAUTHORIZED` (401 / 403) — token invalid / expired or missing
  scope. Run `codens-mcp login` again.
- `CREDIT_INSUFFICIENT` (402) — top up via the pricing page or Auth
  Codens dashboard.
- `RESOURCE_NOT_FOUND` (404) — repo / PRD / task / run does not exist
  or belongs to another org.
- `RATE_LIMITED` (429) — back off; respect `retry_after_seconds`.
- `INTERNAL_ERROR` (500 / 503) — server-side issue. Retry with short
  backoff; contact support with `detail`.
- `IDEMPOTENCY_CONFLICT` (409) — same Idempotency-Key sent with a
  different payload.
- `JWT_EXPIRED` / `JWT_INVALID` / `JWT_REPLAYED` (401) — refresh
  service-to-service JWT.
- `ORG_NOT_LINKED_TO_AUTH` / `ORG_NOT_FOUND` (403 / 404) — wrong
  organization_id for the target service. Omit `organization_id` to
  let codens-mcp auto-resolve.
- `SERVICE_DISABLED` (403) — the service is disabled for that
  organization.

Cross-service caveat: Red, Blue, Green, and Purple each maintain their
own `organization_id`. Reusing an ID across services returns
`UNAUTHORIZED` / `ORG_NOT_FOUND`. codens-mcp v0.7.5+ auto-resolves the
correct ID from each service's `/api/v1/auth/me` when
`organization_id` is omitted — that's the recommended pattern.

## Pricing

Currency: credit (CCU), 1 credit = ¥0.01. Each input token costs 1.5
credits and each output token costs 7.5 credits, with a model factor
(Haiku 0.2x / Sonnet 1.0x / Opus 5.0x). A typical AI auto-fix consumes
80,000–125,000 credits (Sonnet baseline, 3-retry average).

Monthly plans (5 tiers):

- Free Trial — Free. 30,000 credits valid 14 days. No credit card.
- Hobby — ¥3,000 / mo. 300,000 credits (≈ 3–4 AI auto-fixes).
- Pro — ¥10,000 / mo. 1,000,000 credits (≈ 12–13 AI auto-fixes).
- Business — ¥50,000 / mo. 5,000,000 credits (≈ 60–70 AI auto-fixes).
- Enterprise — Custom. Unlimited credits, optional on-prem inference.

Machine-readable spec at
https://api.auth.codens.ai/.well-known/pricing.json (proxied from BCP,
5-minute cache, static fallback on BCP outage):

    {
      "version": "1",
      "currency": "CCU",
      "initial_credit_grant": 1000,
      "tiers": [
        {
          "name": "default",
          "credit_per_workflow_run": 10,
          "credit_per_mcp_call": 1,
          "monthly_quota": null
        }
      ],
      "rate_cards_url": "https://bcp.codens.ai/api/v1/rate_cards"
    }

Agents can also fetch this with `auth_agent({ action: "get_pricing" })`.

If marketing copy and the JSON disagree, the JSON is canonical (BCP
can update pricing at any time).

## Troubleshooting

- `expired_token`: user_code is valid 15 minutes. Rerun
  `codens-mcp login`; open https://auth.codens.ai/device in the
  browser first if you keep missing the window.
- `UNAUTHORIZED`: token expired. Run `codens-mcp whoami` to confirm,
  then `codens-mcp login` to re-authenticate. Credentials live at
  `~/.purple-codens/credentials.json`.
- Cross-service `UNAUTHORIZED` / `ORG_NOT_FOUND`: omit
  `organization_id` and let codens-mcp v0.7.5+ resolve it per service.
- Workflow run stuck in "pending": Fargate / VPS pool is saturated.
  Check the `status` field in
  `purple_workflow({ action: "get_run_status", run_id })`. If unchanged
  for 15+ minutes, contact support with the `run_id`.
- PR opened but tests failing: Purple's fix_verify loop retries
  automatically (a few times). If still failing, open a fresh chain
  via `red_bug_report({ action: "create" })` →
  `red_bug_fix_plan({ action: "submit_to_purple" })`.
- Notion sync not reflecting (Green): check link status with
  `green_notion({ action: "status" })`. If unlinked, use the URL from
  `green_notion({ action: "link" })` to run OAuth (admin only).
- MCP tools not visible to the agent: check that
  `~/.claude/settings.json` `mcpServers.codens.command` is the
  absolute path to your installed `codens-mcp`. Run `which codens-mcp`
  and paste that path.

## References

- PyPI codens-mcp: https://pypi.org/project/codens-mcp/ — unified MCP
  server (all 38 tools). v0.6.0 absorbed the standalone
  purple-codens-mcp package.
- Pricing JSON: https://api.auth.codens.ai/.well-known/pricing.json
- OIDC discovery:
  https://api.auth.codens.ai/.well-known/openid-configuration
- Auth Codens (account / org / OAuth client management):
  https://auth.codens.ai
- Per-product dashboards: https://app.red.codens.ai,
  https://app.blue.codens.ai, https://app.green.codens.ai,
  https://app.yellow.codens.ai
- Pricing page (humans): https://www.codens.ai/pricing.html
- Contact: https://www.codens.ai/contact.html