Vimeflow

Why settle for a terminal or a GUI? Have both — boost productivity and stay in your flow.

Your agent CLIs run in real terminal panes, and the GUI is built around them — not on top of them.

English | 简体中文

Vimeflow is an Electron desktop app backed by a Rust sidecar (vimeflow-backend). A single window gives you agent terminals (native Ghostty panes on macOS), keyboard-driven multi-pane layouts, a file explorer, a vim-mode editor, hunk-level git review, a vim-style command palette, customizable themes, and live observability for Claude Code, Codex CLI, Kimi Code, and OpenCode.

Contents

• Native Ghostty terminals on macOS
• Many agents in one workspace
• Pick up where you left off
• Review changes hunk by hunk
• Worktree integration
• Command palette and settings
• Themes
• Linux
• Current support
• Build and run from source
• Project references

Native Ghostty Terminals on macOS

Vimeflow doesn't emulate a terminal in the browser. Packaged macOS arm64 builds embed the actual Ghostty engine (libghostty-spm with a parented NSView), while the Rust sidecar keeps ownership of the PTY. The result is Ghostty's GPU-accelerated rendering inside Electron: output renders as it streams, and panes reflow smoothly during resizes instead of tearing or lagging.

Run full-screen TUIs alongside your agents — nvim, lazygit, and similar tools work side by side with an agent session and reflow cleanly on resize. Linux and the dev fallback use xterm.js.

<sub>Try it:
1. Launch a packaged macOS build, or npm run electron:dev:ghostty from source.
2. Press ⌘;, run :layout, and choose a two-pane layout.
3. Start an agent in one pane and nvim . in the other — both are real PTYs.</sub>

Terminal working-directory sync relies on OSC 7. zsh and fish usually emit it automatically; for bash, run:

./scripts/setup-shell-osc7.sh

Many Agents in One Workspace

Most coding-agent CLIs report their state in a single statusline. Vimeflow gives each agent a dedicated panel instead — model, context window, and a live trace feed — detected automatically when you run the CLI, with no wrapper commands required. The trace feed keeps the 50 most recent completed tool calls, organized into per-agent profiles (Claude, Codex, Kimi, and OpenCode each have their own), and any trace that modified the working tree gets a Show diff shortcut, so you can jump straight to the change a step made.

<sub>Try it:
1. Click + in the sidebar — the New Session dialog takes a session name, a working directory, and optionally the agent command to launch with it.
2. Press ⌘; and run :layout to pick a multi-pane arrangement.
3. Run claude, codex, kimi, or opencode in any pane — the status panel picks each one up as it starts.</sub>

Reading the status sidebar

The panel shows a set of live gauges. When you collapse the sidebar, they fold into a compact rail:

Context reservoir — how much of the model's context window remains. The fill changes color as usage grows, so you can see the limit approaching.	Cache rate — the share of the current turn served from cache, drawn as a ring. A fuller ring means a cheaper, faster turn.	Traces — the 50 most recent completed tool calls: tool, arguments, and result, newest first.	Collapsed — the reservoir and ring folded into a single compact rail.

Plan usage, where the API allows it

For agents that expose a usage API — currently fully supported for Codex CLI and Claude Code — the panel tracks session and weekly usage next to the model name.

Kimi Code shows the same bars, with a one-click control to disable tracking entirely:

_{Kimi Code plan usage is opt-in — fetching it sends your configured Kimi credentials to the Kimi API. Detection, transcript tailing, and activity tracking otherwise stay entirely local (~/.kimi-code/).}

_{OpenCode exposes no usage-quota API, so there are no bars to draw — the status card links the upstream request (sst/opencode#16017) instead. It's detected through a small auto-installed bridge plugin that reads model, context window (sized from OpenCode's models.dev cache), and tool activity with zero credential access.}

Pick Up Where You Left Off

Closing Vimeflow doesn't end your agents' day. The workspace remembers every session — its layout, its panes, and the conversation running in each one — and the next launch brings it all back: each agent pane re-issues its own resume command (claude --resume, codex resume, and friends) against the exact conversation it was in. A workspace full of half-finished tasks reopens as a workspace full of half-finished tasks, not a row of empty prompts.

_{Sessions restore together with their layouts. Each detected agent resumes by conversation id; a pane with nothing to resume simply comes back as a fresh shell.}

Review Changes Hunk by Hunk

Vimeflow includes a full inline review surface docked next to your terminals, rather than shelling out to git diff. Diffs are rendered by Pierre's engine (@pierre/diffs), themed to match your workspace, with the changed-files list one pane over. You can act on hunks in place: stage or unstage a single hunk, or discard a hunk or an entire file.

Review is also interactive. Leave a line-level comment and the agent working in that session replies in the same thread, then fixes the code; the final Resolve click stays with you. For a second opinion, Request review hands the diff to another reviewer — dispatch it to another agent, or copy the prompt and use it wherever you like. Either way, you can walk through the edits hunk by hunk and catch problems while the code is still being written, without leaving the window.

<sub>Try it:
1. Open a session in a repository with uncommitted changes.
2. Press ⌘G (or ⌘; → :open-diff) to open the diff dock next to your panes.
3. Pick a file in the changed-files list and stage, unstage, or discard individual hunks.
4. Tune hunk rendering under Settings → Version Control → Hunk Appearance.</sub>

Worktree Integration

Working with several agents usually means several git worktrees, and it's easy to lose track of which one you're looking at. Vimeflow watches each agent's terminal and detects when it enters a worktree — an Entering worktree(...) message, a bare cd, an EnterWorktree skill report, or an OSC 7 hint — then switches the pane to match, with no reload. The git chip in the status bar always shows your current location (worktree → branch) and copies the worktree name, its path, or the branch in one click.

The worktree an agent lives in also determines what you see: the file explorer follows into that tree, and diff review scopes its changed-files list and hunks to that worktree. You always review the code the agent is actually touching, not a stale checkout.

Command Palette and Settings

The palette combines command-line speed, Neovim-style aliases, and Zed-style fuzzy matching. ⌘; opens it: :new for a new session, :layout for panes, plus :open-diff, :open-editor, :theme, :settings, :goto, and more — with fuzzy matching and per-command shortcuts. Select the Vim keymap preset if you want Vim-flavored aliases like :tabnew, :vsplit, :split, and :only. The settings dialog covers the rest: appearance, keymap, coding agents, editor, terminal, version control, and more.

<sub>Try it:
1. Press ⌘; and type a few letters — commands fuzzy-match as you type.
2. Run :new to spin up a session, :goto to jump between sessions.
3. Open Settings (bottom of the sidebar) to remap keys under Keymap or configure agent launchers under Coding Agents.</sub>

Themes

The Lens theme system ships several built-in themes — Catppuccin (dark default), Flexoki (light), Gruvbox (dark and light), Tokyo Night, Dracula, and more. Every color in the app is a semantic token, so the whole workspace, terminals included, recolors instantly, with a live preview before you apply. You can also import and export themes as JSON to build your own.

<sub>Try it:
1. Press ⌘; and run :theme.
2. Move through the list — the workspace previews each theme live.
3. Press Enter to apply, or Esc to discard the preview.</sub>

Linux

Everything above works on Linux as well, with one difference: terminals use xterm.js rather than libghostty (Linux builds do not support the libghostty rendering engine yet). Package it as an AppImage, chmod +x, and run it.

Current Support

Vimeflow currently supports version 0.1.0 from source code only.

• Supported release line: 0.1.0
• Supported packaged targets: Linux x64 AppImage and macOS arm64 DMG built locally from source
• Desktop runtime: Electron 42 + Rust sidecar over LSP-framed JSON IPC
• Terminal runtime: built-in native Ghostty via libghostty-spm for packaged macOS arm64, with xterm.js kept as the Linux/dev fallback
• Agent observability: Claude Code, Codex CLI, Kimi Code, and OpenCode
• Not yet supported: hosted binary releases, Windows packaging, production signing/notarization, or auto-update

Packaging is host-specific: build the Linux x64 AppImage on Linux x64, and build the macOS arm64 DMG on an Apple Silicon Mac.

Build and Run from Source

Prerequisites:

• Node.js >= 22; Node 24 from .nvmrc is preferred for CI parity
• nvm is optional but recommended for using .nvmrc; skip nvm use if Node 24 is already active through another manager
• Rust stable toolchain
• Git
• Linux x64 or Apple Silicon macOS for supported package builds

git clone https://github.com/winoooops/vimeflow.git
cd vimeflow
nvm use # Optional: switches to Node 24 from .nvmrc
npm ci

To keep a dev run fully isolated from an installed Vimeflow (separate sessions, settings, and agent state), point any of the commands below at a throwaway data directory:

VIMEFLOW_USER_DATA_DIR=/tmp/vimeflow-demo npm run electron:dev

macOS

Run with the native Ghostty runtime — the same terminal backbone the packaged build ships:

npm run electron:dev:ghostty

Or run on the xterm.js path — same app, no native Ghostty:

npm run electron:dev

Build the arm64 DMG:

npm run electron:build            # or: npm run electron:build:mac:arm64

The DMG lands at release/vimeflow-*-arm64.dmg. It bundles the native Ghostty parent runtime, is intended for local source builds, and is not notarized.

Linux

Run from source — terminals are xterm.js on Linux (native Ghostty is macOS-only for now):

npm run electron:dev

On hosts without a working Chromium sandbox:

VIMEFLOW_NO_SANDBOX=1 npm run electron:dev

Build the x64 AppImage:

npm run electron:build            # or: npm run electron:build:linux:x64

Then run it:

chmod +x release/vimeflow-*.AppImage
./release/vimeflow-*.AppImage --no-sandbox

If the host does not provide libfuse2, use AppImage's extract-and-run fallback:

./release/vimeflow-*.AppImage --appimage-extract-and-run --no-sandbox

Use Vimeflow

1. Start Vimeflow with npm run electron:dev or a locally built package.
2. Click + to create a session in your project, optionally launching claude, codex, kimi, or opencode with it.
3. Split panes, browse files, edit code, and review git changes hunk by hunk — see the feature tour above.
4. The agent status panel appears whenever a supported agent is detected.

Lifeline and Harness Engineering

This repository is also a practical harness-engineering project. Vimeflow's development workflow uses the Lifeline Claude Code extension for planning, autonomous implementation loops, reviews, PR requests, upstream review handling, and PR approval.

Project-local setup notes live in CLAUDE.md.

Verify a Checkout

npm run lint
npm run format:check
npm run type-check
npm test
cargo test --manifest-path crates/backend/Cargo.toml

Regenerate TypeScript bindings after Rust type changes:

npm run generate:bindings

Project References

• Setup details: SETUP.md
• Development commands and style: DEVELOPMENT.md
• Architecture and Electron sidecar IPC: ARCHITECT.md
• Design system: DESIGN.md and docs/design/UNIFIED.md
• Current roadmap status: docs/roadmap/progress.yaml
• Changelog: CHANGELOG.md / CHANGELOG.zh-CN.md
• Backend crate notes: crates/backend/README.md

License

MIT