Codens Help — Use the Codens family from any AI agent

1. Access paths — three options

Codens can be reached through three paths. Using MCP is the simplest: any MCP-compatible client (Claude Code, Cursor, Cline, etc.) gains access to all tools automatically.

Path	Audience	Characteristics	Recommendation
Via MCP	Claude Code, Cursor, Cline, and other MCP-capable agents	Install `codens-mcp` and register it in `~/.claude/settings.json`; all 30 tools become available. Authentication uses an OAuth flow, and credit and billing are linked automatically.	Recommended
REST API direct	Custom agents, CI jobs, and backend integrations	Call `https://api.purple.codens.ai` and the corresponding service endpoints directly using their OpenAPI specs. Bearer tokens are issued by Auth Codens. The `Idempotency-Key` header is supported.	—
Stripe Projects auto-signup	Future: agents and individual users without an existing contract	Onboard through the Stripe Customer Portal with usage-based pricing. The first credit grant is applied automatically, allowing immediate use of Codens. (Planned.)	Coming soon

2. Quick Start (via MCP)

Three steps put every Codens tool within reach of your agent.

Step 1. Install

pip install codens-mcp

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

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

The same MCP server configuration is supported in Cursor and Cline. Adapt the JSON to each client's settings file format.

Step 3. First-time authentication — the `purple_login` tool

Calling the tool below opens a browser and starts the OAuth flow. After completion, the token is stored in your operating system's secure store, and subsequent tool calls authenticate automatically.

// Example agent invocation
await tools.purple_login({});

// Response
{
  "ok": true,
  "user_id": "u_01H...",
  "organization_id": "org_01H...",
  "credits_remaining_jpy": 5000
}

Setup complete

From this point forward, every Purple, Red, Blue, Green, and Auth tool is callable from your agent. The next section, "Four use cases", shows concrete examples.

3. Four practical use cases

Four representative scenarios are shown below. Each is illustrated with a sample dialogue and the sequence of tools that the agent invokes.

A. Hand a development task to Codens for automatic implementation — Purple Codens

Pull an implementation task out of your local repository and let Claude Code, running on a Purple Codens VPS, complete the work and open a pull request. Multiple tasks can run in parallel.

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

Agent: -> purple_workflow_create({
    repo: "Corevice/auth-codens",
    title: "Add rate limiting to login API",
    description: "Apply 10 req/min per IP using a Redis-backed limiter. Add tests.",
    base_branch: "develop"
  })
  -> Poll progress with purple_workflow_status({ workflow_id })
  -> Share the PR URL with the user once the workflow completes.

B. Bug report to automated fix PR — Red into Purple chain

Errors detected by Sentry or reported manually are analyzed by Red Codens, and Purple Codens then produces the fix PR. Red can issue a PR on its own, but chaining into Purple yields higher-quality results for complex fixes.

User: "Please fix Sentry issue ABC-123."

Agent: -> red_analyze_error({ sentry_issue_id: "ABC-123" })
  -> Review the suggested_fix in the response.
  -> red_generate_fix_pr({
       sentry_issue_id: "ABC-123",
       use_purple_chain: true   // High-quality mode
     })
  -> PR URL: https://github.com/Corevice/.../pull/512

C. AI-generated and AI-executed E2E tests — Blue Codens

Generate E2E test scenarios automatically from a PRD or issue, and run them in coordination with CI. When tests fail, the trace can be passed to Red Codens for an automated fix.

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

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

D. From conversation to PRD to implementation — Green into Purple

Green Codens shapes vague requests into a structured PRD, and the same PRD is handed to Purple Codens for automated implementation. Notion synchronization is enabled by default.

User: "Add an annual plan option to the billing screen. Please handle requirements gathering and implementation."

Agent: -> green_prd_create({
    title: "Annual plan selection UI",
    raw_input: "Add an annual plan option to the billing screen..."
  })
  -> green_prd_finalize({ prd_id })  // The AI structures the requirements.
  -> purple_workflow_create({
       repo: "Corevice/billing-control-plane",
       prd_id,
       base_branch: "develop"
     })
  -> Share the PR URL with the user once the workflow completes.

4. The full catalog of 30 tools

The list below covers every tool offered by the Codens family. Once the MCP server is enabled, all of them are directly callable from an agent.

Purple Codens (16 tools) — AI development orchestration

Tool	Description
`purple_login`	Sign in to Codens via the OAuth flow and store the token in the secure store.
`purple_logout`	Discard the stored token.
`purple_whoami`	Return the current user, organization, and remaining credit.
`purple_workflow_create`	Create a new workflow (task) and start execution on a VPS.
`purple_workflow_status`	Retrieve the workflow's current step, progress, and remaining time.
`purple_workflow_list`	List the organization's workflows, filterable by status, repository, and creation time.
`purple_workflow_logs`	Fetch execution logs for a workflow as a stream or batch.
`purple_workflow_cancel`	Stop a running workflow.
`purple_workflow_retry`	Resume from the failed step. Useful after the underlying cause has been corrected.
`purple_task_create`	Create a single task within a workflow directly (for manual breakdowns).
`purple_task_attach_file`	Attach additional context (PRD, specification) to a task.
`purple_repo_register`	Register a new repository with the Codens project, including the useWorktree setting.
`purple_repo_list`	Return the list of registered repositories.
`purple_credit_balance`	Return the credit balance, the consumption over the past 7 days, and the next reset.
`purple_credit_grant`	(Admin) Grant credits to an arbitrary organization.
`purple_billing_portal_url`	Return a signed URL to the Stripe Customer Portal.

Red Codens (4 tools) — error detection and automated fix PRs

Tool	Description
`red_analyze_error`	Analyze a Sentry issue or stack trace and return the root cause and a fix plan.
`red_generate_fix_pr`	Generate the fix PR automatically. Setting `use_purple_chain` enables high-quality mode.
`red_list_recent_fixes`	Return the recent automated fix PRs and their merge status.
`red_run_3retry_loop`	Retry up to three times, feeding test results back into the prompt.

Blue Codens (4 tools) — QA automation

Tool	Description
`blue_generate_unit_tests`	Automatically generate unit tests for a given module or function.
`blue_generate_e2e_tests`	Automatically generate E2E test scenarios from a feature or PRD (Playwright or Cypress).
`blue_run_e2e`	Execute an E2E test suite and return video, trace, and network logs.
`blue_analyze_failure`	Analyze a failing trace and return a report that can be chained into Red Codens.

Green Codens (4 tools) — PRD creation and management

Tool	Description
`green_prd_create`	Create a draft PRD from raw input (Claude structures the content).
`green_prd_finalize`	Finalize the draft and synchronize it to Notion or a GitHub Issue.
`green_prd_list`	List PRDs (filterable by status, owner, and related repository).
`green_prd_link_workflow`	Link a PRD to a Purple workflow and synchronize progress in both directions.

Auth Codens (2 tools) — authentication and organization management

Tool	Description
`auth_token_refresh`	Refresh the access token. Useful for renewing it before it expires.
`auth_org_switch`	Switch the active organization for users who belong to multiple organizations.

Total: Purple 16 + Red 4 + Blue 4 + Green 4 + Auth 2 = 30 tools.

5. Error envelope

Every REST and MCP endpoint returns errors in a common envelope. The error_code field is a machine-readable enum that an agent can use to decide whether to retry or fall back.

Common error format

{
  "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
}

The nine `error_code` enum values and their retry semantics

error_code	Meaning	Retry semantics
`RATE_LIMITED`	The rate limit was exceeded. Respect `details.retry_after_seconds`.	retryable: true (with exponential backoff)
`BUDGET_EXCEEDED`	The organization's monthly budget cap has been reached. Increase it via `purple_billing_portal_url`.	retryable: false
`CREDIT_INSUFFICIENT`	The credit balance is insufficient. Confirm the balance with `purple_credit_balance`.	retryable: false
`WORKFLOW_NOT_FOUND`	The specified workflow_id does not exist or is owned by a different organization.	retryable: false
`UNAUTHORIZED`	The token is invalid or has expired. Retry after calling `auth_token_refresh`.	retryable: true (after refresh)
`IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD`	The same Idempotency-Key was sent again with a different payload.	retryable: false
`INTERNAL_ERROR`	An unexpected server-side error. Contact support with the trace_id.	retryable: true (with a short backoff)
`VALIDATION_ERROR`	The request body or query parameters failed validation.	retryable: false
`RESOURCE_NOT_FOUND`	The target resource (repository, PRD, task, etc.) does not exist.	retryable: false

Operating with Idempotency-Key

Write endpoints that create workflows or pull requests require the Idempotency-Key header. The same key paired with the same payload returns the same result; if the payload differs, the request is rejected with IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_PAYLOAD.

6. Pricing

Codens uses a hybrid model that combines prepaid credits and usage-based billing. For details, please refer to the Pricing page. Agents that need a machine-readable view should call the endpoint below.

Machine-readable pricing endpoint

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

// Response
{
  "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
}

New organizations receive an automatic credit grant of 1,000 JPY on first signup. Onboarding via the planned Stripe Projects auto-signup will offer an additional bonus.

7. Troubleshooting

The table below lists common symptoms and points to check. If the issue is not resolved, please reach out via the Contact page and include the trace_id.

Symptom	What to verify
The MCP tools are not visible to the agent.	Confirm that `mcpServers.codens.command` in `~/.claude/settings.json` points to the absolute path of the installed `codens-mcp` binary. Please share the output of `which codens-mcp` when reporting the issue.
`UNAUTHORIZED` errors are returned repeatedly.	The token has likely expired. Run `purple_login` again, or include `auth_token_refresh` in the agent flow.
The workflow stays in "pending" and does not start.	The VPS pool may be saturated. Check `queue_position` in the `purple_workflow_status` response. If progress remains stalled for more than 15 minutes, contact us with the trace_id.
Credits are consumed faster than expected.	Inspect `recent_consumption` in the `purple_credit_balance` response. Identify the heaviest tools through `tool_breakdown` and, if necessary, throttle them with `purple_workflow_cancel`.
A pull request is created, but tests are failing.	Use `red_run_3retry_loop` to feed the test results back and retry the fix up to three times. If the tests still fail, run `blue_analyze_failure` to identify the root cause.
Notion synchronization (Green) is not reflected.	Verify whether the organization's Notion integration is enabled by checking `sync_status` in the `green_prd_list` response. If the value is `integration_disabled`, an administrator must review the integration in Auth Codens.

8. References

For deeper information, please follow the links below.

PyPI: codens-mcp — Unified MCP server (all 30 tools across Red / Blue / Green / Auth + Purple).
PyPI: purple-codens-mcp — Purple-only MCP (dependency of codens-mcp; usable standalone).
Pricing plans — Five tiers (1 credit = ¥0.01).
Pricing JSON (machine-readable) — Fetchable directly from agents (initial credit grant and per-tier rates).
OIDC Discovery — Auth metadata for the Codens family.
Codens Dashboard — Customer console (organization / project / billing settings).
Contact — Feature requests, bug reports, or sales inquiries.