perspica

perspica [options] [oldfile [newfile]]

perspica is a local semantic diff for reviewing code. It parses both sides of a change with tree-sitter, works out what actually changed (a rename, a new parameter, a moved function, a real logic change), and sets aside mechanical noise such as reformatting, comment-only edits, rename-only lines, unchanged moves, and generated files. It also points at what a line diff hides: references to names that no longer exist, calls that were not updated for a new signature, and code the change left unused.Semantic analysis covers TypeScript and JavaScript (including TSX and JSX), Python, Rust, Go, Java, and C. Other files still appear as ordinary line diffs. Nothing is sent off the machine unless you ask for LLM analysis with -s. An optional LLM groups changes by intent, rates risk, and writes a summary. When the change came from your own Claude Code or Codex session, perspica can show the prompts that produced it.With no arguments it reviews the current branch against its merge-base with `origin/HEAD`, `main`, or `master`, including uncommitted and untracked files. --pr uses the gh CLI to fetch a GitHub pull request. The default terminal format is tty; --web serves a viewer on 127.0.0.1 (default port 7890). Analyses are cached under `.git/perspica/`.

OLDFILE NEWFILE

Compare two files. Omit both to review the current git work.

Override language detection.

Output format: tty (default), json, or web.

Shorthand for --format json.

Open results in a local browser viewer.

Port for the web viewer (default: 7890; the next free port is used if taken).

Do not open a browser tab in web mode.

Disable colored output.

Show mechanical hunks (formatting, renames, moves) in full in the terminal.

Diff staged changes.

Diff the working tree against HEAD, or a commit range (`a..b`, `a...b`, or a ref).

Review a GitHub pull request by number (uses the gh CLI).

Review the current branch against its merge-base with BASE (default: `origin/HEAD`, `main`, or `master`). This is what perspica does with no arguments.

Group changes by intent, with risk and a summary, using an LLM. Sends the change list and changed code, never whole files.

Thorough analysis: the LLM may first read definitions and small files from the changed files. Slower. Implies -s.

LLM API key. Prefer setting it in the environment.

With --api-key: anthropic (default) or openai. ollama needs no key and uses a local model.

Model to use instead of the provider's default.

Do not read Claude Code or Codex sessions behind your change.

Run the LLM analysis again even if a saved one matches this diff.

Print help.

Print version.

Semantic classification is only for the listed languages; everything else is a line diff. --pr needs a working gh login. LLM analysis is optional and, except with Ollama, sends the classified change list and changed code to a provider. Agent session files under `~/.claude/projects` and `~/.codex/sessions` are read only for your own uncommitted work or commits authored with your git identity. The web viewer binds to 127.0.0.1 and refuses other hosts.

perspica is a Rust CLI published on GitHub in 2026 under the MIT License. Install with `cargo install perspica` or a release binary.

git-diff(1), git(1), delta(1), difft(1), gh(1), cargo(1)

Source code