One keyboard-driven dashboard for every Claude Code and Codex session on your machine.

Install · Quick start · Workflows · CLI · Configuration · Limitations · Development

_{Dashboard and embedded agent UI}

_{Session-scoped diffs · themes and native agent controls}

vag puts your coding-agent sessions in one terminal workspace. Open a session in the real agent UI, detach to the dashboard while it keeps running, see which turns need attention, and inspect the working-tree diff associated with each session.

It does not replace or reimplement either agent. vag launches your installed claude and codex binaries in PTYs and keeps its folders, colors, and activity metadata separate from their session stores. Think lazygit for agent sessions.

• One tree for every session — discover Claude Code and Codex sessions automatically, group them into folders, filter them, or scope the view to the current Git repository. Agent session files are scanned read-only and never moved.
• The real agent UI — run the installed CLIs in embedded terminal panes. Detach to the dashboard, return later, keep several sessions open, or zoom one to the full terminal.
• Attention at a glance — see when a session is working, done, waiting for approval, waiting for input, idle, or exited. Native agent events are used when available, with PTY and transcript activity as fallbacks.
• Session-scoped diffs — press D to review the live diff for files a session touched. Use the built-in renderer or your existing delta setup.
• Organize at terminal speed — create sessions with a built-in fuzzy directory picker, or press e and edit the whole session tree as an oil.nvim-style text buffer.
• Activity without inflated timers — dashboard cards and a calendar heatmap record genuine streaming-output time, excluding idle time and approval waits.
• Local and remote — mix Claude, Codex, local shells, and SSH machines in the same dashboard.
• Batteries included — themes, mouse support, Nerd Font icons, a floating-tree layout, and in-app settings ship in one binary. The fuzzy finder is built in; fzf is not required.

vag supports macOS and Linux on x86_64 and aarch64. Install at least one of Claude Code or Codex first.

brew install cluely/vag/vag

The Homebrew formula also installs git-delta for richer diff rendering.

curl -fsSL https://raw.githubusercontent.com/cluely/vag/main/install.sh | sh

The script downloads a release binary when one is available and otherwise builds from source with Cargo. The fallback requires a current stable Rust toolchain. Set VAG_INSTALL_DIR to choose the destination.

cargo install --git https://github.com/cluely/vag

Building from source requires a current stable Rust toolchain. Git is used for repository scoping and diffs; delta and SSH are optional.

After installing, check the setup:

vag doctor

Start vag inside a repository to see that project's sessions, or anywhere else to see every discovered session:

cd ~/code/my-project
vag

Press n, choose Claude or Codex, and pick a working directory with the built-in fuzzy finder. While the agent works, press ctrl-q to return to the tree and open another session. The row status updates live:

Unfiled Inbox sessions with no activity for more than three days move into a collapsed Archived smart group. This only changes the dashboard view; it does not edit either agent's store.

Press D from the tree or ctrl-g from a pane. vag shows a collapsible file tree beside a live diff anchored to the commit that was HEAD when the session first opened.

By default, the diff is limited to files the agent's transcript says it touched. Press a to widen it to the whole repository, B to re-anchor the base to the current HEAD, or r to refresh. If delta is on PATH, its syntax themes, line numbers, and side-by-side settings apply automatically; otherwise vag uses its built-in unified renderer.

Press e in any tree to enter edit mode. Rename a session by editing its line, move it with dd and p, create a folder with o and a trailing /, or copy and paste a session to fork it. :w previews the actions before applying them.

Add an SSH machine from the UI with R, or from the shell:

vag remote add gpu-box user@host --dir '~/work'

Press n on a machine to create an agent session there, or s to open a plain shell. Connections use your normal ssh command and ~/.ssh/config; vag does not store credentials.

Remote Claude sessions created by vag persist and can be reopened from the dashboard. A remote Codex session works only while its original vag pane is open; after that, resume it on the remote machine with codex resume because vag cannot reattach it yet.

The default sidebar keeps the session tree beside the active agent. Floating mode gives the agent the full width and opens the tree as an overlay when you press the detach key:

vag --float

Use b from the floating tree to return to the full dashboard, or e to edit the overlay directly.

Press ? inside vag for the contextual keymap. Dashboard command bindings and its five control chords are rebindable from the settings page or config.toml; navigation and view-specific scrolling keys stay fixed.

Per-run UI overrides:

--icons <ascii|nerd|auto>
--tree <sidebar|float>
--float
--pane <titlebar|border>
--theme <name>
--edit

The settings row is pinned at the bottom of the tree. Press , to open it and change the theme, icons, pane style, tree mode, sidebar width, launch behavior, or any rebindable key. Changes preview live and are written without discarding comments in the config file.

For manual configuration, create ~/.config/vag/config.toml (XDG_CONFIG_HOME is respected). Every field is optional:

[ui]
theme = "mocha"          # night, mocha, gruvbox, dracula, nord, onedark,
                         # solarized, rose-pine, or transparent
tree = "float"           # sidebar or float
pane = "titlebar"        # titlebar or border
icons = "auto"           # ascii, nerd, or auto
sidebar_width = 38
mouse = true
edit_default = false

[keys]
detach = "ctrl-q"
toggle_sidebar = "ctrl-e"
focus_tree = "ctrl-h"
focus_pane = "ctrl-l"
toggle_diff = "ctrl-g"
new_session = "n"
diff = "D"
settings = ","

[agents.claude]
command = "claude"
extra_args = []

[agents.codex]
command = "codex"
extra_args = []

[diff]
use_delta = true
delta_args = []           # for example: ["--side-by-side"]

[behavior]
repo_scope = true
show_hidden = false
codex_show_automation = false

Override individual theme colors with red, orange, yellow, green, cyan, blue, magenta, pink, or a #rrggbb value:

[theme]
bg = "#1a1b26"
fg = "#c0caf5"
surface = "#24283b"
sidebar_bg = "#1f2231"
sel = "#3b4261"
dim = "#565f89"
accent = "cyan"
info = "#7dcfff"
pane_fg = "#c0caf5"
pane_bg = "#1a1b26"

Set pane_fg and pane_bg together, using hex colors, to override the embedded terminal palette.

Remotes can also be declared directly:

[[remotes]]
name = "gpu-box"
host = "user@example.com"
default_dir = "~/work"
# claude_command = "claude"
# codex_command = "codex"

Configuration and local state live at:

XDG_CONFIG_HOME and XDG_DATA_HOME change those roots. Folder organization and activity stats are written atomically. Discovery reads agent stores without writing to them; explicit Codex archive and delete requests are delegated to the native Codex CLI.

Flags take precedence over the file. The equivalent environment overrides are VAG_ICONS, VAG_TREE, VAG_PANE, VAG_THEME, and VAG_EDIT. Native CLAUDE_CONFIG_DIR and CODEX_HOME overrides are also respected.

Mouse support works in tmux without additional configuration. Because terminal mouse reporting takes over drag events, hold Shift while dragging to select text, or set ui.mouse = false.

is_vim="ps -o state= -o comm= -t '#{pane_tty}' | grep -iqE '^[^TXZ ]+ +(\\S+\\/)?g?(view|l?n?vim?x?|fzf|vag)(diff)?$'"
bind-key -n 'C-h' if-shell "$is_vim" 'send-keys C-h' 'select-pane -L'
bind-key -n 'C-l' if-shell "$is_vim" 'send-keys C-l' 'select-pane -R'

Each open session is a real CLI process running on a PTY. Its output is fed to alacritty_terminal, then the emulated grid is rendered by ratatui. Input stays as raw terminal bytes; vag handles only its configured navigation, scrolling, and view shortcuts around the child process.

Discovery is defensive because both agents' on-disk formats are internal. A failed backend produces a warning instead of taking down the other agent or the dashboard.

• vag has no daemon. Quitting ends the sessions it launched.
• The embedded pane exposes an xterm-256color surface. Kitty keyboard protocol sequences are not forwarded, so use an agent's alternate binding or zoom with z when a key depends on that protocol.
• Claude Code has no per-session delete command. vag can hide Claude sessions; Codex archive and delete actions use the native Codex CLI.
• Claude and Codex storage formats are internal. A CLI update may require a compatibility fix even though discovery is read-only and defensive.
• Remote Codex sessions cannot be reattached from vag; after the original pane closes, resume them on the remote machine. Remote sessions also cannot currently be forked from vag.

git clone https://github.com/cluely/vag.git
cd vag
cargo test
cargo run

Read-only smoke tests against the agent stores on your machine are opt-in:

cargo test -- --ignored

The terminal fidelity harness can run an agent in isolation or dump its headless terminal grid:

cargo run --example spike -- -- claude
cargo run --example spike -- --headless 10 -- codex

Issues and pull requests are welcome. Please run cargo test before submitting a change.

vag borrows interaction ideas from tools that make complicated terminal workflows feel direct: lazygit, fzf, oil.nvim, and Neovim.

MIT © 2026 Guilherme Garibaldi