stvena

README

Stvena

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.

https://github.com/user-attachments/assets/7aecafe5-1e45-442e-ab49-82cfc3750d9f

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.

Why Stvena?

• See the work as it happens. Review changes since the agent started, or inspect staged, unstaged, and new files across the workspace.
• 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.
• Follow saved edits in your editor. The experimental Stvena Live extension lists each newly captured batch and opens the working source at its first changed line while focus stays in the integrated terminal.
• Keep track of your review. Pin a captured version, mark files and hunks reviewed, and see when a reviewed change has changed 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.

Installation

You need Git, an interactive terminal, and your chosen agent CLI installed and authenticated. Stvena uses Unix PTYs and process groups; macOS and Linux are the intended platforms. Native Windows is not supported.

Prebuilt binary (recommended)

No Go installation is required:

curl -fsSL https://raw.githubusercontent.com/nccapo/stvena/main/install.sh | sh

The 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 sh

Homebrew is not required. A dedicated Homebrew tap is not published yet, so the verified installer is currently the shortest supported installation path.

Install with Go or build from source

These 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 --help

Quick start

Launch Stvena inside the Git 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 ID

Shortcuts 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.

A typical workflow

1. Start stvena in your project. Press Enter to configure shortcuts, or Esc to type your task in the agent.
2. 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.
3. 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.
4. Press t to run a check such as go test ./.... Open results with T, then o for recognized problem locations.
5. 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-W	Close current agent terminal and stop its command
Ctrl-Q	Quit Stvena and stop all agents
1 / 2 / 3	Session changes / workspace changes / project files
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
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.

Work with multiple agents

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.

Follow reads and edits in VS Code

An experimental Stvena Live extension follows captured edits in the editor while Stvena runs in its integrated terminal. It opens working source files at the changed line, lists the latest changed files, and lets you pause and resume following. 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.

Download the binary and stvena-live-0.2.0.vsix from the GitHub preview release. Install the preview binary on macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/nccapo/stvena/v0.2.0-preview.1/install.sh | \
  STVENA_VERSION=v0.2.0-preview.1 sh

In VS Code or Antigravity, install the downloaded .vsix with Extensions: Install from VSIX…, open a trusted local Git workspace, and run stvena in its integrated terminal. No Go or Node.js installation is needed. The preview is not yet published to a marketplace; the default Stvena installer still selects the stable release, so use the explicit preview version above. The extension targets VS Code 1.85 or newer. It reads saved file captures from the repository's Git 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.

The first target is the VS Code extension API. Zed requires a separate integration. See the extension guide for installation, compatibility, and capture limits, or the bridge protocol to build another local editor integration.

Privacy and local data

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>.
• 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/* and refs/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.

Development and contributions

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 package

Maintainers 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.

License

MIT © 2026 Stvena contributors.

Stvena is an independent project, unaffiliated with OpenAI or Anthropic.