Hand routine JS/TS tasks to Codemind from your agent. $0.10 per verified build; failures are free.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Submit several pre-decomposed stories in one call and get back one batchId to track, instead of dispatching build_feature N times yourself. Swarm is a Pro plan feature: the maximum batch size depends on the account plan (up to 50; not available on Free or the base pay-as-you-go account); a batch over the limit is refused with BATCH_SIZE_LIMIT_EXCEEDED and the limit. Each item has the same shape as a single build_feature call (storyTitle, acceptanceCriteria, stackType, existingFiles?, skipTestsFor?) plus its own repoUrl (informational only). Call get_batch with the returned batchId to check aggregate progress.
1 to 50 stories to dispatch.
Fires once when every item in the batch reaches a terminal state. Must be supplied together with webhookSecret.
HMAC-SHA256 signing secret (16-256 chars) for the aggregate completion webhook. Must be supplied together with webhookUrl.
A repeat call with the same key returns the original batchId instead of dispatching again.
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
Submit several pre-decomposed stories in one call and get back one batchId to track, instead of dispatching build_feature N times yourself. Swarm is a Pro plan feature: the maximum batch size depends on the account plan (up to 50; not available on Free or the base pay-as-you-go account); a batch over the limit is refused with BATCH_SIZE_LIMIT_EXCEEDED and the limit. Each item has the same shape as a single build_feature call (storyTitle, acceptanceCriteria, stackType, existingFiles?, skipTestsFor?) plus its own repoUrl (informational only). Call get_batch with the returned batchId to check aggregate progress.
| Argument | Type | Description |
|---|---|---|
| items* | array | 1 to 50 stories to dispatch. |
| webhookUrl | string | Fires once when every item in the batch reaches a terminal state. Must be supplied together with webhookSecret. |
| webhookSecret | string | HMAC-SHA256 signing secret (16-256 chars) for the aggregate completion webhook. Must be supplied together with webhookUrl. |
| idempotencyKey | string | A repeat call with the same key returns the original batchId instead of dispatching again. |
{
"type": "object",
"required": [
"items"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"repoUrl",
"storyTitle",
"acceptanceCriteria",
"stackType"
],
"properties": {
"repoUrl": {
"type": "string"
},
"examples": {
"type": "array",
"items": {
"type": "object",
"required": [
"target",
"call"
],
"properties": {
"call": {
"type": "string"
},
"async": {
"type": "boolean"
},
"target": {
"type": "string"
},
"throws": {
"type": "string"
},
"imports": {
"type": "array",
"items": {
"type": "string"
}
},
"expected": {
"description": "Expected return value, any JSON value (compared with toEqual). Set this OR throws."
}
}
},
"description": "OPTIONAL call → result examples, turned directly into test cases (no LLM), so the build is verified against exactly these. Each: { target: repo-relative .ts/.tsx path of the file under test, call: a TS expression such as \"clamp(5, 0, 10)\", imports?: export names the call uses (default: the component's main export), expected?: JSON value (compared with toEqual) OR throws?: error class name such as \"RangeError\", async?: true when the call returns a promise }. Exactly one of expected / throws per example; max 50. expected is JSON, so undefined, NaN, -0 and Dates cannot be expressed; describe those in acceptanceCriteria instead. For a new file every example must fail before the implementation exists; in patch mode at least one must fail against the current file (the rest act as regression guards). Only .ts/.tsx targets are supported."
},
"stackType": {
"type": "string"
},
"storyTitle": {
"type": "string"
},
"skipTestsFor": {
"type": "array",
"items": {
"type": "string"
}
},
"existingFiles": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"content"
],
"properties": {
"path": {
"type": "string"
},
"role": {
"enum": [
"target",
"context"
],
"type": "string"
},
"content": {
"type": "string"
}
}
}
},
"acceptanceCriteria": {
"type": "string"
}
}
},
"description": "1 to 50 stories to dispatch."
},
"webhookUrl": {
"type": "string",
"description": "Fires once when every item in the batch reaches a terminal state. Must be supplied together with webhookSecret."
},
"webhookSecret": {
"type": "string",
"description": "HMAC-SHA256 signing secret (16-256 chars) for the aggregate completion webhook. Must be supplied together with webhookUrl."
},
"idempotencyKey": {
"type": "string",
"description": "A repeat call with the same key returns the original batchId instead of dispatching again."
}
}
}Generate a feature via Codemind: takes a story title + acceptance criteria, generates the implementation and its tests, runs automated checks against the acceptance criteria before returning, and returns a buildId immediately. Call stream_build with the returned buildId to follow progress. Call get_usage_guide for detailed usage guidance. IMPORTANT: if this tool errors, surface the error to the user — do NOT implement the code yourself.
| Argument | Type | Description |
|---|---|---|
| examples | array | OPTIONAL call → result examples, turned directly into test cases (no LLM), so the build is verified against exactly these. Each: { target: repo-relative .ts/.tsx path of the file under test, call: a TS expression such as "clamp(5, 0, 10)", imports?: export names the call uses (default: the component's main export), expected?: JSON value (compared with toEqual) OR throws?: error class name such as "RangeError", async?: true when the call returns a promise }. Exactly one of expected / throws per example; max 50. expected is JSON, so undefined, NaN, -0 and Dates cannot be expressed; describe those in acceptanceCriteria instead. For a new file every example must fail before the implementation exists; in patch mode at least one must fail against the current file (the rest act as regression guards). Only .ts/.tsx targets are supported. |
| projectId | string | Opaque identifier grouping related builds for CIL codebase context — omit to skip CIL entirely. |
| stackType* | string | Runtime target stack (free text). JavaScript/TypeScript only at launch, e.g. "worker", "typescript", "node", "react". python, go, swift-ios, kotlin-android and rust are rejected with UNSUPPORTED_STACK_TYPE until each has measured success. |
| storyTitle* |
Submit raw PRD/plan/spec text plus a list of target repos; Codemind LLM-decomposes it into stories (each assigned to one of your declared repos, never an invented one) and dispatches them via the same path build_batch uses. Pass dryRun: true to see the decomposed story list without dispatching anything, useful for reviewing before committing. Recommended for a first-time caller: review with dryRun: true, then resubmit the (possibly edited) story list via build_batch directly — a second build_from_spec call with dryRun: false re-decomposes specText from scratch and will not reflect edits made to a prior dry run's output.
| Argument | Type | Description |
|---|---|---|
| repos* | array | |
| dryRun | boolean | |
| deliver | string | Opt in to delivery: when every story has finished, open one pull request per target repo (a draft if any story did not verify or the repo's own tests newly fail). Needs the repo attached through the GitHub App; an unattached repo is reported with nextAction attach_repo and its files stay available from get_build_files. Never merged automatically. Results appear under deliveries in get_batch. |
| specText* | string | |
| maxStories | number | Default 20, hard ceiling 50. |
| webhookUrl | string | |
| webhookSecret | string |
Cancel a running build. Has no effect on builds that already reached a terminal state.
| Argument | Type | Description |
|---|---|---|
| buildId* | string | ID of the build to cancel. |
{
"type": "object",
"required": [
"buildId"
],
"properties": {
"buildId": {
"type": "string",
"description": "ID of the build to cancel."
}
}
}Resume a finished Ship run (started with build_from_spec) that ended incomplete or nothing_delivered: re-dispatches only the stories that did not verify, in the same run. Verified stories are not rebuilt or billed again; a resumed story is billed once, when it first verifies. Each resumed story is told why its earlier attempt failed. At most 2 resumes per run (then RESUME_LIMIT_EXCEEDED). The same throttle, plan cap and allowance apply as for a new submission. Resuming a run with nothing left to do changes nothing. Track progress with get_batch.
| Argument | Type | Description |
|---|---|---|
| batchId* | string |
{
"type": "object",
"required": [
"batchId"
],
"properties": {
"batchId": {
"type": "string"
}
}
}Send corrected acceptance criteria to a running build. Applies to components that have not started generating yet; the currently-generating component finishes as originally scoped.
| Argument | Type | Description |
|---|---|---|
| buildId* | string | ID of the running build to steer. |
| correctedAcceptanceCriteria* | string | The new, complete acceptance criteria — replaces the original for all not-yet-started components. |
{
"type": "object",
"required": [
"buildId",
"correctedAcceptanceCriteria"
],
"properties": {
"buildId": {
"type": "string",
"description": "ID of the running build to steer."
},
"correctedAcceptanceCriteria": {
"type": "string",
"description": "The new, complete acceptance criteria — replaces the original for all not-yet-started components."
}
}
}Instantly provision a new anonymous Codemind account on the free plan — no credential, no human step required. Call this when build_feature (or any other tool) fails with an auth error and no CODEMIND_API_KEY is configured. Returns a tenantId and a bearer token (apiKey) usable immediately for build_feature and every other tool. The account is anonymous (no identity attached) until a person opens the claim link in the response text and signs in. If a tool call fails with an auth error and you ALREADY have a configured apiKey, call get_usage_guide with topic "auth" before calling this tool again — replacing an already-claimed account's credential here loses its identity and history. All arguments are optional; pass utm_source, utm_medium and utm_campaign, and invite, only if your human gave you them.
| Argument | Type | Description |
|---|---|---|
| invite | string | Optional invite code from an invite link your human gave you. Case-sensitive; pass it exactly as given. An invalid or used-up code is ignored. |
| ph_did | string | Optional web visitor id from a setup link or command your human gave you (--ph-did). Pass it exactly as given; an invalid value is ignored. |
| utm_medium | string | Optional marketing medium tag, e.g. "launch". Same format as utm_source. |
| utm_source | string | Optional marketing source tag, e.g. "producthunt". Lowercase letters, digits, "_", "." and "-", max 64 characters; anything else is ignored. |
| utm_campaign | string | Optional campaign tag, e.g. "ph-2026-10-08". Same format as utm_source. |
Get the aggregate status of a batch submitted via build_batch.
| Argument | Type | Description |
|---|---|---|
| batchId* | string |
{
"type": "object",
"required": [
"batchId"
],
"properties": {
"batchId": {
"type": "string"
}
}
}Read-only: your plan, how many verified builds you have used, how many are included and left in the current allowance window, and the paid-balance draw (cents) if you have topped up. Call this to check headroom before a large batch, or to learn why a build was rejected for allowance.
No arguments.
{
"type": "object",
"properties": {}
}Get the current state of a build by ID (status and error details).
| Argument | Type | Description |
|---|---|---|
| buildId* | string | The build ID. |
{
"type": "object",
"required": [
"buildId"
],
"properties": {
"buildId": {
"type": "string",
"description": "The build ID."
}
}
}Retrieve the generated files from a completed build. Returns each file path and full content.
| Argument | Type | Description |
|---|---|---|
| buildId* | string | The build ID. |
{
"type": "object",
"required": [
"buildId"
],
"properties": {
"buildId": {
"type": "string",
"description": "The build ID."
}
}
}Get a build's original submitted spec (storyTitle, acceptanceCriteria, stackType, existingFiles, skipTestsFor) without retrying it — useful for inspecting or reusing a prior build's spec as a template.
| Argument | Type | Description |
|---|---|---|
| buildId* | string | The build ID. |
{
"type": "object",
"required": [
"buildId"
],
"properties": {
"buildId": {
"type": "string",
"description": "The build ID."
}
}
}Get the current state of a review by ID (status, verdict, findings) without streaming — useful for polling or inspecting a review after the fact. Use stream_review to follow a review in real time instead.
| Argument | Type | Description |
|---|---|---|
| reviewId* | string | The reviewId returned by review_code. |
{
"type": "object",
"required": [
"reviewId"
],
"properties": {
"reviewId": {
"type": "string",
"description": "The reviewId returned by review_code."
}
}
}Get the current state of a test by ID (status, pass/fail verdict, generated verification test content) without streaming — useful for polling or inspecting a test after the fact. Use stream_test to follow a test in real time instead.
| Argument | Type | Description |
|---|---|---|
| testId* | string | The testId returned by test_component. |
{
"type": "object",
"required": [
"testId"
],
"properties": {
"testId": {
"type": "string",
"description": "The testId returned by test_component."
}
}
}Returns the generated fix diff (as file paths and line counts, not full content) and before/after test-run output for one triage run, identified by the triage run id from get_triage_runs (NOT a build id and NOT an issue number). stdout/stderr are tail-truncated because test failure summaries appear at the end of output, not the install noise at the start. Full file contents are available separately via the get_build_files tool using the run's buildId. Also includes a per-LLM-call trace (stage/model/status/latency) from Analytics Engine when available, covering attempts that failed before ever reaching the before/after test comparison above.
| Argument | Type | Description |
|---|---|---|
| triageRunId* | string | The triage run id, as returned by get_triage_runs (the first token of each line), not the build id or issue number. |
{
"type": "object",
"required": [
"triageRunId"
],
"properties": {
"triageRunId": {
"type": "string",
"description": "The triage run id, as returned by get_triage_runs (the first token of each line), not the build id or issue number."
}
}
}Lists the issue-triage run history for one attached repo — one row per GitHub issue that was auto-triaged — including terminal status (`pr_opened` means a fix PR was opened and passed the repo's own test suite; `needs_human` means the issue wasn't judged auto-fixable; `failed` means the triage/build/verify pipeline errored). The `repoAttachmentId` is the attachment `id` returned by `list_repos`, NOT a `owner/repo` string. Full diagnostics (the generated diff and before/after test output) for any run id returned here are available via the get_triage_diagnostics tool.
| Argument | Type | Description |
|---|---|---|
| repoAttachmentId* | string | The repo attachment id, as returned by list_repos (not an owner/repo string). |
{
"type": "object",
"required": [
"repoAttachmentId"
],
"properties": {
"repoAttachmentId": {
"type": "string",
"description": "The repo attachment id, as returned by list_repos (not an owner/repo string)."
}
}
}Get detailed usage guidance for Codemind's tools — how to write effective acceptanceCriteria, when to use patch mode, how webhooks work, what to do when a build declines, common failure patterns unrelated to acceptanceCriteria quality, and how to recover from an auth error without losing an identified account. Call this before build_feature/test_component/review_code if you are unfamiliar with this tool surface, or if the same story fails repeatedly across retries; call it with topic "auth" before calling create_free_account to recover from an auth error on an existing credential.
| Argument | Type | Description |
|---|---|---|
| topic | string | Which part of Codemind usage to get guidance on. Defaults to overview. |
{
"type": "object",
"properties": {
"topic": {
"enum": [
"overview",
"patch-mode",
"webhooks",
"error-handling",
"common-failures",
"auth",
"cloud-swarm"
],
"type": "string",
"description": "Which part of Codemind usage to get guidance on. Defaults to overview."
}
}
}List recent builds for this tenant.
| Argument | Type | Description |
|---|---|---|
| limit | number | Max builds to return (default 20, max 50). |
| offset | number | Pagination offset (default 0). |
{
"type": "object",
"properties": {
"limit": {
"type": "number",
"description": "Max builds to return (default 20, max 50)."
},
"offset": {
"type": "number",
"description": "Pagination offset (default 0)."
}
}
}Lists GitHub repos currently attached to the caller's tenant via Codemind Resolve (the GitHub App that automatically triages filed issues into fix PRs), and that the returned `id` field is the repo attachment id to pass into `get_triage_runs`.
No arguments.
{
"type": "object",
"properties": {}
}Index files into the CIL codebase context for a project — for files Codemind itself did not generate (a manual edit, another tool's output). Not needed after a normal build_feature call: a completed build's own output is indexed automatically when projectId was supplied.
| Argument | Type | Description |
|---|---|---|
| files* | array | Files to index, ≤10 files / ≤700KB total. |
| projectId* | string | Opaque project identifier — same value used in build_feature calls for this codebase. |
{
"type": "object",
"required": [
"projectId",
"files"
],
"properties": {
"files": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"content"
],
"properties": {
"path": {
"type": "string",
"description": "Repo-relative path."
},
"content": {
"type": "string",
"description": "Complete file content."
}
}
},
"description": "Files to index, ≤10 files / ≤700KB total."
},
"projectId": {
"type": "string",
"description": "Opaque project identifier — same value used in build_feature calls for this codebase."
}
}
}Retry a failed build using the same spec (story, acceptance criteria, stack, existing files).
| Argument | Type | Description |
|---|---|---|
| buildId* | string | ID of the failed build to retry. |
{
"type": "object",
"required": [
"buildId"
],
"properties": {
"buildId": {
"type": "string",
"description": "ID of the failed build to retry."
}
}
}Submit code for review: bugs, security issues, silent failures, and style concerns. Give it files (path+content) and/or a unified diff. At least one of files or diff is required — submitting neither is rejected. TWO independent LLM-judge passes review it (a general correctness/security pass and a dedicated silent-failure pass) and their findings are merged into one verdict. For a genuinely useful review, ALSO supply conventions (paste this project's CLAUDE.md and RULES.md content — you already have repo access, this tool does not) so both passes can enforce project-specific rules, and relatedFiles (any existing file the change references but doesn't itself modify — an interface being implemented, a caller of a changed function, a sibling example of the real convention) so findings can be verified against actual code instead of guessed. Omitting both still works but produces a weaker review with no codebase grounding. No code generation or execution happens here — this is judgment only, not test verification (use test_component for that). Returns a reviewId immediately; call stream_review to follow progress and get the findings. Call get_usage_guide for detailed usage guidance.
| Argument | Type | Description |
|---|---|---|
| diff | string | A unified diff. The reviewer weights changed lines most heavily. Combined with files, must not exceed 150,000 characters. |
| files | array | Full file contents to review. Provide when you want the reviewer to see complete files, not just a diff. |
| context | string | Optional story/PR description to give the reviewer intent context. |
| conventions | string | This project's CLAUDE.md and/or RULES.md content (or the relevant excerpt). Strongly recommended when available — both review passes treat this as authoritative: a finding that violates a stated rule here is always blocking. |
Stream live progress for a batch submitted via build_batch. Polls the batch's aggregate status periodically and emits a progress notification each tick; closes once the batch reaches a terminal status (completed or completed_with_failures). Call get_batch instead for a single point-in-time snapshot.
| Argument | Type | Description |
|---|---|---|
| batchId* | string |
{
"type": "object",
"required": [
"batchId"
],
"properties": {
"batchId": {
"type": "string"
}
}
}Follow a build submitted by build_feature in real time. Emits a progress notification on every phase change and resolves with the final result when the build completes or fails. Use immediately after build_feature returns a buildId.
| Argument | Type | Description |
|---|---|---|
| buildId* | string | The buildId returned by build_feature. |
{
"type": "object",
"required": [
"buildId"
],
"properties": {
"buildId": {
"type": "string",
"description": "The buildId returned by build_feature."
}
}
}Follow a review submitted by review_code in real time. Resolves with the findings and the approve/request-changes verdict.
| Argument | Type | Description |
|---|---|---|
| reviewId* | string | The reviewId returned by review_code. |
{
"type": "object",
"required": [
"reviewId"
],
"properties": {
"reviewId": {
"type": "string",
"description": "The reviewId returned by review_code."
}
}
}Follow a test submitted by test_component in real time. Resolves with the pass/fail verdict and the generated verification test content.
| Argument | Type | Description |
|---|---|---|
| testId* | string | The testId returned by test_component. |
{
"type": "object",
"required": [
"testId"
],
"properties": {
"testId": {
"type": "string",
"description": "The testId returned by test_component."
}
}
}Run standalone cloud verification on code you already have: give it a component (filePath/exportName/signature) plus acceptance criteria, and it generates a black-box verification test, validates that test against a mechanical stub, then executes your REAL code against it in the cloud (isolate or container, per stack). No code generation happens here — use build_feature for that. Returns a testId immediately; call stream_test to follow progress and get the pass/fail verdict. Call get_usage_guide for detailed usage guidance.
| Argument | Type | Description |
|---|---|---|
| code* | string | The REAL implementation to test. Never shown to the model that generates the verification test. |
| component* | object | MUST match the real code exactly — the generated verification test imports/calls by these exact names. |
| stackType* | string | Runtime target stack (JavaScript/TypeScript only at launch), e.g. "worker", "typescript", "node", "react". |
| contextFiles | array | Optional ambient read-only files the code under test may import. |
| acceptanceCriteria* | string | What the code must do — the verification test is generated from this alone. |
{
"type": "object",
"required": [
"stackType",
"component",
"code",
"acceptanceCriteria"
],
"properties": {
"code": {
"type": "string",
"description": "The REAL implementation to test. Never shown to the model that generates the verification test."
},
"component": {
"type": "object",
"required": [
"filePath",
"exportName",
"signature"
],
"properties": {
"purpose": {
"type": "string",
"description": "Optional one-sentence description. Not required for testing."
},
"filePath": {
"type": "string",
"description": "Workspace-relative path of the file under test."
},
"signature": {
"type": "string",
"description": "Declaration line for the primary export, in the target language."
},
"exportName": {
"type": "string",
"description": "Primary export identifier the verification test will call."
},
"supportingTypes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional co-located type declarations the signature depends on."
}
},
"description": "MUST match the real code exactly — the generated verification test imports/calls by these exact names."
},
"stackType": {
"type": "string",
"description": "Runtime target stack (JavaScript/TypeScript only at launch), e.g. \"worker\", \"typescript\", \"node\", \"react\"."
},
"contextFiles": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"content"
],
"properties": {
"path": {
"type": "string"
},
"content": {
"type": "string"
}
}
},
"description": "Optional ambient read-only files the code under test may import."
},
"acceptanceCriteria": {
"type": "string",
"description": "What the code must do — the verification test is generated from this alone."
}
}
}| string |
| Short title used to organize this build. |
| webhookUrl | string | HTTPS URL to POST a signed payload to when the build reaches a terminal state (completed/failed). Must be supplied together with webhookSecret. |
| skipTestsFor | array | Repo-relative source paths (max 20) to opt OUT of test-file delivery for — e.g. the repo has no test framework and a scaffolded test file would be unwanted. Verification still ALWAYS runs against every component regardless of this setting — it only filters which files are DELIVERED to you, never whether verification happens. If the target project has NO test infrastructure at all, the build will very likely still fail even with this set — there is currently no fallback verification mode (e.g. typecheck-only) for that case. Explicit opt-in only, never infer from acceptanceCriteria prose. |
| existingFiles | array | PATCH MODE — pass current content of files being modified. Without this, codegen creates new files instead of editing existing ones. |
| webhookSecret | string | Shared secret (16-256 chars) used to HMAC-SHA256-sign the webhook payload, sent in the x-codemind-v2-signature header. Must be supplied together with webhookUrl. Never echoed back. |
| acceptanceCriteria* | string | Detailed requirements — function signatures, file paths, edge cases. Used verbatim to generate the implementation. |
{
"type": "object",
"required": [
"storyTitle",
"acceptanceCriteria",
"stackType"
],
"properties": {
"examples": {
"type": "array",
"items": {
"type": "object",
"required": [
"target",
"call"
],
"properties": {
"call": {
"type": "string"
},
"async": {
"type": "boolean"
},
"target": {
"type": "string"
},
"throws": {
"type": "string"
},
"imports": {
"type": "array",
"items": {
"type": "string"
}
},
"expected": {
"description": "Expected return value, any JSON value (compared with toEqual). Set this OR throws."
}
}
},
"description": "OPTIONAL call → result examples, turned directly into test cases (no LLM), so the build is verified against exactly these. Each: { target: repo-relative .ts/.tsx path of the file under test, call: a TS expression such as \"clamp(5, 0, 10)\", imports?: export names the call uses (default: the component's main export), expected?: JSON value (compared with toEqual) OR throws?: error class name such as \"RangeError\", async?: true when the call returns a promise }. Exactly one of expected / throws per example; max 50. expected is JSON, so undefined, NaN, -0 and Dates cannot be expressed; describe those in acceptanceCriteria instead. For a new file every example must fail before the implementation exists; in patch mode at least one must fail against the current file (the rest act as regression guards). Only .ts/.tsx targets are supported."
},
"projectId": {
"type": "string",
"description": "Opaque identifier grouping related builds for CIL codebase context — omit to skip CIL entirely."
},
"stackType": {
"type": "string",
"description": "Runtime target stack (free text). JavaScript/TypeScript only at launch, e.g. \"worker\", \"typescript\", \"node\", \"react\". python, go, swift-ios, kotlin-android and rust are rejected with UNSUPPORTED_STACK_TYPE until each has measured success."
},
"storyTitle": {
"type": "string",
"description": "Short title used to organize this build."
},
"webhookUrl": {
"type": "string",
"description": "HTTPS URL to POST a signed payload to when the build reaches a terminal state (completed/failed). Must be supplied together with webhookSecret."
},
"skipTestsFor": {
"type": "array",
"items": {
"type": "string"
},
"description": "Repo-relative source paths (max 20) to opt OUT of test-file delivery for — e.g. the repo has no test framework and a scaffolded test file would be unwanted. Verification still ALWAYS runs against every component regardless of this setting — it only filters which files are DELIVERED to you, never whether verification happens. If the target project has NO test infrastructure at all, the build will very likely still fail even with this set — there is currently no fallback verification mode (e.g. typecheck-only) for that case. Explicit opt-in only, never infer from acceptanceCriteria prose."
},
"existingFiles": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"content"
],
"properties": {
"path": {
"type": "string",
"description": "Repo-relative path being modified."
},
"role": {
"enum": [
"target",
"context"
],
"type": "string",
"description": "'target' asserts this exact path must become its own patchable component, even if the acceptanceCriteria never quotes its exact path verbatim — use this when a prior build's response indicated an existingFiles path was not matched to any component of that build; does not change the pre-flight import check below. 'context' means this file is supplied only to resolve some OTHER file's import, not to be patched itself — it EXEMPTS this file's own imports from the pre-flight check that otherwise requires every existingFiles entry's imports to also be supplied (unless acceptanceCriteria quotes this file's exact path verbatim, in which case the file may still become a real patch target and the exemption does not apply). Omitting role is NOT the same as 'context' — an omitted-role file's own imports are ALWAYS required to be supplied, same as 'target'; role is otherwise purely an ADDITIONAL signal for whether this path is treated as a guaranteed component, not an exclusion from that. NOT supported when path is a test file (*.test.ts, *_test.go, test_*.py, *Test.kt, etc.) — v2 always synthesizes its own verification test per component, so an existing test file cannot itself be a patch target yet; such a build is rejected."
},
"content": {
"type": "string",
"description": "Complete current content of the file."
}
}
},
"description": "PATCH MODE — pass current content of files being modified. Without this, codegen creates new files instead of editing existing ones."
},
"webhookSecret": {
"type": "string",
"description": "Shared secret (16-256 chars) used to HMAC-SHA256-sign the webhook payload, sent in the x-codemind-v2-signature header. Must be supplied together with webhookUrl. Never echoed back."
},
"acceptanceCriteria": {
"type": "string",
"description": "Detailed requirements — function signatures, file paths, edge cases. Used verbatim to generate the implementation."
}
}
}{
"type": "object",
"required": [
"specText",
"repos"
],
"properties": {
"repos": {
"type": "array",
"items": {
"type": "object",
"required": [
"repoUrl"
],
"properties": {
"hint": {
"type": "string"
},
"repoUrl": {
"type": "string"
},
"existingFiles": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"content"
],
"properties": {
"path": {
"type": "string"
},
"content": {
"type": "string"
}
}
},
"description": "OPTIONAL current contents of this repo's files that the spec changes or depends on ({path, content}). With deliver and the repo attached through the GitHub App you can omit this: Ship reads the files each story names, plus their local imports, from the repo itself. Every story for this repo is built with them (a file whose path the story names is edited, the rest are read-only context). With deliver, Ship only overwrites an existing file that is supplied here AND still has exactly this content in the repo at delivery; any other existing file is never overwritten."
}
}
}
},
"dryRun": {
"type": "boolean"
},
"deliver": {
"enum": [
"pull_request"
],
"type": "string",
"description": "Opt in to delivery: when every story has finished, open one pull request per target repo (a draft if any story did not verify or the repo's own tests newly fail). Needs the repo attached through the GitHub App; an unattached repo is reported with nextAction attach_repo and its files stay available from get_build_files. Never merged automatically. Results appear under deliveries in get_batch."
},
"specText": {
"type": "string"
},
"maxStories": {
"type": "number",
"description": "Default 20, hard ceiling 50."
},
"webhookUrl": {
"type": "string"
},
"webhookSecret": {
"type": "string"
}
}
}{
"type": "object",
"properties": {
"invite": {
"type": "string",
"description": "Optional invite code from an invite link your human gave you. Case-sensitive; pass it exactly as given. An invalid or used-up code is ignored."
},
"ph_did": {
"type": "string",
"description": "Optional web visitor id from a setup link or command your human gave you (--ph-did). Pass it exactly as given; an invalid value is ignored."
},
"utm_medium": {
"type": "string",
"description": "Optional marketing medium tag, e.g. \"launch\". Same format as utm_source."
},
"utm_source": {
"type": "string",
"description": "Optional marketing source tag, e.g. \"producthunt\". Lowercase letters, digits, \"_\", \".\" and \"-\", max 64 characters; anything else is ignored."
},
"utm_campaign": {
"type": "string",
"description": "Optional campaign tag, e.g. \"ph-2026-10-08\". Same format as utm_source."
}
}
}| relatedFiles | array | Existing files for cross-reference ONLY — never diffed, never themselves the subject of a finding. Supply an interface the change implements, a caller of a changed function, or a sibling file showing the project's real convention, so the reviewer can verify claims against real code instead of guessing. |
{
"type": "object",
"properties": {
"diff": {
"type": "string",
"description": "A unified diff. The reviewer weights changed lines most heavily. Combined with files, must not exceed 150,000 characters."
},
"files": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"content"
],
"properties": {
"path": {
"type": "string"
},
"content": {
"type": "string"
}
}
},
"description": "Full file contents to review. Provide when you want the reviewer to see complete files, not just a diff."
},
"context": {
"type": "string",
"description": "Optional story/PR description to give the reviewer intent context."
},
"conventions": {
"type": "string",
"description": "This project's CLAUDE.md and/or RULES.md content (or the relevant excerpt). Strongly recommended when available — both review passes treat this as authoritative: a finding that violates a stated rule here is always blocking."
},
"relatedFiles": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"content"
],
"properties": {
"path": {
"type": "string"
},
"content": {
"type": "string"
}
}
},
"description": "Existing files for cross-reference ONLY — never diffed, never themselves the subject of a finding. Supply an interface the change implements, a caller of a changed function, or a sibling file showing the project's real convention, so the reviewer can verify claims against real code instead of guessing."
}
}
}