Reviews
Review a task's change locally, push it, open and merge its pull request, and clean up after.
One of the hardest parts of working with agentic development tools is keeping a handle on the massive amount of code they can produce.
Komrad aims to make reviewing easy though it’s review panel.
With it, you can comment on changes and reply to the agent implementing a feature. You can also see the specific edit the agent made in response to a comment and even see and reply to comments from a colleague on your changes.
Local reviews#
While a change is still taking shape, iterating with the agent directly is often faster than pushing to a forge like GitHub or GitLab.
Komrad supports this with local reviews. You read the task’s diff, leave comments on its lines, and edit it yourself, and the writer answers in the same view. That keeps feedback loops quick and saves CI runs on work that isn’t ready yet.
Komrad’s local review model resembles Gerrit’s code review. You step through the change in snapshots, and each snapshot holds the code as it stood when it was reviewed.
Opening a review#
Hover the task, open its menu with space, and pick review with r. The main view shows everything the task’s branch changed since it left the base.
The sidebar holds a tree of the files the change touches, and the main view holds the diff and the conversation.
When the task has a pull request, the sidebar shows the forge’s review decision, who commented there, and the pull request’s title. Press o on the title to read the description.
The writer’s pane stays beside the diff while the writer runs. To give the diff more room, open the review’s menu and press v for the view menu. There, w wraps long lines, and the boxes under the entries choose whether the sidebar and the chat, which is the writer’s pane, are shown beside the diff. Press tab to reach the boxes. Komrad keeps your choice when you open the next review.
Moving through the diff#
The cursor in the diff moves the way Vim’s normal mode does. Press ]t and [t to move between the threads the diff shows. The filter on the comments tab chooses which threads show. A count moves that many threads, so 2]t skips one. Press enter on a thread to read it in the comments tab, and Esc to move between the diff and the comments.
The review keeps a jump list, like Vim’s. gd, gr, gi, gg, G and the searches each leave the place you jumped from in it. Press ctrl+o to go back through those places, into a file those keys opened as well, and ctrl+i to go forward again. A reload empties the list.
These keys work whether vim_mode is on or off. That setting covers typing in fields, and the diff never types.
Asking a language server about code#
Press gd on a name to go to its definition, gr to list every reference to it, and gi to list its implementations. K reads what the language server says about it. A language server runs only while a review of its checkout is open.
When the language server names several places, they fill the quickfix list at the bottom of the diff, with a preview of the place under its cursor. Press enter to go to that place with the list still showing, and Q to move back into it. Inside the list, Esc or Q closes it.
komrad runs a language server only when you write a file for it in language_servers.dir. The file’s name is the language server’s name. komrad ships a default config for each language server nvim-lspconfig knows, so an empty gopls.toml runs gopls with its default config. A field in the file replaces the default config’s field, and env, settings and init_options merge into it key by key.
gopls’s definition starts it in any checkout with a .git. Set its root markers to start it only in Go modules:
root_markers = ["go.mod", "go.work"]
env = { GOMEMLIMIT = "2GiB" }
A language server nvim-lspconfig doesn’t know needs cmd, filetypes and root_markers. Filetypes are Neovim’s names, such as sh or typescriptreact. komrad names each file’s filetype the way Neovim does, and highlights it with the grammar nvim-treesitter uses for that filetype. A root marker can be a pattern, such as *.sln. This tsc.toml runs TypeScript 7’s language server for TypeScript and JavaScript:
cmd = ["tsc", "--lsp", "--stdio"]
filetypes = ["typescript", "typescriptreact", "javascript", "javascriptreact"]
root_markers = ["tsconfig.json", "jsconfig.json", "package.json"]
env = { GOMEMLIMIT = "3GiB" }
komrad sets no memory limit on a language server. Set each one’s own limit in its file, such as GOMEMLIMIT for gopls and tsc. Two files can’t read the same filetype. komrad reads the directory again on each request, so a change applies the next time a language server starts.
The sidebar lists each language server over the checkout under the file tree, and says whether it is starting, ready or failed. A failed one shows the first line of why it failed. Move the cursor onto one and press space for its menu. Its menu opens the language server’s log on the logs screen of the agent the review is open on, and restarts it after you change its file. Each agent’s logs list every language server that has run over its task’s checkout, under language servers.
Leaving comments#
Open the review’s menu with space on a line with no thread and press c to comment on it.
A thread in the comments tab lists what you can do with it under the conversation. Press c there to reply, or r to resolve the thread or reopen it. On a thread in the diff, open the review’s menu and press c for the same entries.
The comment goes to the task’s writer the moment you press enter, as mail that carries the comment whole. The writer reads it when it next reads its mail, so when a comment cannot wait, stop the writer with Escape in its pane beside the diff.
The thread says where your comment stands. It is released once it is sent, read once the writer has read it, and answered once the writer has replied. A reply marked addressed carries a snapshot of the change it made.
Each comment goes out with the lines it was written on and the code around them, so the writer can find the spot even after the file has moved.
The writer answers in your threads. To see exactly what it changed in answer to a comment, open the thread and press a. You resolve a thread once its answer satisfies you, and a reply never resolves or reopens it.
Snapshots#
Each comment you write is pinned to the snapshot you read, and the diff stays on that snapshot while the writer moves on. Open the menu, then the view menu with v, and press r to catch up with the newest work. The top of the diff names the snapshot on screen.
An answer, or the diff a comment was written against, takes replies but not new comments when it ends before the newest snapshot, because new comments go on the newest snapshot.
Reviews from agents#
The writer can ask for a reviewer when it thinks its work is ready, and you can start one yourself from the task’s menu. A task can hold more than one reviewer at once, up to reviewer.max_per_task. A reviewer reviews the same way you do, leaving threads on the task’s diff and releasing a review the writer answers.
Choosing which threads show#
The comments tab’s filter row chooses which threads show, in the comments tab and in the diff. All shows every thread, unresolved hides the resolved ones, and mine shows only the threads you opened. Press F to step along the row, or click a stop. A thread you resolve while unresolved is chosen stays on screen until the cursor leaves it. Komrad keeps your choice on every review until it restarts.
Shipping the work#
Once you’re happy with the change locally, it goes to a forge, like GitHub or GitLab.
Pushing and opening the pull request#
The writer commits, pushes its branch and opens the pull request itself, so the simplest path is to tell it to. You can also push from the task’s git menu: open the task’s menu, press g, then p. Komrad says how many commits go up before it pushes. The review’s menu holds push and the pull request’s entries in its forge menu under f, so you can push or merge without leaving the diff.
Komrad links a pull request to a task by its branch, so a pull request opened from the task’s branch shows up on the task’s row on its own. The git menu nests a forge menu under f for everything that acts on the pull request, and o there opens it in your browser.
To share a line of the change, open the review’s menu on it, press f for the forge menu, and press l. Komrad copies the line’s link on the forge, pinned to the pull request’s newest commit. A line the writer changed since its last push has no link until it pushes again.
Following the pull request#
While any agent on a task is live, komrad follows its pull request. It notices when checks pass or fail, when it is approved, and when it is merged, and shows that as a symbol on the task’s row. Some of those changes also tell the writer, such as checks failing or the branch conflicting with its base.
Komrad reads a repository every five seconds when something there is likely to change soon, such as checks still running, a branch that just moved, or a pull request komrad just wrote to. It reads every other repository once a minute. When the forge says little of the hour’s budget is left, komrad drops every repository on that host to once a minute until the budget comes back.
Syncing comments from Github or Gitlab#
Komrad also reads the review comments on each followed pull request or merge request, drafts included, once a minute. Each one is copied into the task’s review as a thread of its own. Press ]t to move to the next thread and open it. A reply or an edit on the forge lands in the same thread. Resolving a thread on the forge resolves it here, and resolving it here resolves it on the forge.
Comments from someone who can push to the repository reach the writer on their own. Komrad holds comments from anyone else until you accept them or reply in their thread, so nothing from a stranger reaches the writer before you see it.
The writer answers forge comments in the review, never on the forge itself. On a forge thread, press C to reply on the forge where anyone can read it.
To start a new conversation on the forge, open the review’s menu on a line, press f for the forge menu, and press c. Komrad posts your comment on that line of the pull request, as you. A line the writer changed since its last push can’t take a comment until it pushes again.
Merging#
When the pull request is ready, open the task’s git menu and press f for the forge menu. You can merge and leave the task where it is, merge and archive the task, merge, archive and delete the task, choosing in the same form what the delete takes, have the forge merge it on its own once checks and reviews pass, or merge and then rebase the task’s worktree onto the base so the writer can start its next change.
Cleaning up#
A merged task can be archived, which stops its agents and keeps everything else, or deleted, which also removes its worktree. A task’s life covers both. Merge and archive does the first step for you.
Credentials#
Where the token lives#
The database holds only which forge and which account. The token itself sits in a file only your user can read, and never shows up in logs. The GitHub CLI and your SSH keys work the same way.
Agents never hold a credential of their own, and tokens are never typed into a pane, so they can’t leak into a transcript. Komrad hands each tool the credential when the tool runs.
On your laptop, gh gets a token from the App when [github_app] is set, and otherwise uses the login gh already has. Git uses whatever credential you already have. On a remote engine, git and gh hold a placeholder, and the control plane adds the person’s GitHub login, as komrad’s engine describes.
For GitLab, glab gets the token of the connection for the checkout’s host, in a config that names that host alone, so the token is never sent anywhere else. With no connection for that host, it uses the login glab already has. Git reaches GitLab through komrad gitlab credential once you add a line for each host.
git config --global credential.https://gitlab.example.com.helper '!komrad gitlab credential'