live-pr

README

╻  ╻╻ ╻┏━╸   ┏━┓┏━┓
┃  ┃┃┏┛┣╸ ╺━╸┣━┛┣┳┛
┗━╸╹┗┛ ┗━╸   ╹  ╹┗╸

live-pr

Living pull request for LLM-assisted development.

A GitHub PR records only the compressed final conclusion. The actual iteration — pivots, discarded approaches, why each decision was made — happens locally with the coding agent and is thrown away.

live-pr keeps that timeline alive: agents and humans append decision / pivot / note records during development, you review the branch like a GitHub PR in a local TUI, and at the end the timeline ships as the body of a real pull request.

Features

• Decision timeline — append-only records from humans and agents, editable from the TUI and CLI
• GitHub-PR-style TUI — PR list with views/filters/stacks, and a detail screen with the conversation beside a review pane
• Full conversation sync — PR description, comments, submitted reviews (colored verdicts), inline review comments, and lifecycle activity
• Comment from the TUI — post, edit, and delete GitHub conversation comments; edit the PR description
• Review from the TUI — inline comments plus a verdict (comment / approve / request changes) submitted together
• Pluggable review pane — embedded Neovim CodeDiff, delta, or built-in git diff; switch with --diff
• Local-first context — checked-out PR file diffs stay on the pushed head; unpushed commits and working-tree changes remain available in the commit picker
• PR LIST / LOCAL / LIVE / REMOTE status line — distinguishes the navigator, PR-less local work, the checkout's PR, and other fetched PRs; dirty/ahead/behind stay separate
• Live PR monitoring — LIVE checkouts poll lightweight head, state, draft, and CI metadata without replacing the local review
• PR export — live-pr pr publish creates or updates the GitHub PR with the timeline as its body
• Mouse support — wheel scrolling per pane, click to select or open a PR, view tabs, and popup options

Status

Alpha, and versioned 0.x. Releases go out several times a day; keybindings, configuration keys, and on-disk state can change between 0.x releases without a deprecation period. v1.0 is the point where those three stop moving without a migration path — a goal, not a date.

Install

With Homebrew (macOS):

brew install shonenm/live-pr/live-pr

Or download a platform archive from GitHub Releases:

version=$(curl -fsSI https://github.com/shonenm/live-pr/releases/latest | tr -d '\r' | sed -n 's#.*/tag/##p')
case $(uname -m) in x86_64) arch=amd64 ;; *) arch=$(uname -m) ;; esac
asset="live-pr_${version#v}_$(uname -s)_${arch}.tar.gz"
tmp=$(mktemp -d)
curl -fL "https://github.com/shonenm/live-pr/releases/download/$version/$asset" -o "$tmp/$asset"
tar -xzf "$tmp/$asset" -C "$tmp"
mkdir -p "$HOME/.local/bin"
install -m755 "$tmp/live-pr" "$HOME/.local/bin/live-pr"

Or with Go:

go install github.com/shonenm/live-pr@latest

Requirements: Git. An authenticated GitHub CLI (gh) for GitHub browsing, commenting, reviewing, and publishing. Neovim CodeDiff and delta are optional; raw git diff is built in.

Platforms: macOS and Linux are the supported targets — macOS is what live-pr is developed on, and the full test suite (plus go vet and the race detector) runs on Linux in CI. The macOS and Windows CI jobs only compile everything and run the terminal-embedding tests. Releases include a Windows archive, but Windows is build-verified only: nobody exercises the TUI there, so treat it as untested.

Quick start

live-pr demo             # disposable demo, no GitHub resources touched
live-pr                  # open the TUI for the current repository and branch
live-pr --diff=delta     # pick the review pane: git, delta, codediff, codereview, or a command
live-pr pr publish       # push and create/update the GitHub PR from the timeline

Press ? in the TUI for keybindings, or see docs/keybindings.md.

Configuration

~/.config/live-pr/config.toml, overridden per-repo by .live-pr.toml:

theme = "primer-dark"        # primer-dark (default) | primer-light | nord | catppuccin-mocha
summarize_command = ""       # summary backend: transcript on stdin, summary on stdout ("" = claude -p)

[diff]
command = 'nvim -c "CodeDiff --inline $LIVE_PR_RANGE"'  # embedded reviewer ("" = built-in git diff)
display = "delta --color-only"                          # static diff filter
split_ratio = 20                                        # conversation : review width (detail screen)
min_pane_width = 60

[list]
split_ratio = 50             # list : preview width on the PR list screen (default 45)

[merge]
methods = ["squash", "merge", "rebase"] # display order; first is selected by default

[ci]
command = ""                 # append command stdout to the hierarchical CI checks view
# provider = "woodpecker"     # use woodpecker-cli and its existing context/keyring
# Available to command: LIVE_PR_REPO, LIVE_PR_PR_NUMBER, LIVE_PR_PR_URL, LIVE_PR_HEAD_SHA

[accessibility]
monochrome = false           # remove ANSI color/style output
ascii = false                # replace UI arrows, status glyphs, spinners, and borders with ASCII

merge.methods must contain merge, squash, and rebase exactly once.

See docs/diff-tool-integration.md for reviewer details and docs/local-review-modes.md for LOCAL/LIVE/REMOTE behavior and data ownership.

diff.command, diff.commit_command, ci.command, and summarize_command are run through a shell, and .live-pr.toml is read from the repository you are viewing — so a repository you clone can run a command of its author's choosing when you start live-pr in it, the same exposure as Vim's exrc. Review the per-repo configuration of repositories you do not trust; SECURITY.md covers the trust boundaries in full.

The Woodpecker provider normally reuses the active woodpecker-cli context. Headless hosts can configure authentication only in the global config (repository configuration cannot override these fields):

[ci]
server = "https://ci.example.com"
# Optional when the CLI is managed by mise and is not directly on PATH:
cli_command = ["mise", "exec", "--", "woodpecker-cli"]
token_command = ["op", "read", "op://Personal/Woodpecker/credential"]

The token command is executed directly without a shell. Its single-line stdout is passed only to the child CLI as WOODPECKER_TOKEN and is not persisted.

Agent Skill

Teach coding agents when to record decisions:

gh skill install shonenm/live-pr live-pr --agent claude-code --scope user

The binary carries the matching skill version (live-pr skill path). A Claude Code Stop hook (live-pr init --hooks) can summarize sessions into the timeline automatically.

More

• docs/keybindings.md — full key reference
• docs/development.md — CLI reference, building, debugging
• docs/prior-art.md — how live-pr relates to neighboring tools
• CONTRIBUTING.md — how to report bugs and send pull requests
• SECURITY.md — reporting a vulnerability, and what live-pr runs on your machine

License

MIT