# 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

```ts
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

```text
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?

```text
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**:

| Metric      | Programmatic | Raw text |
| ----------- | -----------: | -------: |
| Pass rate   |     **100%** |      88% |
| Avg. tokens |     **133k** |     560k |
| Avg. calls  |      **4.4** |       11 |
| Avg. time   |      **14s** |      79s |
| Avg. cost   |   **$0.096** |   $0.280 |

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`](docs/mcp-hands-on-eval.md) for the methodology and [`docs/battle-test-report.md`](docs/battle-test-report.md) for engine testing.

## Install

```bash
npm install
npm run build
npm test
```

## Architecture

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

See [`docs/api.md`](docs/api.md) and [`docs/architecture-decision.md`](docs/architecture-decision.md).

## License

MIT