How to Add Comments in Tuicr: Line, File, and Review-Level Annotations

Press c to add a line comment, C (Shift+c) for a file comment, or type :comment for a review-level note, then press Enter to save to your review session.

Tuicr is a terminal-based code review tool that lets you annotate diffs with contextual comments without leaving the command line. In the agavra/tuicr repository, comments are first-class citizens that persist in structured review sessions stored in ~/.local/share/tuicr/reviews/. Whether you're reviewing a specific line, an entire file, or the overall change, Tuicr provides keyboard-driven workflows to capture your feedback efficiently.

Understanding Tuicr's Three Comment Types

Tuicr supports three distinct comment scopes, each triggered by different keys and stored with specific targeting metadata:

• Line comments: Anchored to a specific line in the diff, triggered by c in Normal mode, and stored as CommentTarget::Line { path, line, side }
• File comments: Attached to an entire file, triggered by C (Shift+c), and stored as CommentTarget::File { path }
• Review-level comments: General feedback not tied to specific code, accessed via command mode, and stored as CommentTarget::Review

Each type creates an AddCommentRequest that the system routes through ReviewStore::add_comment in src/review_store.rs.

Adding Line Comments with the c Key

When you press c in Normal mode with your cursor on a diff line, Tuicr initiates the line comment workflow.

The key binding is defined in src/input/keybindings.rs, where c maps to Action::AddLineComment (lines 41-44). The handler in src/handler.rs (lines 51-58) captures this action and calls app.enter_comment_mode, passing the current cursor position obtained via app.get_line_at_cursor().

In src/app/comments.rs, the enter_comment_mode function (lines 72-83) switches self.input_mode to InputMode::Comment, clears the comment buffer, and records the target with the specific line metadata.

The UI renders a boxed input area via format_comment_input_lines in src/ui/comment_panel.rs (lines 12-22), showing a [NOTE] header and line range information. The cursor position inside the box is communicated back to the terminal via CommentCursorInfo (lines 88-98).

Adding File-Level Comments with Shift+C

For broader feedback covering an entire file, press C (Shift+c) while viewing any file panel.

This triggers Action::AddFileComment from src/input/keybindings.rs, handled in src/handler.rs by calling enter_comment_mode with CommentTarget::File { path }. The comment box appears at the top of the file panel rather than inline with specific code, allowing you to provide context about the file's overall structure or approach.

Adding Review-Level Comments via Command Mode

To add general feedback not tied to specific files or lines, enter command mode with : and type comment (or add from the CLI).

This creates a CommentTarget::Review variant, storing the comment at the session level. The UI displays an unanchored comment box in the diff view, useful for high-level architectural observations or summary remarks that span multiple files.

Saving and Persisting Comments

When you press Enter (triggering SubmitInput), the save_comment function in src/app/comments.rs (lines 110-170) executes:

1. Validates the buffer isn't empty
2. Builds an AddCommentRequest containing the target and content
3. Calls add_comment_to_session(&mut self.session, request)

The ReviewStore::add_comment method in src/review_store.rs (lines 72-85) persists the comment to the JSON review session file in ~/.local/share/tuicr/reviews/. The comment immediately appears in both the diff view and the Comment Navigator sidebar (accessible via ;c by default).

Adding Comments from the Command Line

Tuicr supports non-interactive comment addition through its CLI, using the same underlying storage layer as the TUI:

tuicr review add \
  --repo . \
  --type note \
  --target line \
  --path src/main.rs \
  --line 42 \
  --content "Explain this calculation"

The CLI parses arguments into an AddCommentRequest and calls the same ReviewStore::add_comment method used by the UI, guaranteeing identical behavior between TUI and command-line workflows.

Editing and Deleting Existing Comments

To modify an existing comment, navigate to it in Normal mode and press c, then use i to edit or A to append (vim-style). The handler in src/handler.rs (lines 62-65) dispatches Action::EditComment to edit_comment_at_cursor, which re-enters comment mode with the existing content pre-filled in the buffer.

For deletion, use the comment navigator (accessed via ;c by default) and select the delete action, or use the CLI command tuicr review delete.

Summary

• Press c on any diff line to add an inline comment anchored to that specific line via Action::AddLineComment
• Press C (Shift+c) to attach a comment to an entire file using CommentTarget::File
• Type :comment in command mode for review-level feedback using CommentTarget::Review
• Press Enter to persist comments via save_comment in src/app/comments.rs
• All comments store in ~/.local/share/tuicr/reviews/ through ReviewStore::add_comment in src/review_store.rs
• Edit comments by pressing c then i on existing comment lines to trigger edit_comment_at_cursor
• CLI parity: Use tuicr review add with --target flags for non-interactive scripting

Frequently Asked Questions

What keyboard shortcut adds a comment to a specific line in Tuicr?

Press c in Normal mode while your cursor is on the target line. This triggers Action::AddLineComment from src/input/keybindings.rs and opens an inline comment box anchored to that line via CommentTarget::Line. The system captures your cursor position through app.get_line_at_cursor() before entering comment mode.

Where does Tuicr store comments after I save them?

Comments persist to JSON files in ~/.local/share/tuicr/reviews/ through the add_comment_to_session function in src/review_store.rs (lines 72-85). Each comment is stored as a Comment struct defined in src/model/comment.rs, containing content, author, optional commit ID, and anchoring metadata that preserves the relationship to specific lines or files.

Can I add comments to Tuicr without using the interactive TUI?

Yes. Use the CLI command tuicr review add with flags like --target line, --path, and --line. This constructs an AddCommentRequest identical to the TUI workflow and calls the same ReviewStore::add_comment method, ensuring consistent storage whether you use the terminal interface or command-line scripting.

How do I edit an existing comment in Tuicr?

Navigate to the comment line in Normal mode and press c, then press i to enter insert mode (or A to jump to end-of-line). The handler dispatches Action::EditComment in src/handler.rs (lines 62-65), which calls edit_comment_at_cursor to pre-fill the comment buffer with existing content before re-entering comment mode via enter_comment_mode in src/app/comments.rs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}