Repository avatar
Other Tools
v0.1.1
active

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.

grasp in 50 seconds: Claude makes a change, you guess and see the real before/after, grasp flags what else it could break, you reject with a note, and Claude fixes it on its next task

Watch as video (MP4)

A decision in grasp: before and after, run for real

Start here: guess, then see; and what it could breakReject with a note for the agent
What changed for usersRejecting a decision
Watch mode: the session as a reel, one animated scene per step

Watch mode

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:

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

CommandWhat it does
grasp demoOpen the review page on two sample Claude Code sessions. Nothing to set up, nothing is kept.
grasp initSet 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 prLoad a branch or pull request from git; -explain adds Claude's decisions and examples.
grasp importLoad Claude Code transcripts.
grasp feedbackPrint reviewer feedback as Markdown instructions (the same text the agent gets).
grasp mcpThe MCP server the agent starts: record_decision, show_behavior, get_review_feedback.
grasp hookClaude 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

MCPB
https://github.com/arsaljamal/grasp/releases/download/v0.1.1/grasp-0.1.1.mcpb
Install Command
# mcpb: https://github.com/arsaljamal/grasp/releases/download/v0.1.1/grasp-0.1.1.mcpb