How Carrick works

The problem

In modern TypeScript organisations, AI coding agents write an increasing proportion of application code. Their most common mistakes are rarely local syntax errors:

• Rebuilding existing utilities: An agent implements a helper that already exists elsewhere in the organisation under a different name.
• Trusting stale contract copies: An agent relies on a drift-prone local copy or manual mock of another service’s interface.
• Breaking downstream consumers: An agent modifies a route or response shape without awareness of which external services consume it.

Having every repository cloned locally does not eliminate these issues, because a local branch is not main and coding agents rarely grep entire multi-repository workspaces. Carrick replaces manual cross-repo searches with direct lookups against a compiled service index.

The three-layer index

Carrick maintains a single index per project, compiled continuously from the main branch of each connected repository. The index contains three layers for every function and endpoint:

1. Structure: Routes, outbound client calls, router mount hierarchies, and normalised paths.
2. Types: Request and response types resolved by the TypeScript compiler (tsc), which also evaluates whether producer and consumer interfaces match.
3. Intent: Semantic descriptions of function behaviour, enabling queries like “where do we deduplicate users by email” to find relevant code regardless of function naming.

Delivery surfaces

Carrick surfaces the index at four points, plus a line when each session opens:

Surface	Recipient	Trigger	Information delivered
MCP server	Agent	When it asks	Intent search, callers, endpoint types, compatibility checks, and service graphs
Post-edit hook	Agent	Same turn as an edit, without asking	Routes and calls in the edited file, counterparts in other repos on disk, and broken contracts
Session-start line	Agent	When a session opens	Index freshness and pending scan status
Editor extension	Engineer	On file open and save	Problems panel diagnostics, cross-repo go to definition, code lenses, and status bar boundary
PR comment	Reviewer	On each pull request	Contract drift and breaking schema changes introduced by the branch

Four task skills that carrick init installs in your workspace (carrick-census, carrick-drift, carrick-impact, and carrick-reuse) guide agents through common architectural and contract questions.

The MCP server queries across your entire organisation, including repositories that are not checked out on your machine. In contrast, local hooks and the editor extension read the downloaded index for local files directly without invoking cloud models at edit time. Carrick coordinates local channels so hooks and the language server never produce duplicate notifications.

Cloud inference and architecture

Cloud inference is central to Carrick. It classifies complex call relationships that the static scanner cannot resolve deterministically and generates semantic intent descriptions. There is no local-only index.

Carrick is composed of four modular components:

• Scanner (carrick/, public, Rust): AST extraction, routing analysis, call resolution, and diagnostic findings.
• Type sidecar (carrick/src/sidecar): Captures TypeScript types using ts-morph and executes tsc compiler passes to judge contract compatibility.
• Cloud (hosted by Carrick): the inference service, an ingest pipeline that unifies repositories into a project graph, the MCP server, and the web dashboard.
• CLI (carrick on npm): Commands for workspace setup (init), indexing (index), status monitoring (status), and file verification (check), bundled with local agent hooks and the Language Server Protocol (LSP) server.

After the initial scan, the Carrick GitHub Action updates the index automatically on every push to main.

Related

• Quickstart installs Carrick and builds the first index.
• Building the index covers the configuration your agent writes, the first scan, and the CI workflow.
• What Carrick covers details framework extraction, protocols, and architectural limits.
• MCP tools is the complete reference for hosted agent tools.