On this page
#Quickstart
#Install
#Homebrew (macOS and Linux)
brew tap cloudflavor/tap
brew install cloudflavor/tap/parley
#Cargo
cargo install parley-cli
#Build from source
cargo build --release
#What Parley is actually doing
Parley separates two things:
- a diff source you are reviewing
- a review session stored in the active Parley store
The diff source is the code you see in the TUI:
- the current working tree by default
- a specific commit with
--commit - a base/head range with
--baseand--head - the current repository root with
--root
The review session is the structured review state Parley keeps locally:
- named reviews such as
my-review - line-anchored comment threads
- thread statuses:
open,pending,addressed - review state exists for compatibility, but TUI completion is thread-based
#Storage location
Parley first checks for a .parley/ directory in the current repository. If it exists, that local directory is the active store.
If .parley/ does not exist, Parley stores repo-scoped state under:
$HOME/.config/parley/repos/<repo-name>-<hash>/
The repo name keeps the global store readable, and the hash prevents collisions between repositories with the same directory name.
Parley does not create .parley/ in the repository during normal review commands. To explicitly opt a repository into local storage, run:
parley config use-local
To see the active store path for the current repository, run:
parley config path
That matters because comments are not just free-form notes. Each thread is attached to a file path and line reference, and replies update the parent thread status.
The review session is the comment context. Switching reviews changes which comments and review state are visible, while the selected diff source stays as-is.
#Create a review session
parley review create my-review
parley review start my-review
review create creates the local session. review start moves it into under_review, but the moment you add an open thread, the review state automatically becomes open again.
#Open the TUI on your current changes
parley tui --review my-review
--review is required, and the review must already exist. Create it first with review create.
If your terminal or SSH session mishandles mouse reporting, disable mouse capture:
parley tui --review my-review --no-mouse
If you are in a repository with multiple worktrees, start Parley against a specific one:
parley tui --review my-review --worktree feature/my-branch
The TUI never creates or guesses a startup review. Review context is explicit so comments are always written under the intended review.
#Open a specific commit or range
By default, the TUI opens the current working tree diff. You can also open historical revisions:
parley tui --commit HEAD~2
parley tui --base origin/trunk --head feature/my-branch
parley tui --base v0.1.0
# everything after HEAD~2 (exclude that commit)
parley tui --base HEAD~2 --head HEAD
# everything after and including HEAD~2
parley tui --base HEAD~2^ --head HEAD
--commit <rev>shows that commit against its first parent.--base <rev>defaultsheadtoHEAD.--base <rev> --head <rev>shows an explicit range.- Use
--base <rev> --head HEADto review everything after<rev>. - Use
--base <rev>^ --head HEADto include<rev>itself in that cumulative range.
Refresh (R) keeps using the same source while the TUI session stays open, and AI prompt context follows that same diff source.
You can also switch to a specific commit from inside the TUI:
- Press
Ctrl+kto open the command palette. - Choose
Open Commit Picker. - Type part of a commit message, short SHA, or full SHA to filter the recent commit list.
- Use
↑/↓,j/k,PgUp/PgDn,Home, orEndto select a commit. - Press
Enterto apply it.
The picker changes only Parley's active diff source. It does not run git checkout or modify the working tree.
To switch comment context without changing the diff:
- Press
Ctrl+kto open the command palette. - Choose
Open Review Picker. - Filter by review name or state.
- Press
Enterto apply the selected review.
The TUI reloads comments from the selected review and keeps the current diff source.
To create a new review from inside the TUI, use Ctrl+k and Create Review. The new review becomes active immediately, and later comments are written to that review's directory. If the review picker has no matches for the typed name, pressing Enter opens the same create-review prompt with that name.
Current limitation:
- reopening the review later does not restore the revision source automatically; pass the same flags again.
#Review the current root directory
Use root mode when you want to review the repository as files, not as a git diff:
parley tui --review my-review --root
--review is still required, and the review must already exist. Root mode does not create or guess a review.
Root mode includes tracked files and untracked files that are not ignored by gitignore rules. It skips .git/, .parley/, and worktrees/. Each file is displayed as context lines, so comments attach to the file's current line numbers.
Startup in root mode lazy-loads file content. The file tree appears first, load progress is shown while data hydrates, and individual files load when selected or opened from search. Root mode opens raw source by default. Press D / Shift+d or use command palette Toggle Root JSON/Markdown Rendering to switch .json files into pretty-printed JSON and Markdown files into readable rendered text rows.
#The core workflow
Think of the normal flow like this:
- Open a diff.
- Move to a changed line.
- Create a thread on that line.
- Reply until the issue is resolved.
- Mark the thread addressed.
- When each issue is resolved, mark its thread addressed.
#Example: review one issue end to end
Say you open a diff and find a risky change in src/lib.rs.
- Move to the line with
j/k,PgUp/PgDn, or search. - Press
morcto open a draft on that line. - Write a comment such as:
This branch drops the error context. Can we keep the original cause here?
- Save with
Ctrl+s.
That creates a thread anchored to the selected diff line, and the thread starts as open.
If someone else replies, for example:
I pushed a fix and kept the original error chain.
the thread becomes pending.
If the original commenter replies again, the thread goes back to open.
When the original commenter is satisfied, they mark it addressed.
Only the original commenter can normally change a thread to open, pending, or addressed. That is enforced by the review model.
#Example: use AI on a thread
xruns AI refactor on the selected unresolved threadXruns AI reply on the selected threadAruns AI refactor across all eligible threads in the review
Typical pattern:
- Leave a thread
open. - Press
xon that thread. - AI adds a reply to the thread.
- Because AI is a different author, the thread becomes
pending. - You inspect the code changes and either reopen the thread or mark it addressed.
Starting an AI run opens and follows the current file's AI logs so provider startup/config errors and stream output are visible.
#Customize AI task prompts
Parley always builds thread context from the selected comment, replies, target file, diff hunk, and referenced files. You can replace the final task instructions appended to that context with markdown files configured in $HOME/.config/parley/config.toml.
Use one shared prompt for all AI modes:
[ai]
prompt_path = "prompts/parley-ai.md"
Or use mode-specific prompts:
[ai]
reply_prompt_path = "prompts/parley-reply.md"
refactor_prompt_path = "prompts/parley-refactor.md"
Supported providers: codex, claude, opencode, pi.
Mode-specific paths take precedence over prompt_path. Relative paths are resolved from the repository root where Parley is started. If a configured prompt file cannot be read, the AI session fails before invoking the provider.
#Core controls
#Navigation
h/lorLeft/Right: previous or next filej/korUp/Down: move line cursor down or upPgUp/PgDn: page scrollCtrl+u/Ctrl+d: half-page scrollg/Shift+G: jump to first or last linez: toggle content fullscreenShift+Z: center active line in viewport
#Search and jump
:<line>: go to line/<text>: search within the current filen/p: next or previous search hitCtrl+g: open codebase search popup- File and codebase search use
rgwhen available and fall back togrep - Codebase search respects gitignore rules and updates results while you type
Enteror mouse click on a result opens the matched file and line
#Threads
morc: create thread on selected linev: start visual line selectionShift+V: clear visual line selection- With visual line selection active, move to the end of the range and press
morcto open the comment box at the bottom of that range r: reply to selected threadN/P: jump next or previous thread[/]: select previous or next thread in current fileCtrl+t: open the global thread selectore: toggle selected thread expansionCtrl+e: toggle selected thread anchor context expansion (collapsed by default)a/o/f: addressed/open/force-address selected threadu: re-anchor selected thread to the currently selected diff line
#File references in comments
- Type
@inside the comment or reply box to open file matching. - Use
EnterorTabon a file match to open that file in the active diff pane and switch into line-picker mode. - The comment editor explicitly tells you to select a diff line before the reference is confirmed.
- In line-picker mode, use
↑/↓,j/k,PgUp/PgDn, org/Shift+Gto move the diff cursor, thenEnterorTabto insert@path:line. - If mouse support is enabled, clicking a diff line during line-picker mode inserts that line immediately.
- After inserting the reference, Parley restores the file, pane, and diff line where the draft started.
Esccancels the line picker and leaves the bare@pathreference in the comment buffer.
#Comment editor
Esc: close comment boxCtrl+s: save comment or replyCtrl+p: toggle markdown preview- Arrow keys or
Ctrl+p/n/b/f: move cursor (up/down/left/right) Home/End: move to start/end of lineCtrl+a/Ctrl+e: move to start/end of lineCtrl+k: kill to end of lineEnter: insert newlineTab: insert 4 spacesBackspace/Delete: delete characterAlt+b: move backward one whitespace-delimited wordAlt+d: delete forward through the next whitespace-delimited word- Long comment drafts wrap inside the editor, preserving whole words when possible
#Review state
s: set reviewopenw: set reviewunder_review
Review state mostly follows thread state:
- any
openthread means the review isopen - no
openthreads means the review isunder_review - thread
addressedis the completion signal used in the TUI
#AI and tools
x: AI refactor selected threadX: AI reply selected threadA: AI refactor full reviewi: cycle AI provider (codex,claude,opencode,pi)I: toggle AI transport (acporcli) for providers that support bothK: cancel current AI runH: toggle per-file AI logs popupL: toggle the global AI activity pane- AI activity
Enter: jump to the selected file/session logs - AI activity
O/o: open AI log in external pager - AI progress popup
O/o: open AI log in external pager Ctrl+k: open command palette- Command palette
Search Codebase: open live repository search - Command palette
Show AI Activity: open the global AI session activity pane - Command palette
Toggle AI Transport: switch between ACP and CLI for the active provider - Command palette
Open Thread Selector: search and jump across all review threads - Command palette
Show Git File Heatmap: scan git history on demand and show file hotspots - Command palette
Open Commit Picker: switch the active diff source to a recent commit - Command palette
Open Review Picker: switch the active review context - Command palette
Create Review: create a new review context and switch to it M: open the git file heatmap- Heatmap
s: cycle sort by churn, added, removed, commits, net growth, net shrink, volatility, or path - Heatmap
Shift+S: reverse the active heatmap sort Ctrl+f: focus files filter inputShift+F: cycle file filter modeShift+O: open file viewerCtrl+w: open worktree pickerShift+U: edit user namet: open theme pickerT: toggle light/dark theme variantb: toggle thread navigatorCtrl+v: toggle split viewS: toggle side-by-side diff layoutTab: switch active diff pane (when split view enabled)</>: resize files paneEnter: collapse or expand the active file groupShift+C: collapse all visible file groupsCtrl+z: suspend Parley (runfgto resume)?: open in-app docs/help overlay
By default, agent providers use persistent transports instead of spawning a one-shot CLI prompt for every thread. OpenCode uses ACP with opencode acp, Codex uses codex-acp, Claude uses claude-agent-acp, and Pi uses pi --mode rpc --no-session. Pi is RPC, not ACP. Set a provider's transport = "cli" in $HOME/.config/parley/config.toml only when you explicitly need the old one-shot behavior. If ACP is configured with a non-ACP command such as codex exec or opencode run, Parley fails fast and shows the config error in the AI logs.
The default $HOME/.config/parley/config.toml AI shape is:
[ai]
timeout_seconds = 120
default_provider = "opencode"
default_transport = "acp"
[ai.codex]
transport = "acp"
client = "codex-acp"
args = []
[ai.claude]
transport = "acp"
client = "claude-agent-acp"
args = []
[ai.opencode]
transport = "acp"
client = "opencode"
args = ["acp"]
model_arg = "-m"
[ai.pi]
transport = "pi_rpc"
client = "pi"
args = ["--mode", "rpc", "--no-session"]
For one-shot CLI mode, configure the provider explicitly:
[ai.codex]
transport = "cli"
client = "codex"
args = ["exec"]
The TUI can also switch transport at runtime with I. The active selection is stored as ai.default_transport, which accepts only the generic acp and cli choices. Parley uses built-in CLI profiles for codex, claude, and opencode when that value is cli. Pi keeps using provider-specific pi_rpc.
Parley stores AI output as per-file session logs in memory while the TUI is open. Starting an AI run opens/follows the current file logs. H shows transcripts for the current file, and L shows a global activity index for running and recent sessions. Review comments are separate durable state; AI output is added to a thread only when the AI review flow persists a reply.
The thread selector is separate from the per-file thread navigator. Ctrl+t searches all threads in the active review and jumps to the selected file/thread with Enter. In root mode, comments whose original anchor text no longer matches are still displayed at their stored line reference so pending threads do not disappear after refactors.
#Split diff layout
Ctrl+v: toggle split view- Command palette
Toggle Split View: toggle split view from the command list S: toggle side-by-side diff layoutTab: switch active diff pane- Added and removed lines use tinted backgrounds to make changed regions easier to scan
#A realistic first session
parley review create parser-cleanup
parley review start parser-cleanup
parley tui --review parser-cleanup
Inside the TUI:
- move through changed files with
h/l - move inside the diff with
j/k - press
con a changed line to leave a thread - press
ron that thread to reply later - press
Rafter editing code in another terminal - press
awhen the original reviewer considers the issue resolved - press
Ctrl+zto suspend Parley; runfgto resume
For a historical review:
parley tui --review parser-cleanup --base origin/trunk --head feature/parser-cleanup
That lets you keep one named review session while pointing the TUI at an explicit base/head diff.
#Config
Parley reads configuration from $HOME/.config/parley/config.toml.
By default, review-owned state is stored under $HOME/.config/parley/repos/<repo-name>-<hash>/reviews/<review-name>/. If .parley/ exists in the repository, Parley uses .parley/reviews/<review-name>/ instead.
Each review directory contains:
review.json
logs/tui.log
All comments, replies, thread status, review status, and TUI logs for that review stay under this directory.
Older flat review files in reviews/<review-name>.json are still loaded.
By default, Parley ignores .parley/ files when local storage is active so that review metadata and logs do not show up in the file list.
To include .parley/ in the diff again, set:
ignore_parley_dir = false
#Which status to set before AI
- For review-wide
refactor(A): target threads must beopenorpending. - For selected-thread AI (
xorX): the selected thread is sent unless it isaddressed.
#Refresh after edits
Inside TUI:
R
This reloads review metadata and the active diff source.
- For the normal workflow, that means the current working tree diff.
- If you opened the TUI with
--commitor--base/--head, refresh keeps using that same historical source.