Stop reopening your IDE just to review what your coding agent changed.
Run Codex or Claude Code beside a live review workspace in the same terminal. Inspect every changed file, read the surrounding code, run checks, select exact lines, and send that context straight back to the agent.
Stvena.Demo.Video.mp4
Built in Go. Designed for terminal workflows with Codex and Claude Code. Early-stage software: interfaces and local storage formats may change.
If Stvena saves you from the "open the IDE just for the diff" loop, consider starring the repository.
- See the work as it happens. Review changes since the agent started, or inspect branch, staged, unstaged, and new changes. A retained session timeline lets you reopen the stable edit batches Stvena actually observed.
- Read beyond the diff. Browse the project tree, open complete files, and switch between unified and side-by-side views with syntax highlighting.
- Give the agent precise context. Select code with the mouse or keyboard, collect snippets across files, and paste an assembled draft into the agent. You decide when to submit it.
- Run multiple agents at once. Keep independent Codex and Claude Code terminals running, switch between them, and review their combined changes in one workspace.
- Accept or reject from your editor. The Stvena Live extension puts ✓ Accept and ✗ Reject above every change block in the ordinary working file, with Explorer badges for what still needs review. Never a native diff tab.
- Follow saved edits in your editor. The experimental Stvena Live extension lists captured activity and mirrors Stvena's current review range in the real source file—never a native IDE diff. Editor selections can open TUI review or enter Stvena's context tray.
- Keep track of your review. Pin a captured version, mark files and hunks reviewed, and see when a reviewed change has changed again.
- Accept or reject what the agent wrote. Accepting is the review mark you already use. Rejecting queues the change, reverts exactly those lines when the agent finishes its turn, and hands the agent a message saying what you turned down so it does not write it again.
- Check the code you are looking at. Run a command in a temporary checkout of a captured version, inspect logs, and jump from recognized failures to source.
- Stage deliberately. Stage or unstage files and hunks with confirmation.
You need the git command, an interactive terminal, and your chosen agent CLI
installed and authenticated. Your project does not have to be a Git repository:
a folder that was never git inited is captured into Stvena's own directory
instead, without writing anything into your source tree. Stvena uses Unix PTYs and process groups; macOS and Linux are
the intended platforms. Native Windows is not supported.
With Homebrew installed, run:
brew install nccapo/stvena/stvena
stvena --versionThis taps nccapo/homebrew-stvena,
trusts only the stvena formula, and installs a prebuilt binary verified against
the release's SHA-256 checksum. No Go installation is required. The formula
supports Apple Silicon and Intel Macs, plus ARM64 and amd64 Linux systems.
Install and authenticate Codex or Claude Code separately before launching Stvena.
The tap tracks stable releases by default. To upgrade or uninstall:
brew upgrade stvena
brew uninstall stvenaPreview releases are not installed automatically. The editor integrations need Stvena 0.4.0 or later; see Follow reads and edits in VS Code.
If you previously used install.sh and Homebrew reports an existing binary in
/opt/homebrew/bin or /usr/local/bin, locate it first:
command -v stvenaRemove that manually installed Stvena binary if it occupies Homebrew's target
path, then rerun brew install nccapo/stvena/stvena. See the
tap documentation
for migration details.
No Go installation is required:
curl -fsSL https://raw.githubusercontent.com/nccapo/stvena/main/install.sh | shThe installer downloads the correct macOS or Linux release for your machine,
verifies it against the published SHA-256 checksums, and installs it in an
existing writable binary directory or $HOME/.local/bin.
| Operating system | Architectures |
|---|---|
| macOS | Intel (amd64), Apple Silicon (arm64) |
| Linux | amd64, arm64 |
Run the same command again to upgrade to the latest release. Check the installed
version with stvena --version.
To choose the installation directory or install a specific release:
curl -fsSL https://raw.githubusercontent.com/nccapo/stvena/main/install.sh | \
STVENA_INSTALL_DIR="$HOME/.local/bin" STVENA_VERSION=v0.1.0 shThese options require Go 1.24.2 or newer:
go install github.com/nccapo/stvena/cmd/stvena@latest
git clone https://github.com/nccapo/stvena.git
cd stvena
go build -o bin/stvena ./cmd/stvena
./bin/stvena --helpLaunch Stvena inside the project you want to work on. You can pass an
agent command and its arguments after --, or reopen a saved review:
cd /path/to/your/project
stvena # Starts Codex
stvena claude # Starts Claude Code
stvena -- codex --model YOUR_MODEL
stvena review
stvena sessions
stvena review --session IDShortcuts use Ctrl on both macOS and Linux. Command keys normally belong to the terminal application. Optional Command aliases require a terminal that forwards them; see terminal shortcut setup.
Multiple agent terminals: Ctrl-] opens a chooser: c starts Codex, l starts Claude Code, and Enter repeats your original command with its arguments. Ctrl-N / Ctrl-P switch between terminals while background agents keep running. See Work with multiple agents for the complete workflow.
Reopening a review compares a saved baseline with today's workspace; it does not resume an agent conversation. Other commands can run in the agent pane, but direct selection paste is supported for Codex and Claude Code.
- Start
stvenain your project. Press Enter to configure shortcuts, or Esc to type your task in the agent. - Press Ctrl-G to focus review. Open a changed file, or press 3 to browse the project. Press v to switch between a diff and the full file.
- Drag over code and press b to paste it into the agent's input. Add your request and submit it in the CLI. Use x to collect multiple selections and B to open the context tray.
- Press t to run a check such as
go test ./.... Open results with T, then o for recognized problem locations. - Mark a file reviewed with Space and move to the next unreviewed file with N. In Workspace view, S stages or unstages the selected file.
| Key | Action |
|---|---|
| F6 | Focus bottom panel; arrows select, Enter activates, Esc returns |
| Ctrl-G | Switch between agent and review |
| Ctrl-] | Open another agent terminal |
| Ctrl-N / Ctrl-P | Next / previous agent terminal |
| Ctrl-Y | Next attention: error, review, waiting, changed, running, done |
| Ctrl-W | Close current agent terminal and stop its command |
| Wheel / Shift-PgUp / Shift-PgDn | Scroll the agent pane's output history |
| Ctrl-Q | Quit Stvena and stop all agents |
| 1 / 2 / 3 / 4 | Session / workspace / project files / branch changes |
| Enter / f | Open file / return to file browser |
| v | Toggle diff and full-file view |
| Drag / V | Select code with mouse / keyboard |
| b / x / B | Paste selection / collect selection / open context |
| P | Pin the displayed version or resume live updates |
| K / Z | Start Review checkpoint / finish and preview its draft |
| Space / N | Mark file reviewed / next unreviewed file |
| X / D | Reject the hunk or file / open the rejections tray |
| O | IDE mode: give the agent the whole terminal |
| I / L | Toggle review inbox / open observed session timeline |
| J | Open the task brief: outcomes, constraints and evidence |
| t / T | Run a check / inspect results |
| a / ? | Actions menu / keyboard help |
Stvena opens with the bottom panel focused and Configuration selected. Press Enter to change shortcuts, or Esc to start typing in the agent. Use arrows to select any other footer action. For a Ctrl-G conflict, change Switch panes to Ctrl-O; Ctrl-G then reaches the agent. Settings apply across projects. ? opens Configuration in review; F6 can refocus the footer. Review shortcuts apply when review has focus. Ctrl-C keeps the agent's native interrupt behavior. Review remains open after the agent exits; q closes it. See the complete user guide for comments, hunk staging, search, clipboard tools, and every shortcut.
For a review pause, switch panes with Ctrl-G, then choose Actions → Review checkpoint (K) after the agent changes files. Stvena pins the captured session tree. Use Space/H to review files/hunks, N for the next unreviewed file, and c or x to save exact-line comments or selections across files. Finish checkpoint (Z) warns about remaining work and previews one draft; b pastes it into Codex/Claude Code without submitting, or copies it in standalone review. P resumes live; changed items need review again. An open checkpoint and its feedback survive reopening a saved review.
Marking a file or hunk reviewed (Space / H) is acceptance: the change stays exactly as the agent wrote it. X rejects instead. In the diff it rejects the change block under the cursor; in the file list it rejects the whole file. D opens the rejections tray, where Enter applies the queue now, u undoes a queued rejection, and b resends a message that did not reach the agent.
Rejections are queued, not applied immediately. Stvena does not own the agent's
edits — Codex and Claude write straight to disk — so reverting a file while the
agent is still working makes its next edit build on lines that no longer exist,
makes its tests fail for reasons it cannot see, and commonly makes it re-apply
the change you just rejected. The queue therefore waits until every live agent
is between turns, using the same Stop hook that drives agent attention. The
review header shows N rejected pending while it waits.
In the editor, an accepted or rejected block disappears as soon as you click; undo it from Stvena.
Every Stvena in a project shares review marks: accept a change in one and it is accepted in the others wherever they show the same change, and undoing it travels the same way. Only one of them talks to the editor: if you start a second one, the newest takes over and the older one says so.
Without hooks there is no turn boundary to wait for. Three seconds of
silence means only that nothing was printed, never that a turn ended, so Stvena
never applies the queue on its own for an unhooked agent. Use D → Enter when
you know it is safe. Standalone stvena review, with no agent running, applies
rejections immediately.
When the queue applies, every rejection is reverse-applied as a single
git apply, which writes nothing unless all of it applies. A hunk the agent
edited again after you reviewed it is refused rather than force-applied; the
change stays in your working tree and the message tells the agent to undo it
itself. Rejecting a file the agent created deletes it, so that one asks for
confirmation first. A change that is also staged is reverted in the index as
well when possible, and the notice names any path whose staged copy still holds
it.
Stvena then pastes a message into the agent describing what you rejected and what the working tree now contains — without submitting it, like every other handoff. Press Enter yourself after reading it. Actions → Auto-send rejections (W) submits automatically instead; it is off by default, is shared across projects, and still refuses to submit when you have unsent input in the agent, because Stvena cannot see the CLI's input line.
Press J to write a short list of outcomes and constraints for the current work. In the Brief panel, a adds an item, i edits it, [ / ] reorders it, and d removes the selected item or evidence link. Space marks an item checked by hand. x attaches the current code selection, t the latest check run, and c a saved comment. Enter opens evidence; Esc returns to review.
Stvena never checks an item for you: a passing check or an agent saying it finished does not mark it done. Evidence is marked stale, never deleted, when its code changes or a newer run of the same check exists.
When the Stvena Live extension connects, Stvena offers IDE mode (O). The review pane closes and the agent gets the whole terminal — which is the point in an editor's integrated terminal, where splitting an already short pane again costs more than the review pane is worth while the editor is showing the same review. Ctrl-G still opens review over the full terminal, and O returns to the split view. The setting is shared across projects.
Stvena never switches IDE mode on by itself. It waits for the extension's own
heartbeat rather than trusting the terminal environment, because Cursor,
Windsurf and other forks all identify themselves as VS Code and the extension
may not be installed in the one that is running. Set STVENA_IDE to name an
editor Stvena does not recognise.
In IDE mode the header carries what the review pane would have shown: remaining review work, pending rejections, and the current notice.
This is Drag+b from the editor. Select lines in a file Stvena is reviewing and
⤴ Paste to agent · Ask… · Add to context appears above the selection, like
the ✓ Accept / ✗ Reject actions; the editor title bar gets a send button too. In
Zed, use the Stvena: Paste Selection to Agent code action. The selected lines
go into the agent's input exactly as b pastes them in Stvena. Add your request
around them and press Enter yourself. Hide the actions with
stvena.showSelectionCodeLens.
Select code in the editor and press Cmd-K Cmd-A (Ctrl-K Ctrl-A on Linux), or use Stvena: Ask the Agent About This Selection. Type your question and Stvena places it in the agent's input together with the selected code, taken from its own capture rather than the editor's buffer. As with every other handoff, Stvena does not press Enter — read the draft and send it yourself.
Stvena can run several agent terminals in one session. Each terminal keeps its
own screen, conversation, and unfinished input. The agent pane shows one terminal
at a time, and the header identifies the active command and its position, such as
codex 1/2. Other agents continue running in the background.
Press Ctrl-] from either pane to open the new-agent chooser:
- c starts Codex with its CLI defaults.
- l starts Claude Code with its CLI defaults.
- Enter starts the selected option. The initial option repeats the command used to launch Stvena, including its arguments.
Every new terminal starts in the original working directory. All agents share the same session baseline and review workspace, so changes from every agent appear together. Code selections and review drafts are pasted into the currently selected agent.
Use Ctrl-N and Ctrl-P to move between agent terminals. Ctrl-W stops and closes the selected agent; finished terminals otherwise remain available for inspection. Closing the last agent leaves the review workspace open, where Ctrl-] can start another. Ctrl-Q stops every agent and exits Stvena.
Agent terminals are live processes rather than saved conversations. Reopening a
saved review does not restart them, and multiple-agent shortcuts are unavailable
in standalone stvena review mode.
A compact strip above the panes shows every terminal's stable name and status:
● RUNNING, ! REVIEW, ? WAITING, + CHANGED, ✓ DONE, × ERROR, or
· IDLE. Brackets identify the active terminal; → identifies the highest
attention priority. Color reinforces these text labels. 3f always means three
unreviewed file paths (a rename can include both paths). / RUN means the agent is still working while it needs review.
The header counts agents, running agents, agents with unreviewed files, waiting
agents, and errors. The strip uses at most two rows; overflow keeps the highest
priority agent visible and shows how many other agents are hidden.
Ctrl-Y (Next attention) starts at the highest priority and cycles through error → review → waiting → changed → running → done. Normal terminal navigation resets the cycle. Configure it in ? → Configuration, like the other global shortcuts; the footer also provides Next attention. Command-Y is an optional alias when the terminal forwards it. No background event switches panes.
Selecting attention opens the relevant file in This session when possible. An existing pinned checkpoint or unfinished review input stays intact. The normal e editor action then opens that file; the live editor bridge continues to publish combined workspace changes.
REVIEW clears only after Space marks the captured file reviewed, or H marks all its hunks reviewed, in This session or a session checkpoint. Opening the agent or diff does not acknowledge it. Reviewing an older pinned version does not clear newer changes. An acknowledged session stays clear when another agent later edits the same path. New edits by the original agent create new review items. If edits are reverted before capture, Next attention offers an explicit no-net-change acknowledgement. Closing a terminal removes its live indicators; its changes and existing review records remain in the shared workspace.
Execution, review, activity time and changed-file ownership are separate state. Attention priority is derived from them. Invocation-local observers use Claude hooks and Codex hooks: prompt/tool events mark running, Stop marks a completed turn, Claude StopFailure and unsuccessful process exits mark error. Claude permission/idle notifications provide waiting signals. Without structured hooks, PTY output means running; three seconds without output means idle, never waiting or completed. A successful process exit means done.
File attribution compares named files before and after Claude Edit/Write/MultiEdit or Codex apply_patch calls, including additions, deletions and renames. The git snapshot watcher then supplies captured review versions. Arbitrary shell/MCP writes and commands without hooks cannot be reliably attributed in a shared working directory; they remain visible in the combined diff without assigning an owner. Concurrent edits to the same file are reviewed against its combined captured diff. Git-ignored files are outside the normal diff capture.
Codex must support and trust the configured hooks. Explicit Claude --settings
are preserved, so automatic observers are not added in that case. Codex waiting
prompts and CLI turn failures without a supported event cannot be detected
reliably; Stvena does not infer them from terminal text. Live attention state is
not restored after restarting Stvena; saved review records continue to work.
The experimental Stvena Live extension follows
captured edits and the active Stvena review range while Stvena runs in its
integrated terminal. It always opens ordinary working source files—Stvena's TUI
remains the diff surface. Use Stvena: Review This Line in Stvena to move the
TUI to the editor cursor, or Stvena: Add Selection to Context to collect the
captured selection in Stvena's tray. Supported Codex and Claude tool hooks
also report read locations. Blue read markers and amber edit markers show the
relevant lines with an inline label; markers expire after 15 seconds. Codex
requires its normal /hooks trust review before read reporting runs.
Accept and reject, the per-block actions, Explorer badges, asking the agent about a selection, IDE mode, and reviewing a project that is not a Git repository need Stvena 0.4.0 or later. Against an older binary the extension hides what that binary cannot do and keeps its 0.2.x read and edit following.
Install Stvena Live by nccapo from the VS Code Extensions view, or run:
code --install-extension nccapo.stvena-liveThen install or upgrade the Stvena binary on macOS or Linux with
Homebrew (brew upgrade stvena) or the
install script. The extension and terminal
application are installed and updated separately.
Open a trusted local workspace in VS Code, check that stvena --version
reports 0.4.0 or later, and run stvena or stvena claude in its integrated
terminal. No Go or Node.js installation is needed.
Stvena Live 0.3.0 adds accept and reject. Marketplace installations receive updates through VS Code according to your update settings; a pre-release version needs Switch to Pre-Release Version on the extension page. For Antigravity or manual installation, use Extensions: Install from VSIX… with the VSIX attached to the release. See the extension guide for both installation paths and troubleshooting.
Click Stvena: Following in the status bar to pause or resume navigation; Stvena: Show Latest Activity returns to the latest reported read or edit. If the view stays Waiting, check the binary version and workspace trust, and open Stvena Live in the Output panel for connection errors.
The extension targets VS Code 1.85 or newer. It exchanges small, validated local descriptors through the repository's Git directory, or, for a project without one, through Stvena's own per-project directory; it does not run commands, write source, add telemetry, or expose a network service.
Updates are snapshots sampled roughly every 700 ms plus capture and extension polling time. They include saved edits from every workspace writer, without per-agent attribution or guaranteed intermediate history. Automatic navigation skips deleted files and files with unsaved editor changes.
See the extension guide for installation, compatibility, and capture limits, or the bridge protocol to build another local editor integration.
Zed's extension API cannot draw markers, register commands, or open files, so the same surface arrives over the Language Server Protocol instead. Stvena's own binary serves it:
stvena editor-lsp --ide zedThe language server ships in Stvena 0.4.0 and later; an earlier
binary has no editor-lsp subcommand and the editor will report that the server
failed to start.
In Zed, install the Stvena Live extension
— it does nothing but launch that command — then run stvena in a terminal in
the same project. Two Zed settings are off by default and turn on two of the
surfaces:
{ "code_lens": "on", "inlay_hints": { "enabled": true } }code_lens draws the ✓ Accept / ✗ Reject buttons and inlay_hints draws the
marker labels; diagnostics, code actions and the status item need neither.
| In the editor | How it arrives |
|---|---|
| The working file opens at the changed or read line, terminal keeps focus | window/showDocument — not in Zed 1.19, see below |
| ✓ Accept · ✗ Reject above a change block; gone once decided | Code lens |
✎ agent edit, 👁 read (claude), ◆ reviewing labels |
Inlay hints |
| Every unreviewed block listed, with an underline and a scrollbar mark | Information diagnostics |
| Paste to agent, Review in Stvena, Add to context, Accept/Reject file, Apply rejections, Pause/Resume | Code actions (source.stvena) |
following · 3 unreviewed · 1 rejection waiting for turn end |
$/progress |
Zed 1.19 does not implement window/showDocument, so it does not open files for
you yet: Stvena marks the changed and read lines where they are, lists them in
the Project Diagnostics panel, and says so once in the language server log.
Every other surface works, and navigation turns itself on in any editor that
advertises the capability.
Any editor that can launch a language server can use the same command; only Zed needs the extension wrapper. Rejecting with a reason has no LSP equivalent — reject from the editor and add the reason in the TUI, or use the TUI's X.
Stvena does not require its own API key or account. It launches the agent CLI you already use with your environment and credentials. Your chosen agent's network access and data handling still apply.
- Review metadata, comments, snippets, draft requests, layout preferences, and check
output are stored under your OS cache directory in
stvena/<repository hash>. - The task brief is stored per project with review state. It holds at most 30 items, 200 characters per item, and 8 evidence links per item.
- Custom shortcuts are shared across projects in your OS user configuration
directory at
stvena/hotkeys.json. - Captured code is retained in local Git objects under
refs/stvena/sessions/*andrefs/stvena/reviews/*. Use normal branch pushes; a mirror push can also publish these private refs. - Capture respects Git ignore rules for untracked files. Already tracked files are captured even if subsequently ignored. Put credentials outside Git and inspect your index before committing.
- Selected code is pasted only when requested; Stvena does not press Enter to submit it. Drafts can include absolute paths and captured source.
- Check commands run with your user permissions and inherited environment. The temporary checkout is not a sandbox. Run commands you trust.
Retained snapshots do not expire automatically. Use one Stvena process per repository to avoid competing writes to saved review state. The storage and limits guide describes capture behavior and size limits.
Bug reports, focused pull requests, and usability feedback are welcome. Read CONTRIBUTING.md for setup, checks, and what to include in a report. For sensitive findings, see SECURITY.md.
go test ./...
go test -race ./...
go vet ./...
go build ./...
cd extensions/vscode
npm ci
npm test
npm run packageMaintainers publish the prebuilt archives and checksums by pushing a semantic version tag. See Publish a release for the release command and verification steps.
| Package | Responsibility |
|---|---|
cmd/stvena |
Command entry point |
internal/app |
Agent lifecycle, event loop, input, and actions |
internal/diffview |
Git collection, captured content, and staging |
internal/session |
Snapshot capture, retained refs, and session storage |
internal/review |
Navigation, selections, review marks, and feedback |
internal/checks |
Check execution, bounded logs, and problem locations |
internal/editor |
Local editor bridge and captured-change protocol |
internal/ui |
Terminal layout, code rendering, and controls |
extensions/vscode |
Stvena Live editor navigation and latest-change view |
The product direction and research notes describe ideas and tradeoffs; they are dated planning documents, not a promise of supported features.
MIT © 2026 Stvena contributors.
Stvena is an independent project, unaffiliated with OpenAI or Anthropic.