Parley

Parley is a terminal-first review tool for local Git diffs with structured, line-anchored discussion threads and optional AI-assisted replies/refactors.

It is designed for iterative review loops where code changes are generated or assisted by AI, but review state and thread resolution remain explicit and human-controlled.

Primary docs site: https://parley.cloudflavor.io

Why Parley

• Review threads are anchored to specific diff lines, not loose notes.
• Thread status is explicit: open, pending, addressed.
• Review state exists for compatibility, but TUI completion is thread-based.
• TUI workflow is keyboard-first and optimized for rapid navigation.
• AI operations integrate into the same thread model instead of bypassing review state.

Core Concepts

Diff source vs review session

Parley separates:

• Diff source: what code you are reviewing (working tree, --commit, or --base/--head range)
• Review session: repo-scoped state under the active Parley store (review name, threaded comments, status history)

By default, Parley stores repo-scoped state under $HOME/.config/parley/repos/<repo-name>-<hash>/. If the repository already has a .parley/ directory, Parley uses it instead. To opt a repository into local checked-in or shared state explicitly, run:

parley config use-local

Thread lifecycle

• New comment -> open
• Reply by original thread author -> open
• Reply by different author (including AI in normal flows) -> pending
• Explicit resolution by original thread author -> addressed

Review lifecycle

• Any open thread keeps review work active.
• pending means waiting for human review.
• addressed means the individual thread is resolved.

Installation and Build

Prerequisites:

• Rust toolchain
• Git repository as working directory
• Terminal with TUI support

Install the parley binary:

cargo install parley-cli

Build locally:

cargo build --release

Run from source:

cargo run -- tui

Quickstart

Create and start a review session:

parley review create my-review
parley review start my-review

Open TUI on current working tree changes:

parley tui --review my-review

Disable mouse capture for SSH/terminal compatibility:

parley tui --review my-review --no-mouse

Review historical diffs:

parley tui --review my-review --commit HEAD~2
parley tui --review my-review --base main --head feature/my-branch
parley tui --review my-review --base v0.1.0
# everything after HEAD~2 (exclude that commit)
parley tui --review my-review --base HEAD~2 --head HEAD
# everything after and including HEAD~2
parley tui --review my-review --base HEAD~2^ --head HEAD

Review the repository root as files instead of a git diff:

parley tui --review my-review --root

Root mode lazy-loads file contents. JSON files are displayed with pretty formatting, and Markdown files are rendered into readable text rows.

CLI Reference

Top-level commands:

• parley tui
• parley review <subcommand>
• parley mcp

Common review subcommands:

• create <name>
• start <name> (shortcut for set-state <name> under_review)
• list
• show <name> [--json]
• set-state <name> <open|under_review>
• add-comment ...
• add-reply ...
• mark-addressed ...
• mark-open ...
• run-ai-session ...

TUI Workflow and Key Controls

Thread actions:

• m or c: create thread on selected line
• r: reply to selected thread
• a: mark addressed
• o: mark open
• f: force-address selected thread
• N / P: next/previous thread

Review state actions:

• s: set open
• w: set under_review
• Thread completion is handled with a/o.

AI actions:

• x: AI refactor selected thread
• X: AI reply selected thread
• A: AI refactor review
• K: cancel active AI run
• H: per-file AI logs
• L: global AI activity/session list

Useful navigation:

• h/l: previous/next file
• j/k: line up/down
• /query: search
• R: refresh diff and review data
• ?: in-app help

AI Session Behavior

Providers:

• codex
• claude
• opencode

Modes:

• refactor
• reply

Eligibility summary:

• refactor targets open and pending threads.
• reply targets open and pending by default.
• Explicit selected-thread AI actions target the selected thread regardless of status.
• Provider startup/config errors and stderr are surfaced in the per-file AI logs popup.

MCP Integration

Run MCP server over stdio:

parley mcp

Parley exposes JSON-RPC MCP tooling for review automation, including:

• list_reviews
• get_review
• list_open_comments
• add_reply
• mark_comment_addressed
• mark_comment_open
• set_review_state
• run_ai_session

Local State and Configuration

Parley stores review data in the active store. By default that is:

$HOME/.config/parley/repos/<repo-name>-<hash>/

If .parley/ already exists in the repository, Parley uses it as the active store. Run parley config use-local to create it explicitly for repositories that should keep Parley state in the project.

By default, .parley/ is excluded from review diff file lists when local storage is active. To include it again, set:

ignore_parley_dir = false

in:

<active-store>/config.toml

Documentation

Main docs website:

• parley.cloudflavor.io

Project docs in this repository:

• Overview
• Quickstart
• Review Workflow
• Keybindings
• MCP Integration

Docs site source and deployment tooling:

• ui-docs/README.md

License

Apache-2.0