Programmatic

A structural programming interface for source code, designed for AI coding agents.

Today, agents edit code as text: search, read files, make edits, re-check, and hope they didn't miss a reference.

Programmatic gives agents structural code intelligence, turning operations like "rename this symbol" into semantic operations instead of string manipulation.

Status: Phase 1. Programmatic currently provides a TypeScript/TSX structural engine and an MCP server for AI coding agents.

What it does

import { openProject } from "@programmatic/typescript";

const project = openProject("./example-project");

project.inspectFile("src/UserCard.tsx");
project.findSymbol("UserCard");
project.findReferences("UserCard");
project.renameSymbol("UserCard", "ProfileCard");
project.check();
project.save();

MCP tools

list_files
inspect_file
find_symbol
find_symbols
find_references
rename_symbol
check

An agent can use these directly instead of reconstructing code structure through grep, file reads, and manual edits.

Why structural?

Traditional

Read → Search → Inspect → Edit → Re-read → Fix → Type-check


Programmatic

Agent → Structural operation → TypeScript Language Service

Programmatic uses the TypeScript Language Service for semantic resolution and reference finding, then applies minimal text edits to preserve the original source.

Renames understand scopes, imports, exports, JSX, and references while leaving comments, strings, and unrelated identifiers untouched.

Benchmark

Initial evaluation against text-based Claude Code workflows on Zod v3.23.8:

For these rename tasks, the raw workflow used approximately 4.2× more tokens, 2.5× more tool calls, 5.6× more time, and 2.9× more cost.

These are initial results from a single repository and model.

See docs/mcp-hands-on-eval.md for the methodology and docs/battle-test-report.md for engine testing.

Install

npm install
npm run build
npm test

Architecture

AI coding agent
       ↓
Programmatic MCP
       ↓
Programmatic API
       ↓
TypeScript Language Service
       ↓
TypeScript / TSX

See docs/api.md and docs/architecture-decision.md.

License

MIT