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

> Learn how to add comments in Tuicr with line, file, and review-level annotations. Master Tuicr comments using keyboard shortcuts and commands to enhance your code review workflow.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: how-to-guide
- Published: 2026-08-01

---

**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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/input/keybindings.rs), where `c` maps to `Action::AddLineComment` (lines 41-44). The handler in [`src/handler.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/input/keybindings.rs), handled in [`src/handler.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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:

```bash
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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/app/comments.rs)
- **All comments** store in `~/.local/share/tuicr/reviews/` through `ReviewStore::add_comment` in [`src/review_store.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/review_store.rs) (lines 72-85). Each comment is stored as a `Comment` struct defined in [`src/model/comment.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/app/comments.rs).