---
slug: "amartinr-pi-ts-prelint"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/amartinr/pi-ts-prelint@master/README.md"
repo: "https://github.com/amartinr/pi-ts-prelint"
source_file: "README.md"
branch: "master"
---
# pi-ts-prelint

> ⚠️ **Experimental — untested hypothesis**
>
> This extension is based on an unproven idea: that catching TypeScript compilation errors early improves code quality and saves tokens. **No data supports this claim yet.** It is in early development. APIs, configuration, and behavior may change without notice.

## What it does

Intercepts `write` and `edit` tool calls on `.ts`/`.tsx` files and runs `tsc --noEmit` to check for compilation errors. If compilation fails, the change **is still applied** (so the model sees the modified file), but the structured error messages are injected into the tool result so the model can fix them in the next turn.

This is an experiment. We don't yet know whether it actually helps.

## How it works

The extension intercepts `write` and `edit` tool calls for TypeScript files:

1. Intercepts `write` and `edit` tool calls for TypeScript files.
2. Writes the candidate content to a temp file (prefixed with `~`) to calculate the diff with the existing file.
3. Computes the change complexity (modified lines / total lines) to decide whether linting is worth the cost.
4. If the change is large enough, runs `tsc --noEmit` on the **real file** (already modified by the original tool) using a minimal temp tsconfig that copies compiler options from the project.
5. If compilation fails, stores the errors and lets the change proceed (the file is modified).
6. After the tool executes, injects the compilation errors into the tool result — optionally including a diff of what changed, so the model can correlate errors with specific modifications.
7. Cleans up the temp file.

The model always sees the modified file state, avoiding the confusion that arises when edits are blocked and the model tries to re-apply changes on stale file content.

## Limitations

- Only covers `.ts` and `.tsx` files.
- Requires `npx` and a local `typescript` installation in the project.
- If `tsc` throws unexpectedly, the change is allowed to proceed as a fail-safe.
- Compilation errors are not blocking — the model must notice and fix them on its own.
- Only checks the **affected file**, not the entire project — cross-file dependency errors may be missed.

## Configuration

Configuration is loaded from two sources, merged with project-level taking priority:

| Scope | Path |
|-------|------|
| Global | `~/.pi/agent/extensions/pi-ts-prelint/config.json` |
| Project | `.pi/pi-ts-prelint.json` |

### Config file format

```json
{
  "changeComplexity": {
    "minAbsoluteLines": 15,
    "minPercentage": 10
  },
  "diffThreshold": {
    "minErrorsToShow": 3,
    "maxAbsoluteLines": 50,
    "maxPercentage": 50
  }
}
```

### Options

| Option | Default | Description |
|--------|---------|-------------|
| `changeComplexity.minAbsoluteLines` | `15` | Minimum modified lines to trigger linting (AND with percentage) |
| `changeComplexity.minPercentage` | `10` | Minimum modified % of existing file to trigger linting |
| `diffThreshold.minErrorsToShow` | `3` | Minimum compilation errors to include diff in error message |
| `diffThreshold.maxAbsoluteLines` | `50` | Maximum modified lines to include diff in error message |
| `diffThreshold.maxPercentage` | `50` | Maximum modified % of new file to include diff in error message |

### Examples

**Skip linting on smaller edits (project-level):**

`.pi/pi-ts-prelint.json`

```json
{
  "changeComplexity": {
    "minAbsoluteLines": 3,
    "minPercentage": 2
  }
}
```

**Show diff only for 2+ errors (lower threshold):**

`.pi/pi-ts-prelint.json`

```json
{
  "diffThreshold": {
    "minErrorsToShow": 2
  }
}
```

### Merging behavior

Global config is loaded first, then project config is deep-merged on top. You only need to specify the keys you want to override:

`~/.pi/agent/extensions/pi-ts-prelint/config.json` (global defaults)

```json
{
  "changeComplexity": {
    "minAbsoluteLines": 15,
    "minPercentage": 10
  }
}
```

`.pi/pi-ts-prelint.json` (project overrides only)

```json
{
  "changeComplexity": {
    "minAbsoluteLines": 3
  }
}
```

Result: `minAbsoluteLines=3`, `minPercentage=10` (unchanged from global).

## Installation

> ⚠️ This is an experimental extension based on an untested hypothesis. Use at your own discretion.

### Global (all projects)

Copy the extension to your global extensions directory:

```bash
mkdir -p ~/.pi/agent/extensions/pi-ts-prelint
# The extension is loaded automatically as a pi package
```

### Project-local

Add to your `.pi/settings.json`:

```json
{
  "packages": ["npm:pi-ts-prelint"]
}
```

Or place a `.pi/pi-ts-prelint.json` in your project root to customize thresholds.

## Design

The full design document, including the hypothesis and implementation details, is available in [docs/DESIGN.md](https://github.com/amartinr/pi-ts-prelint/blob/HEAD/docs/DESIGN.md).

## License

MIT