Skip to main content
Glama
README.md
# grasp

**Review what your coding agent did, decision by decision.**

AI agents write code faster than people can review it. grasp shows you **what the software does now
compared with before** (real outputs, not the agent's summary), walks you through each decision with
**Approve / Reject**, warns you what the change could break, and sends rejections back to the agent.

Install in Claude Code (no Go needed):

```
/plugin marketplace add arsaljamal/grasp
/plugin install grasp@grasp
```

Work as usual, then type `/grasp:review`. For a pull request without an agent session, see [PR mode](#reviewing-a-pull-request-no-agent-session).

![A decision in grasp: before and after, run for real](docs/img/review.png)

| Start here: guess, then see; and what it could break | Reject with a note for the agent |
|---|---|
| ![What changed for users](docs/img/what-changed.png) | ![Rejecting a decision](docs/img/reject.png) |

<details><summary><b>Watch</b> mode: the session as a reel, one animated scene per step</summary>

![Watch mode](docs/img/watch.gif)
</details>

## How it works

```
 you ask ──► agent decides ──► agent changes files
    │             │                    │
    └──── grasp reads the session (hooks + transcript) ────┐
                  │                                         │
     agent calls record_decision (MCP)            every edit is linked to
     "what, why, files, alternatives, risk"       the decision that explains it
                  │                                         │
                  └────────► review page ◄──────────────────┘
                     approve · reject · comment
                                │
     agent calls get_review_feedback (MCP) and follows it next time
```

- **Show, don't tell.** The agent gives a short command that demonstrates a change (for example: start the
  server, send an empty title, print the response). grasp runs it on the code from before the session and on
  the code now, and shows both outputs side by side. The agent cannot fake them: grasp runs them itself.
  Decisions with no demonstration say so.
- **Guess first, then see.** On the start card the new output stays hidden until you think about what it
  should be. Then you say whether it matched. Anything that surprised you is flagged before you approve it.
- **What it could break, checked by grasp, not the agent.** It flags existing tests the agent changed or
  weakened, and finds code elsewhere in the project that uses a function the agent changed but was not
  updated (or a deleted function that is still called).
- **Decisions, not lines.** Each decision shows *why*, the options the agent rejected, the risk it saw, and
  the exact changes that carry it out.
- **Nothing hides.** Edits that no decision explains are grouped as *changes with no recorded reason*.
  Files a decision names but never touches are flagged as *unverified claims*.
- **Works without cooperation too.** If the agent records no decisions, grasp groups edits by what the agent
  said just before making them, and marks those groups as inferred.
- **One thing at a time.** Each decision is a card; the code and the full reasoning stay hidden until you
  ask for them. **Watch** plays the session like a reel: story bars on top, one animated scene per step
  (the request typing out, decision cards flipping in, changed lines sliding in, commands running), with speed
  control and tap-to-skip.
- **Closes the loop.** Rejections and comments become instructions the agent reads through
  `get_review_feedback` at the start of its next task.

## Quick start (Claude Code)

The plugin (above) downloads the right grasp binary on first use and checks its checksum. Then work as
usual and type `/grasp:review` when you want to review.

Or install the command yourself and set up one project:

```sh
go install github.com/arsaljamal/grasp/cmd/grasp@latest
cd your-project
grasp init      # adds the MCP server (.mcp.json), hooks (.claude/settings.json) and a CLAUDE.md note
claude          # work as usual
grasp serve     # open http://127.0.0.1:7080 and review; it updates live while the agent works
```

Already have sessions? `grasp import --latest` loads the newest Claude Code session for this folder, or pass
transcript files: `grasp import ~/.claude/projects/<project>/<session>.jsonl`.

## Reviewing a pull request (no agent session)

Most changes reach reviewers as a pull request, not as a live agent session. Check out the branch and run:

```sh
grasp pr -base origin/main -title "PR title" -body "PR description" -explain
grasp serve
```

Without `-explain`, each commit becomes a decision (its message is the reason) and you still get the full
"What it could break" check. With `-explain`, Claude Code reads the diff (as files, with no write access),
records the real design decisions, says where to look first, and demonstrates behavior with `show_behavior`,
which runs on the base commit and on the branch. Every claim is linked to the actual diff, and test files
are grouped with the code they test.

## Commands

| Command | What it does |
|---|---|
| `grasp init` | Set up Claude Code in this project. Merges into existing config files, never overwrites them. |
| `grasp serve [-addr]` | The review page, on 127.0.0.1:7080 by default. |
| `grasp pr` | Load a branch or pull request from git; `-explain` adds Claude's decisions and examples. |
| `grasp import` | Load Claude Code transcripts. |
| `grasp feedback` | Print reviewer feedback as Markdown instructions (the same text the agent gets). |
| `grasp mcp` | The MCP server the agent starts: `record_decision`, `show_behavior`, `get_review_feedback`. |
| `grasp hook` | Claude Code hook entry point. Always exits 0, so it never blocks the agent. |

State lives in `.grasp/` in your project: parsed sessions, `reviews.json` (commit it to share verdicts with
your team) and `decisions.jsonl` (decisions from agents grasp has no transcript for).

## Safety

`show_behavior` runs shell commands the agent writes, from your project folder, so treat it like giving the
agent shell access: approve it per call, or allow it only where you would allow the agent's own shell. The
"before" side runs in a temporary git worktree of the commit the session started on; your working files are
never touched. Each run is stopped after 90 seconds, along with anything it started in the background.

## Other agents

Any MCP-capable agent can call `record_decision` and `get_review_feedback`; those decisions show up in an
*agent log* session. Full timelines (edits, commands, Watch mode) currently come from Claude Code transcripts.
Adapters for other agents' logs are welcome.

## Status

Early, and built in the open. Tested end to end with Claude Code on a sample service
([docs/example.md](docs/example.md)). Ideas next: checking decisions against a written spec, a GitHub PR
check that blocks merges with rejected decisions, and team views across many sessions.

## License

MIT

TDQS

A4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool occupies a distinct phase of the review loop: record_decision writes, show_behavior demonstrates evidence, get_review_feedback reads reviewer verdicts. No two tools could plausibly be selected for the same intent.

Naming Consistency5/5

All three names follow a strict verb_noun snake_case pattern (get_review_feedback, record_decision, show_behavior). The verbs accurately signal direction (read/write/demonstrate).

Tool Count4/5

Three tools is minimal but each maps to a necessary step in the submit-review-revise workflow, so nothing feels padded. It sits at the low end of the comfortable range, leaving little room for auxiliary operations.

Completeness4/5

The core loop (record decision, demonstrate behavior, collect feedback) is fully covered. Minor gaps exist around inspecting previously recorded decisions or withdrawing/amending one, but the workflow can proceed without those.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues