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-service searches with direct lookups against a compiled service index.

The three-layer index

Carrick maintains a single index per project, compiled 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 API calls in the edited file, cross-service counterparts, broken contracts, and (once per session) calling functions and type-dependent operations
Read hook	Agent	When a TypeScript file is first opened in a session	File dependencies: function callers, type-dependent operations, and counterpart routes and calls in other services
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-service 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.

A scan builds the index in six steps:

1. SWC parses each TypeScript file into an AST.
2. A static-analysis pass extracts function exports, GraphQL schemas and operations, and WebSocket event contracts, and selects the files with candidate routes or calls.
3. A model reads each selected file and extracts its routes, mounts and calls.
4. The type sidecar resolves request and response types against the TypeScript compiler.
5. A second model pass writes the intent description for each function.
6. The project index is stored in DynamoDB and S3, and refreshes on each rescan, main scan or carrick index run.

After the initial scan, Carrick rescans a repository when you push to its default branch, and you can rescan it from the dashboard. In a repository with the optional Carrick GitHub Actions workflow, the Action updates the index automatically on every push to main.

Related

• Quickstart installs the GitHub App and builds the first index.
• Building the index covers rescans, scanning from your own machine, and the CI workflow.
• What Carrick covers details framework extraction, protocols, and architectural limits.
• MCP tools is the complete reference for hosted agent tools.