Study a codebase or review a diff in your terminal, keep notes and comments on exact lines, and keep coding agents inside the same loop instead of bouncing between disconnected chats and scratch notes.

When I study an unfamiliar codebase or review a change, I struggle with the constant back-and-forth between the source and a separate explanation. A card-style companion for guidance, notes, and review comments, anchored directly to the code, makes that flow much easier to hold onto.

Asking follow-up questions has the same problem. By the time I want help from an agent, I still have to gather the exact source location and package the right context, and once the agent replies the answer usually lives somewhere else. copanion removes that busywork: keep notes beside the code while you read, export the exact question threads that still need help, write the agent replies back into the same packet, then continue or close the thread inside the TUI.

copanion is a Rust CLI/TUI for persistent code-study and change-review packets with an explicit agent loop.

It opens tracked files or Git diffs in a terminal UI, injects note cards and comment threads directly below the lines they explain, and lets you stage follow-up threads in place. Notes stay local. Only open threads that still need an agent reply are exported back to the clipboard or stdout.

Each project gets one canonical packet stored under Copanion's user data directory, usually ~/.local/share/copanion/packets/. copanion discovers the project root, maps it to that packet path, and reopens the same packet every time you come back to the project.

If a packet has no tracked files yet, copanion opens directly into the fuzzy file picker so you can start from inside the TUI.

copanion is built around a repeatable study/review loop with agents in the middle, not outside the tool:

1. Read code in the TUI and attach notes or open questions to exact lines.
2. Export only the question threads that still need an agent reply.
3. Ask an agent to answer those threads and write the answers back into the same packet.
4. Reopen Copanion and keep reading with the full thread visible inline beside the source.
5. Continue the thread, close it, or reopen it later if new confusion appears.

The important point is that the thread stays durable. The root question, the agent answer, and later follow-up questions all live in one place and remain attached to the same code anchor.

• Inline notes and question threads - Attach notes or threaded follow-up questions to exact lines or selected ranges.
• Persistent per-project packets - Save and reopen the same packet across runs from anywhere inside the project.
• Fuzzy file picker - Add tracked files from inside the TUI instead of preparing them up front.
• Searchable annotations - Jump through saved notes and threads with a fuzzy search prompt.
• Question-thread export - Export only the open threads that still need an agent reply.
• Agent write-back - Apply structured agent answers back into the packet so reopened threads show the conversation inline.
• Thread lifecycle control - Continue, close, or reopen a question thread from inside the TUI.
• Clipboard or stdout output - Copy exports to the clipboard by default, or print them with --stdout.
• Canonical system storage - Keep packet files in Copanion's data directory instead of scattering them through project trees.
• Built-in themes - Pick a theme from the CLI or config file.

cargo install copanion

git clone https://github.com/inmzhang/copanion.git
cd copanion
cargo install --path .

This repo ships the same Copanion workflow for both Codex and Claude Code.

To install the skill for Codex:

cp -r "$(pwd)/.agents/skills/copanion" ~/.codex/skills/copanion

To install the skill for Claude Code:

# Option 1:
cp -r "$(pwd)/.claude/skill" ~/.claude/skills/copanion

# Option 2:
claude skill add "$(pwd)/.claude/skill"

Run copanion in the repository you want to study or review:

cd /path/to/your/repo
copanion

That opens the canonical packet for the current project. If the packet is empty, copanion starts in the fuzzy file picker.

To browse recent commits or uncommitted changes instead of the tracked-source view, start in diff mode:

copanion --diff

Diff mode is Git-backed. It opens a commit selector first, lets you choose either the working tree or a contiguous commit range, and then shows a unified patch view with the same Copanion packet loaded beside note/comment counts. It borrows heavily from tuicr.

Examples:

copanion src/main.rs src/lib.rs
copanion --print-packet-path
copanion --diff
copanion --export --stdout
copanion --theme gruvbox-dark

Typical agent-assisted flow:

cd /path/to/your/repo
copanion
# read code, add notes, stage question threads
copanion --export --stdout
# ask an agent to answer the exported threads
copanion --apply-agent-response replies.json
# reopen the TUI and continue or close the thread
copanion

Set a default theme in:

• Linux/macOS: $XDG_CONFIG_HOME/copanion/config.toml (default: ~/.config/copanion/config.toml)
• Windows: %APPDATA%\copanion\config.toml

Example:

theme = "gruvbox-dark"

Theme resolution precedence:

1. --theme <THEME>
2. theme in the config file above
3. built-in default (gruvbox-dark)

Only theme is currently recognized. Unknown keys are ignored with a startup warning.

These work in both source mode and diff mode. The nouns change by mode: source mode works with question threads, while diff mode treats the same thread keys as review comments.

Source mode uses the tracked-file browser and question-thread wording.

Start diff mode with copanion --diff. In this mode, a creates a review comment or reply, c closes a comment thread, and exports include the selected commits or working-tree scope plus your review comments.

Review comments and notes in diff mode attach to added lines, unchanged context lines, or expanded hidden context. Deleted-only rows do not have a durable source anchor, so they are not directly annotatable yet.