crit-cli

Files (1)

• SKILL.md

SKILL.md (first lines)

# Crit CLI Reference

> If a plan was just written and the user said "crit" or "review", use the `$crit` skill instead — it covers the full review loop. This skill covers CLI operations like `crit comment`, `crit pull`/`push`, and `crit share`.

Comments have three scopes:

- **Line comments** (`scope: "line"`) — tied to specific lines, stored in `files.<path>.comments`
- **File comments** (`scope: "file"`) — about a file overall, stored in `files.<path>.comments` with `start_line: 0`
- **Review comments** (`scope: "review"`) — general feedback, stored in the top-level `review_comments` array

The review file path is shown by `crit status`.

## Reading comments

When `crit` completes a review round, read **stdout** and follow its instructions. Unresolved comments are often embedded in that prompt as JSON. Check **stderr** for `approved: true` or `approved: false`.

When you need to read comments separately:

```bash
crit comments            # human-readable, unresolved only (default)
crit comments --json     # flat JSON for agents
crit comments --all      # include resolved comments
crit comments --plan <slug>   # plan reviews
crit comments [path]     # explicit review.json or .crit directory
```

Review-level comments are listed first — easy to miss in raw `review.json`. Uses the same review resolution as `crit comment` (`--output`, `--plan`, daemon session).

## Multiple active sessions

When more than one review session matches the current directory and branch, headless commands (`crit comment`, `crit comments`, `crit share`, `crit push`, `crit pull`) refuse to guess. Run `crit status` (or `crit status --json`) to list every active session, then target the intended review with `--session <id>`:

```bash
crit comment --session <id> --author <name> <path>:<line> <body>
crit comment --session <id> --json --file comments.json --author <name>
crit comments --session <id>
crit share --session <id> <file>
crit push --session <id>
crit pull --session <id>
```

The JSON status output exposes the candidates in `sessions`.



Use `read_file` on the path printed by `crit`. Example structure:

```json
{
  "review_comments": [
    {
      "id": "r_f1e2d3",
      "body": "Overall the architecture looks good",
      "scope": "review",
      "author": "User Name",
      "resolved": false,
      "replies": [
        { "id": "rp_b4a5c6", "body": "Thanks, addressed the minor issues", "author": "Grok" }
      ]
    }
  ],
  "files": {
    "path/to/file.go": {
      "comments": [
        {
          "id": "c_a1b2c3",
          "start_line": 5,
          "end_line": 10,
          "body": "Comment text",
          "quote": "the specific words selected",
          "anchor": "The sessions table needs a complete rewrite...",
          "author": "User Name",
          "resolved": false,
          "replies": [ ... ]
        }
      ]
    }
  }
}
```

Field rules:
- `resolved`: `false` or **missing** both mean unresolved. Only `true` means resolved.
- `quote` (optional): the exact text the reviewer highlighted.
- `anchor` (line comments): the full text of the commented lines at the time the comment was placed. Use the anchor to locate content after edits.
- `drifted: true`: content was removed or heavily rewritten — treat line numbers as approximate.
- Unresolved comments may have `replies` — read them before acting.

<important if="you are authoring or replying to comments via crit comment">

Use `run_terminal_cmd` with the following patterns. Always pass `--author 'Grok'`.

```bash
# Review-level (general feedback)
crit comment --author 'Grok' 'Overall feedback here'

# File-level (whole file, no line numbers)
crit comment --author 'Grok' path/to/file.md 'The whole file needs X'

# Line (single line or range)
crit comment --author 'Grok' path/to/file.go:42 'Missing null check'
crit comment --author 'Grok' path/to/file.go:50-55 'Extract to helper'

# DOM pin (live review or HTML preview). File:line is rejected there.
crit comment --author 'Grok' --selector '<css>' '<body>'
crit comment --author 'Grok' --selector '<css>' --route <path> '<body>'

# Reply to an existing comment
crit comment --reply-to <id> --author 'Grok' 'Fixed — added the helper and tests'
```

Hard rules:
- **Always pass `--author 'Grok'`**.
- **Always single-quote the body** in the shell command (double quotes break on backticks, `$`, etc.).
- Line numbers are 1-indexed file lines on disk (not diff lines).
- Reply bodies support full markdown.
- Only pass `--resolve` when the user explicitly asks you to.
- **Live reviews and HTML preview** do not take `<path>:<line>`. Pin with `--selector <css>`. `--route` is the page path (default `/` for live, `/preview-content` for preview). In `--json`, use `"selector"` and `"route"`.
</important>

From tomasz-tomczyk/crit, MIT.

More from tomasz-tomczyk/crit