
grasp
io.github.arsaljamal/grasp
Review what your coding agent did, decision by decision, with real before/after behavior.
Documentation
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. To see it first on a sample session, type /grasp:demo, or without
Claude Code: go run github.com/arsaljamal/grasp/cmd/grasp@latest demo. For a pull request without an agent session, see PR mode.


| Start here: guess, then see; and what it could break | Reject with a note for the agent |
|---|---|
![]() | ![]() |
Watch mode: the session as a reel, one animated scene per step

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_feedbackat 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:
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:
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 demo | Open the review page on two sample Claude Code sessions. Nothing to set up, nothing is kept. |
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). 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
https://github.com/arsaljamal/grasp/releases/download/v0.1.1/grasp-0.1.1.mcpb# mcpb: https://github.com/arsaljamal/grasp/releases/download/v0.1.1/grasp-0.1.1.mcpb
