Carrick

Carrick maps your entire TypeScript codebase across services and repositories, giving AI agents full context on existing types, routes, and function behaviours over MCP before they write duplicate or breaking code.

Carrick scans TypeScript projects using npm, pnpm, Yarn, Bun, or Deno. Deno projects require Deno 2.9.4 or newer; the Action supplies the runtime and reads existing deno.json or deno.jsonc manifests. Dependency preparation disables lifecycle scripts (details). Cross-repo features need at least two services indexed in the same Carrick project; a single-service install still gets same-repo validation.

Get started: sign up at app.carrick.tools · full documentation at docs.carrick.tools

What an agent can ask

Connect Claude Code, Cursor, Windsurf, or Codex to the Carrick MCP endpoint. Carrick answers semantic questions about your org that an agent normally has to grep across repos to answer, badly:

• "Which functions handle webhook signing across our services?"
• "Where do we deduplicate users by email?"
• "What calls /api/users and what response shape do they expect?"
• "Show me every function that retries on rate-limit errors."

These work because the index combines structural facts, resolved types, and a per-function description of what the code actually does.

What's in the index

For every scanned function in every repo in your org, Carrick stores three layers:

• Structural. Endpoints declared, outbound calls made, mounts, normalised paths.
• Type-aware. Request and response types resolved through the TypeScript compiler, so cross-repo type compatibility is checkable.
• Intent-aware. A one or two sentence description of what each function does, generated at scan time and stored alongside the structural and type data.

The intent layer is the difference. It is what lets an agent answer "where do we deduplicate users by email" rather than "which functions are named dedupeUser."

Connect your agent

The MCP endpoint lives at https://api.carrick.tools/mcp.

claude mcp add --scope user --transport http carrick https://api.carrick.tools/mcp

The recommended authentication is sign-in-with-Carrick: your agent opens a browser, you click Approve once, and no API key changes hands. A manual key paste is available as a fallback. To get started, sign up at app.carrick.tools — the full setup guide lives at docs.carrick.tools.

Populate the index

The index is populated by running the Carrick GitHub Action on each TypeScript repo you want indexed. On the main branch the action refreshes that repo's contribution to the index. On pull requests the Carrick App posts a drift comment for you (no extra workflow steps required).

name: Carrick

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  # Lets Carrick re-trigger this repo's main scan when a sibling repo in the
  # project changes. Optional today and dormant unless enabled server-side —
  # included here so it's already wired if you ever turn it on.
  repository_dispatch:
    types: [carrick-sibling-updated]

permissions:
  id-token: write
  contents: read

jobs:
  carrick:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        # Full git history lets Carrick diff against the last scan and run incrementally.
        with:
          fetch-depth: 0

      - uses: carrick-tools/carrick@v1

No secrets required. The id-token: write permission lets the action mint a short-lived GitHub Actions OIDC token, which Carrick uses to verify the repo's identity and authorize the upload. On pull requests the Carrick App posts the drift comment itself, so the workflow needs no extra permissions and no comment-posting step. Just make sure the Carrick GitHub App is installed on the org and the repo is connected to a project in the dashboard.

Pull requests opened from forks are skipped gracefully: GitHub withholds OIDC credentials from fork runs, so the action prints a notice and exits successfully instead of failing the check. The scan runs when a maintainer pushes the branch to the repository itself.

Dependencies

Package types need their dependencies on disk. Node projects use installed node_modules, and Deno projects use the Deno dependency cache. The Action prepares those dependencies before analysis:

• For Node projects, installation runs for every service the scan will visit, at that service's own nearest lockfile. A monorepo whose packages carry their own lockfiles is installed package by package; a workspace that hoists to one lockfile at its root is installed once. The lockfile picks the manager: package-lock.json runs npm ci, pnpm-lock.yaml runs pnpm install --frozen-lockfile, yarn.lock runs yarn install, bun.lock/bun.lockb runs bun install.
• Lifecycle scripts are disabled in every case, so nothing in your repo executes during a scan.
• Each install command has a five-minute timeout. A failed or timed-out install prints a warning, and the scan that follows refuses any service whose dependencies are still missing (see below).
• Existing node_modules skips that service's Node install. A Deno manifest still triggers Deno cache preparation, which the separate Deno cache does not get from a Node install.
• The package managers' download caches are restored between runs, keyed on the hash of every lockfile the run installs from.

For Deno roots the Action runs deno install --frozen --node-modules-dir=none. This prepares the Deno dependency cache and prevents npm lifecycle scripts from running even when the project authorizes them through allowScripts. A root with both Node and Deno configuration prepares both dependency stores. Before local indexing, install Deno 2.9.4 or newer and run the same preparation command from the Deno workspace root. Projects that import generated declarations must generate those declarations through their normal build before indexing.

An unprepared checkout is refused

Carrick refuses to scan a checkout it cannot type, rather than charging for an index whose types are any and saying nothing about why. The check runs before the scan starts, per service, on what is reachable from that service's own directory — a monorepo root that is installed says nothing about a nested workspace that is not. Two things are refused:

• Dependencies a lockfile states and the tree has not installed. The refusal names the service and the exact command, because the lockfile names the package manager. A tree with no lockfile above the service states no install and is scanned as it is. Deno services are asked only when their config sets nodeModulesDir, since Deno otherwise caches outside the tree.
• A config mapping whose target directory is not on the checkout, that the service imports through. A TypeScript paths entry, a package.json imports key or a Deno import-map entry pointing at, say, a generated client whose generator has not run. The refusal names the mapping and the missing directory and stops there: nothing in the config says what fills a generated directory. A mapping left behind by a deleted package, that nothing imports, is logged and scanned past — no type can be any through a mapping no import uses.

Both are proxies, so there is always a way past: --allow-unprepared on the command, CARRICK_ALLOW_UNPREPARED=1 in the environment, or allow-unprepared: true on the Action (which install-dependencies: false already implies). A pipeline that scans a bare checkout deliberately keeps working; it just says so.

Deno services normally omit tsconfig and use their nearest Deno manifest. An explicit ordinary TypeScript config selects the TypeScript path. An explicit Deno config must name that nearest manifest; deno.json takes precedence over deno.jsonc when both exist. Import maps must be local files.

Turn it off with:

      - uses: carrick-tools/carrick@v1
        with:
          install-dependencies: false

Private registries use your own credentials. Carrick adds no auth of its own: put the token your .npmrc reads in the job's environment and the install step inherits it.

      - uses: carrick-tools/carrick@v1
        env:
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Re-analyzing everything

A scan reads the model once per changed file and reuses what it already has for the rest, which is what makes a routine scan cheap. Occasionally the answers themselves need redoing rather than the files: Carrick starts extracting something it did not extract before, and the cache holds answers from before it could. full-scan re-analyzes every file for one run.

Ask for it, rather than leaving it on. Wire it to the workflow's workflow_dispatch input, which is what carrick init scaffolds:

on:
  workflow_dispatch:
    inputs:
      full-scan:
        type: boolean
        default: false

jobs:
  carrick:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: carrick-tools/carrick@v1
        with:
          full-scan: ${{ inputs.full-scan }}

Then run it from the Actions tab, or:

gh workflow run carrick.yml -f full-scan=true

On every other trigger the expression is empty and the incremental scan runs exactly as before.

An ordinary scan indexes a commit once per scanner version, so a second run on an unchanged commit stores nothing and says so. A full scan is the exception: its answers replace what the index holds for that commit, because re-analyzing everything is a statement that the stored answers were the stale part.

MCP tools

The MCP endpoint exposes the index as structured tools your agent can call directly.