Tuicr

tuicr Review Workflow

Use tuicr review as the default agent interface. The TUI is where the human reviews code; the CLI is how the agent discovers active sessions, reads user comments, and, only when appropriate, adds agent-authored comments.

Core Rule

First decide which workflow the user is asking for:

1. User-led review of agent-generated changes

   • The user wants to inspect the patch and write comments in tuicr.
   • Your job is to open or find the session, then retrieve the user's comments with tuicr review comments when they say comments are ready. If you are explicitly waiting while the user reviews, poll the same command periodically and look for new comment IDs.
   • Do not add your own review comments, do not preemptively review your own patch, and do not impersonate the user's comments.

2. Agent review of an AI-generated patch

   • The user wants you to understand, critique, or summarize a patch.
   • You may inspect the patch and propose findings.
   • If you can confidently identify this workflow and the target session, add findings directly with tuicr review add and an explicit --username identifying the agent. Ask first when the workflow or session is ambiguous.

If the user's intent is ambiguous, ask which workflow they want.

Attach To A Session

1. Determine the repository directory from the user's request, current working directory, or recent file operations. Ask if it is ambiguous.

2. List persisted sessions:

   tuicr review list --repo /path/to/repo   # checkout + its repo's PR sessions
   tuicr review list --repo owner/repo      # all sessions for a forge repo
   tuicr review list --all                  # every session across all repos

   --repo is a selector: a checkout path also surfaces PR sessions for that checkout's origin repo, and a forge coordinate like owner/repo matches local and PR sessions by owner/repo. Each row carries a kind (local or pr) and a usable slug. Use --all when you don't know the repo.

   [] with exit 0 also means "not a repo root" — a subdirectory returns it too. Pass the root, then --all, before concluding nothing is open.

3. Choose the session:

   • If the CLI clearly reports exactly one relevant active session with "active": true, attach to it.
   • If multiple sessions are active, or the correct session is not clear, ask the user which slug to use. One repo can hold a worktree and a commit-range session at once, and adding to the wrong one exits 0.
   • If the user provided a slug or session JSON path, use it directly.
   • For a PR review, pass the PR slug from the listing (e.g. gh:owner/repo/pr/N) to --session; it is self-contained and needs no --repo.
   • If there is no active session, start or wait for one as described below.
   • Until active-session discovery is formalized as a stable protocol, treat "active": true as a convenience signal. If slug resolution fails, ask the user for the slug or repo path used by the session.

The CLI works even if the agent is not running inside tmux, Zellij, or Herdr, so do not require a multiplexer just to connect to an existing active session.

Start A Session

When the user needs an interactive tuicr pane and no active session exists:

<scope> is -w for uncommitted working-tree changes or -r <revset> for a commit range — always pass one explicitly so the user is never left to pick staged/unstaged/commit-range manually in the TUI.

If more than one multiplexer marker is set, prefer the innermost multiplexer if that is clear; otherwise ask. cmux hosts a Ghostty terminal, so $TERM_PROGRAM reads ghostty inside cmux — check $CMUX_WORKSPACE_ID, not the terminal name.

tuicr supports both git and Jujutsu (jj) repositories, and jj workspaces may have no .git directory at all. Do not pre-check the directory with git rev-parse or refuse to launch because git does not recognize it; always run the wrapper and let it validate the repository.

Wrapper paths are relative to this skill directory:

<skill-directory>/tuicr-wrapper-cmux.sh /path/to/repo -- -w
<skill-directory>/tuicr-wrapper.sh /path/to/repo -- -w
<skill-directory>/tuicr-wrapper-zellij.sh /path/to/repo -- -w
<skill-directory>/tuicr-wrapper-herdr.sh /path/to/repo -- -w

The Herdr wrapper requires jq to read pane IDs and completion results from Herdr's JSON responses.

Every wrapper accepts pass-through tuicr arguments after --, which is how you scope the review instead of leaving the scope selector for the user to fill in — for example -- -w for uncommitted working-tree changes or -- -r <revset> for a commit range. Always pass one of these explicitly when launching a review pane.

If your tool supports command timeouts, use a long timeout, such as 10 minutes, because the tmux, Zellij, and Herdr wrappers wait for the TUI to exit. The cmux wrapper is the exception: it returns as soon as the pane is running and prints the new surface ref between === TUICR SURFACE === markers. Capture that ref — it is how you close the pane later with cmux close-surface --surface <ref>. Once the TUI creates its active session, use tuicr review list --repo /path/to/repo to capture the slug. If your environment cannot run another command while a blocking wrapper is waiting, read the comments after the user exits tuicr.

Reconstruct The Diff

To review a patch yourself, rebuild the diff the user sees. The slug's source segment says which:

Range endpoints are inclusive and printed oldest-first, so <base> without ~1 drops the first commit. Check the file count against the listing row's file_count; a mismatch means every line number you derive will be wrong.