astashov grasp
The reviewer leaves comments on your code in VS Code. They land in a shared inbox on disk, which you read and answer with the grasp CLI.
One store serves a whole repository family: the main checkout and every linked worktree share the one .grasp/ at the directory holding the shared .git, and each comment is tagged with the working tree it was written against. So pending shows you only the comments for the tree you are in. Items for a sibling worktree belong to another session, and editing them would touch the wrong checkout. You never pass a path. grasp status prints the store and worktree it resolved.
If a command reports there is no store, the repo has not opted in yet. Tell the user to run grasp init instead of creating directories yourself.
Answering review feedback
grasp pending
Then decide, for each item, which kind it is:
- A question ("why did you do it this way?", "is this needed?") wants an explanation. Do not change code. Answer it.
- A request ("pull this into a helper", "rename this") wants the edit. Make the change.
Answer a question properly. The reviewer is asking because the code did not make it obvious, so explain the reasoning, name the trade-off you took, and say what the alternative would have cost. If the honest answer is that they found a real problem, say so and fix it.
Finish every item of both kinds with:
grasp resolve <id> "<your reply>"
The reply is what the reviewer sees in their editor. For a question it is the answer, in markdown, as long as it needs to be. For a request it is one line on what you changed. Resolve as you go instead of batching at the end.
When the reply is long or contains quotes and newlines, write it to a file and pass it with a shell substitution: grasp resolve <id> "$(cat reply.md)".
Items are never hidden from other sessions, so an empty list means there is nothing pending for this worktree, never that someone beat you to it.
An item marked ⚠ claimed ... by "<session name>" is already being handled by that session. Skip it unless the user asked you to take it over, and say which ones you skipped and why. This is a warning rather than a lock, and the user's instruction always wins.
Comments written on a diff
An item marked ⚠ written on the DIFF of commit <sha> was left while reading a diff. That matters for more than line numbers: the question is about the change, not about the finished file. "Why do we add n() here?" is asking about a hunk, and the current file cannot answer it, because it shows the result with no indication of what moved.
Read the change first, exactly as the item tells you:
git show <sha> -- <path> # the change being asked about
git show <sha>:<path> # that file as a whole, if you need more context
Answer in those terms, saying what the change did and why, instead of describing the code as it now stands. When the item also says "lines are on the parent side", the comment sits on the left half of the diff, so its line numbers belong to the parent revision while the change under discussion is still the commit the item names.
When it is a change request rather than a question, the edit still belongs in the working tree. Use the diff to understand what they were looking at, find the corresponding code as it exists now, and say so if it has since moved or already changed.
Comments left under a walkthrough step
An item may show under walkthrough step N. It quotes what that step said, so you have the context even when another session wrote the walkthrough.
If it also shows a commit, the line numbers refer to the file as of that commit, not the working tree. Read that revision before answering:
git show <sha>:<path>
Publishing a walkthrough
When asked to walk the reviewer through your changes, write a JSON file and publish it:
grasp walkthrough tour.json
Order steps the way a senior author would explain the change, with entry points and the most consequential edits first, never alphabetically or by file order. Each step says what changed and why the change was made that way, not what each line does.
{
"title": "Optional overall title",
"steps": [
{
"file": "src/timer.ts",
"startLine": 12,
"endLine": 40,
"title": "Short step title",
"explanation": "Markdown: what changed and why.",
"importance": 5,
"refs": [{ "label": "startTimer", "file": "src/timer.ts", "line": 12 }]
}
]
}
File names inside explanation are plain text and do not become clickable. refs are the only way a mention becomes navigable, so add a ref for every file or symbol the explanation names.
Per-commit mode. To walk through a range of commits, add a commits array, oldest first, from git log --reverse, and tag each step with its commit sha. Group steps by commit, walk commits oldest to newest, and order steps within a commit by importance.
{
"commits": [{ "sha": "<full sha>", "subject": "<first line of message>" }],
"steps": [{ "...": "...", "commit": "<full sha>" }]
}
A commit-tagged step renders inside a diff of that commit against its parent, so its startLine and endLine must be line numbers in the file as of that commit. Read them with git show <sha>:<path>, never from the working tree.
Validation reports every problem at once, so fix them all and re-run the same command.
Other commands
grasp status # store, worktree, pending count, live sessions
grasp doctor # check the install; every gap prints its own fix
grasp sessions # live sessions by name
grasp pending --json # machine-readable form of the same data
grasp pending --all # every worktree's items, for inspection only:
# do NOT act on another worktree's comments
For architecture walkthrough docs, see the archdoc skill.