Codemind

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.

{
  "type": "object",
  "properties": {
    "utm_source": {
      "type": "string",
      "description": "Optional marketing source tag, e.g. \"producthunt\". Lowercase letters, digits, \"_\", \".\" and \"-\", max 64 characters; anything else is ignored."
    },
    "utm_medium": {
      "type": "string",
      "description": "Optional marketing medium tag, e.g. \"launch\". Same format as utm_source."
    },
    "utm_campaign": {
      "type": "string",
      "description": "Optional campaign tag, e.g. \"ph-2026-10-08\". Same format as utm_source."
    },
    "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."
    }
  }
}

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.

{
  "type": "object",
  "properties": {
    "storyTitle": {
      "type": "string",
      "description": "Short title used to organize this build."
    },
    "acceptanceCriteria": {
      "type": "string",
      "description": "Detailed requirements — function signatures, file paths, edge cases. Used verbatim to generate the implementation."
    },
    "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."
    },
    "projectId": {
      "type": "string",
      "description": "Opaque identifier grouping related builds for CIL codebase context — omit to skip CIL entirely."
    },
    "examples": {
      "type": "array",
      "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.",
      "items": {
        "type": "object",
        "properties": {
          "target": {
            "type": "string"
          },
          "call": {
            "type": "string"
          },
          "imports": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "expected": {
            "description": "Expected return value, any JSON value (compared with toEqual). Set this OR throws."
          },
          "throws": {
            "type": "string"
          },
          "async": {
            "type": "boolean"
          }
        },
        "required": [
          "target",
          "call"
        ]
      }
    },
    "skipTestsFor": {
      "type": "array",
      "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.",
      "items": {
        "type": "string"
      }
    },
    "existingFiles": {
      "type": "array",
      "description": "PATCH MODE — pass current content of files being modified. Without this, codegen creates new files instead of editing existing ones.",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Repo-relative path being modified."
          },
          "content": {
            "type": "string",
            "description": "Complete current content of the file."
          },
          "role": {
            "type": "string",
            "enum": [
              "target",
              "context"
            ],
            "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."
          }
        },
        "required": [
          "path",
          "content"
        ]
      }
    },
    "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."
    },
    "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."
    }
  },
  "required": [
    "storyTitle",
    "acceptanceCriteria",
    "stackType"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "buildId": {
      "type": "string",
      "description": "The buildId returned by build_feature."
    }
  },
  "required": [
    "buildId"
  ]
}

Retry a failed build using the same spec (story, acceptance criteria, stack, existing files).

{
  "type": "object",
  "properties": {
    "buildId": {
      "type": "string",
      "description": "ID of the failed build to retry."
    }
  },
  "required": [
    "buildId"
  ]
}

Cancel a running build. Has no effect on builds that already reached a terminal state.

{
  "type": "object",
  "properties": {
    "buildId": {
      "type": "string",
      "description": "ID of the build to cancel."
    }
  },
  "required": [
    "buildId"
  ]
}

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.

{
  "type": "object",
  "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."
    }
  },
  "required": [
    "buildId",
    "correctedAcceptanceCriteria"
  ]
}

Get the current state of a build by ID (status and error details).

{
  "type": "object",
  "properties": {
    "buildId": {
      "type": "string",
      "description": "The build ID."
    }
  },
  "required": [
    "buildId"
  ]
}

List recent builds for this tenant.

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Max builds to return (default 20, max 50)."
    },
    "offset": {
      "type": "number",
      "description": "Pagination offset (default 0)."
    }
  }
}

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.

{
  "type": "object",
  "properties": {
    "buildId": {
      "type": "string",
      "description": "The build ID."
    }
  },
  "required": [
    "buildId"
  ]
}

Retrieve the generated files from a completed build. Returns each file path and full content.

{
  "type": "object",
  "properties": {
    "buildId": {
      "type": "string",
      "description": "The build ID."
    }
  },
  "required": [
    "buildId"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "description": "Opaque project identifier — same value used in build_feature calls for this codebase."
    },
    "files": {
      "type": "array",
      "description": "Files to index, ≤10 files / ≤700KB total.",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "description": "Repo-relative path."
          },
          "content": {
            "type": "string",
            "description": "Complete file content."
          }
        },
        "required": [
          "path",
          "content"
        ]
      }
    }
  },
  "required": [
    "projectId",
    "files"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "stackType": {
      "type": "string",
      "description": "Runtime target stack (JavaScript/TypeScript only at launch), e.g. \"worker\", \"typescript\", \"node\", \"react\"."
    },
    "component": {
      "type": "object",
      "description": "MUST match the real code exactly — the generated verification test imports/calls by these exact names.",
      "properties": {
        "filePath": {
          "type": "string",
          "description": "Workspace-relative path of the file under test."
        },
        "exportName": {
          "type": "string",
          "description": "Primary export identifier the verification test will call."
        },
        "signature": {
          "type": "string",
          "description": "Declaration line for the primary export, in the target language."
        },
        "purpose": {
          "type": "string",
          "description": "Optional one-sentence description. Not required for testing."
        },
        "supportingTypes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Optional co-located type declarations the signature depends on."
        }
      },
      "required": [
        "filePath",
        "exportName",
        "signature"
      ]
    },
    "code": {
      "type": "string",
      "description": "The REAL implementation to test. Never shown to the model that generates the verification test."
    },
    "acceptanceCriteria": {
      "type": "string",
      "description": "What the code must do — the verification test is generated from this alone."
    },
    "contextFiles": {
      "type": "array",
      "description": "Optional ambient read-only files the code under test may import.",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "content": {
            "type": "string"
          }
        },
        "required": [
          "path",
          "content"
        ]
      }
    }
  },
  "required": [
    "stackType",
    "component",
    "code",
    "acceptanceCriteria"
  ]
}

Follow a test submitted by test_component in real time. Resolves with the pass/fail verdict and the generated verification test content.

{
  "type": "object",
  "properties": {
    "testId": {
      "type": "string",
      "description": "The testId returned by test_component."
    }
  },
  "required": [
    "testId"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "testId": {
      "type": "string",
      "description": "The testId returned by test_component."
    }
  },
  "required": [
    "testId"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "files": {
      "type": "array",
      "description": "Full file contents to review. Provide when you want the reviewer to see complete files, not just a diff.",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "content": {
            "type": "string"
          }
        },
        "required": [
          "path",
          "content"
        ]
      }
    },
    "diff": {
      "type": "string",
      "description": "A unified diff. The reviewer weights changed lines most heavily. Combined with files, must not exceed 150,000 characters."
    },
    "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",
      "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.",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "content": {
            "type": "string"
          }
        },
        "required": [
          "path",
          "content"
        ]
      }
    }
  }
}

Follow a review submitted by review_code in real time. Resolves with the findings and the approve/request-changes verdict.

{
  "type": "object",
  "properties": {
    "reviewId": {
      "type": "string",
      "description": "The reviewId returned by review_code."
    }
  },
  "required": [
    "reviewId"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "reviewId": {
      "type": "string",
      "description": "The reviewId returned by review_code."
    }
  },
  "required": [
    "reviewId"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "enum": [
        "overview",
        "patch-mode",
        "webhooks",
        "error-handling",
        "common-failures",
        "auth",
        "cloud-swarm"
      ],
      "description": "Which part of Codemind usage to get guidance on. Defaults to overview."
    }
  }
}

Lists GitHub repos currently attached to the caller's tenant via Cloud Repo Mode (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`.

{
  "type": "object",
  "properties": {}
}

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.

{
  "type": "object",
  "properties": {
    "repoAttachmentId": {
      "type": "string",
      "description": "The repo attachment id, as returned by list_repos (not an owner/repo string)."
    }
  },
  "required": [
    "repoAttachmentId"
  ]
}

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.

{
  "type": "object",
  "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."
    }
  },
  "required": [
    "triageRunId"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "description": "1 to 50 stories to dispatch.",
      "items": {
        "type": "object",
        "properties": {
          "repoUrl": {
            "type": "string"
          },
          "storyTitle": {
            "type": "string"
          },
          "acceptanceCriteria": {
            "type": "string"
          },
          "stackType": {
            "type": "string"
          },
          "existingFiles": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "path": {
                  "type": "string"
                },
                "content": {
                  "type": "string"
                },
                "role": {
                  "type": "string",
                  "enum": [
                    "target",
                    "context"
                  ]
                }
              },
              "required": [
                "path",
                "content"
              ]
            }
          },
          "skipTestsFor": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "examples": {
            "type": "array",
            "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.",
            "items": {
              "type": "object",
              "properties": {
                "target": {
                  "type": "string"
                },
                "call": {
                  "type": "string"
                },
                "imports": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "expected": {
                  "description": "Expected return value, any JSON value (compared with toEqual). Set this OR throws."
                },
                "throws": {
                  "type": "string"
                },
                "async": {
                  "type": "boolean"
                }
              },
              "required": [
                "target",
                "call"
              ]
            }
          }
        },
        "required": [
          "repoUrl",
          "storyTitle",
          "acceptanceCriteria",
          "stackType"
        ]
      }
    },
    "idempotencyKey": {
      "type": "string",
      "description": "A repeat call with the same key returns the original batchId instead of dispatching again."
    },
    "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."
    }
  },
  "required": [
    "items"
  ]
}

Get the aggregate status of a batch submitted via build_batch.

{
  "type": "object",
  "properties": {
    "batchId": {
      "type": "string"
    }
  },
  "required": [
    "batchId"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "batchId": {
      "type": "string"
    }
  },
  "required": [
    "batchId"
  ]
}

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.

{
  "type": "object",
  "properties": {
    "specText": {
      "type": "string"
    },
    "repos": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "repoUrl": {
            "type": "string"
          },
          "hint": {
            "type": "string"
          }
        },
        "required": [
          "repoUrl"
        ]
      }
    },
    "maxStories": {
      "type": "number",
      "description": "Default 20, hard ceiling 50."
    },
    "dryRun": {
      "type": "boolean"
    },
    "webhookUrl": {
      "type": "string"
    },
    "webhookSecret": {
      "type": "string"
    }
  },
  "required": [
    "specText",
    "repos"
  ]
}