# 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-07-16.

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)
- /orange.html                (Orange 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.
- Orange Codens: AI-powered code review & security audit. Auto-reviews
  GitHub PRs (LLM code review + LLM SAST + secret scan + dependency
  vulnerability scan) and hands findings off to Purple / Red for
  automated fix PRs, merge-gated. Get started by installing the "Orange
  Codens" GitHub App
  (https://github.com/apps/orange-codens/installations/new) on the
  target repository. See /orange.html for the setup guide and
  www.orange.codens.ai for the product site.

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" })`.

## Orange Codens setup

Orange Codens is an automated code review and security audit agent for
GitHub Pull Requests. It can be started just by installing the GitHub
App: sign up for a Codens account, install the "Orange Codens" GitHub
App (https://github.com/apps/orange-codens/installations/new) on the
target repository, and reviews start running automatically the next
time a PR is opened. Unlike Purple/Red/Blue/Green, Orange is not part of
the codens-mcp action-dispatch tool catalog — it is set up entirely
through its own dashboard (app.orange.codens.ai) and a dedicated GitHub
App, not via MCP tool calls.

### Overview

On every PR open / synchronize webhook event, Orange creates a
`review_run` and runs two tracks in parallel: a Code Review module
(Claude reviews the diff for bugs, design, naming/readability,
performance, and missing tests) and a Security module (see below).
Results are posted as one PR summary comment plus a small number of
high-severity inline comments. Findings can be handed off to Purple /
Red to produce an actual fix PR, subject to the org's handoff policy.

### Prerequisites

1. A Codens account and organization (auth.codens.ai).
2. Admin / write access on the target GitHub repository.
3. The Orange-specific GitHub App ("Orange Codens") installed — from
   https://github.com/apps/orange-codens/installations/new (permissions:
   Pull requests read & write, Checks write, Contents read, Metadata
   read).

### Project creation → repository connection

1. Log in to app.orange.codens.ai via auth.codens.ai.
2. "New Project" → select the GitHub repository to review.
3. Install / authorize the GitHub App if prompted.
4. Reviews then trigger automatically on PR open / synchronize — no
   further setup required.
5. Optionally configure the org/repo Handoff Policy and Rule Set.

A review can also be triggered manually without a new commit:

    POST /api/v1/review-runs
    { "pr_url": "https://github.com/Corevice/your-repo/pull/123", "organization_id": "..." }

### How to read a review

- **Summary comment**: always exactly one per PR; low-confidence
  (<0.6) findings are folded into it.
- **Inline comments**: only severity ≥ `high` AND confidence ≥ 0.7,
  capped at 5 per PR.
- **Severity**: `blocker` / `critical` / `high` / `medium` / `low` /
  `info`.
- **Confidence**: 0.0-1.0, self-rated by the LLM; findings whose quoted
  evidence isn't actually present in the diff are dropped.
- **Suggested fix**: shown as a GitHub suggestion block for 1-click
  apply before merge.
- **Verify pass**: if a handed-off finding is fixed by Purple and tests
  pass, the rule_id's confidence stats go up (true positive); if Purple
  can't fix it, they go down (hallucination candidate). This closes a
  feedback loop that pure review bots (CodeRabbit, Greptile) can't
  replicate because they have no fix-execution system of their own.

### Security review

Three sub-modules run in parallel:
- `sec.sast.*` — LLM SAST: Claude reviews the diff for OWASP Top 10 /
  CWE Top 25 issues, crypto misuse, and authorization gaps. This is the
  only credit-billed sub-module.
- `sec.secret.*` — secret scanning (e.g. leaked API keys).
- `sec.dep.*` — dependency vulnerability scanning across
  package.json / requirements.txt / Cargo.toml / go.sum, etc.

Dedup fingerprint: `rule_id + file_path + start_line` within a review
run; a finding still open across commits is updated in place rather
than duplicated. `rule_set.disabled_rules` fully suppresses a rule_id.

### Finding handoff (merge-gated)

Default handoff target by `category`: `security` → Red; `code_quality`
/ `performance` / `maintainability` → Purple. `HandoffPolicy.mode` has
four levels: `off` (PR comments only — default for Free/Starter),
`manual_only` (fires on a UI "request fix" click), `threshold_auto`
(auto-files when severity ≥ threshold and category matches — default
for Pro+: severity ≥ high, category=security, target=Red), and
`full_auto` (auto-files everything, not recommended as a starting
point). Code-quality findings are opt-in on every tier.

Handoff only fires once the PR is **merged** (merge-gated) — firing on
an unmerged PR would target code that doesn't exist on main/develop
yet. A `manual_only` request made before merge is queued and discarded
if the PR closes without merging. To prevent handoff loops, PRs
authored by a Codens bot (Purple/Red's GitHub App user) are reviewed
but excluded from auto-handoff, and review runs triggered as a Purple
verify pass never trigger handoff.

### Billing

Same credit model as the rest of Codens (1 credit = ¥0.01), shared from
the same organization credit pool as Red/Blue/Green/Purple. Billing is
**post-deduct** (charged after the review completes, not reserved
upfront). Insufficient credit never fails silently — a PR comment
states the review was skipped for insufficient credit. Based on our own
billing ledger (2026-07-08 to 2026-07-27, n=1,225), the median PR review
costs **approximately 79 credits (~¥0.8)**; even the 90th percentile is
only ~260 credits (~¥2.6). See the Pricing page for current plan
details.

### Troubleshooting

- No review runs on PR open: check the GitHub App is installed with
  the required permissions, and that the repo is linked as a project.
- Review ran but no PR comment: likely insufficient credit; check the
  Auth Codens dashboard balance. Orange always posts a "skipped" comment
  rather than failing silently.
- Only a summary, no/few inline comments: by design (severity ≥ high
  and confidence ≥ 0.7 only, capped at 5).
- A fixed finding reappears: dedup fingerprint (rule_id + file_path +
  start_line) doesn't survive a shifted start_line after an edit — a
  known limitation.
- No fix PR appears: check the Handoff Policy (Free/Starter defaults to
  off), and remember handoff only fires after the original PR merges.
- Getting started with Orange: sign up for a Codens account
  (auth.codens.ai) → install the "Orange Codens" GitHub App
  (https://github.com/apps/orange-codens/installations/new) → assign the
  target repository to a project/group → opening a PR triggers a review
  automatically.

## 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 0.0225
credits and each output token costs 0.1125 credits (rate card effective
July 2026), with a per-model multiplier (default in-house Qwen 0.1x,
Composer 0.5x, Claude Sonnet 5 / Haiku 4.5 1.0x, Claude Sonnet 4.6 3.0x,
Claude Opus 4.7/4.8 5.0x, Fugu 5.0x, Claude Fable 5 10.0x). Consumption
per task varies by workload and model choice; as one real example,
Orange's PR review costs a median of ~79 credits (~¥0.8, p90 ~260
credits/~¥2.6), based on our own production usage as of July 2026.

Monthly plans (5 tiers):

- Free Trial — Free. 100,000 credits valid 14 days. No credit card.
- Hobby — ¥3,000 / mo. 300,000 credits.
- Pro — ¥10,000 / mo. 1,000,000 credits.
- Business — ¥50,000 / mo. 5,000,000 credits.
- 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.orange.codens.ai
- Pricing page (humans): https://www.codens.ai/pricing.html
- Contact: https://www.codens.ai/contact.html