# Readthru

A code review tool that organizes local code changes into logical chapters and points out what to review before you dive into the code. `readthru prep` automatically runs LSP-based graph analysis on the changed symbols: it computes blast radius (external callers at depth 1 and 2), entry paths from call-graph roots down to each changed symbol, and an overall risk level. Chapters can be ordered by real call-graph dependencies, and the review UI surfaces blast-radius chips and a side panel showing per-symbol callers.

Everything happens on your machine — the CLI serves a local review UI from `127.0.0.1`.

## Install

Readthru runs inside your coding agent — **Claude Code or Codex**. Install the CLI, then drop the skill into your agent:

```bash
npm install -g readthru
readthru install-skill
```

> `install-skill` copies the `readthru-chapters` skill into every agent it finds (`~/.claude/skills`, `~/.codex/skills`) — the skill ships inside the package, so there's nothing else to fetch. Requires Node 20+ and one supported agent on your PATH. Reopen your agent afterward so it picks up the skill.

## Quickstart

In your agent, inside any git repository:

```
/readthru-chapters
```

It asks one line about what the change is for, organizes your local changes into reviewable chapters, and opens the review in your browser. Beyond a normal diff review, it flags **what the diff doesn't show** — a datastore with no infra, code that breaks on your declared runtime, an ORM dropped in a rewrite — and tells you how sure it is.

### Background reviews (advanced)

For reviewing a GitLab MR in the background while you keep working, `readthru open` launches a local review queue + history UI. This is the power-user path; the interactive `/readthru-chapters` flow above needs no server.

## Uninstall

```bash
rm -rf ~/.claude/skills/readthru-chapters ~/.codex/skills/readthru-chapters
npm uninstall -g readthru
```

### Options

| Flag | Description |
|------|-------------|
| `--base <ref>` | Base ref to diff against (default: auto-detect main/master) |
| `--compare <ref>` | Compare ref to diff against `--base` |
| `--ref <mode>` | Diff scope: `work` (staged + unstaged + untracked), `staged`, or `unstaged` (default: auto-detect) |
| `--check` | (on `readthru show`) Validate the chapters against the diff for hunk coverage and exit, without launching the UI |

Examples:

```bash
# Review only staged changes
/readthru-chapters --ref staged

# Diff against a specific branch
/readthru-chapters --base feature-a

# Compare two branches
/readthru-chapters main feature
/readthru-chapters main..feature
/readthru-chapters --base main --compare feature
```

### Graph context

`readthru prep` automatically analyzes call graphs for changed symbols using the Language Server Protocol. TypeScript and JavaScript work out of the box — `typescript-language-server` ships bundled with readthru. Go and Python are auto-detected: install `gopls` or `pyright-langserver` on your PATH and they will be used automatically. All other languages fall back to plain review with no degradation.

On a large cold repository the language server indexes the workspace on the first run, so the first request gets a longer warm-up leash. The overall graph-analysis budget defaults to 90s and is configurable via the `READTHRU_GRAPH_TIMEOUT_MS` environment variable (milliseconds; values below 10000 are ignored) — raise it for huge monorepos or lower it in CI.

For deeper investigation of a specific symbol, use the `graph` subcommand:

```bash
readthru graph <symbol>           # callers, callees, entry paths (depth 2 by default)
readthru graph <symbol> --depth 1 # direct callers only
readthru graph <symbol> --json    # machine-readable JSON output
readthru open                     # reopen past reviews (history UI) without importing a new run
```

### `.readthruignore`

Add a `.readthruignore` file to your repo root to exclude files from the diff analysis. Uses `.gitignore`-style patterns, one per line:

```
# Build artifacts
build/**
dist/**

# Generated code
*.generated.ts

# But keep this one
!dist/important.js
```

Ignored files still appear in the "Other changes" chapter so nothing is silently hidden. Comments (`#`), blank lines, and negation patterns (`!`) are supported — last matching pattern wins.

## License

[MIT](LICENSE)
