Shellvisor

Your real shell, plus a workspace around it — inside the terminal you already use.

Shellvisor is a full-screen terminal app (like tmux, htop or vim) that runs your own zsh or bash in tabs and splits, and — as it grows — adds panes for files, live system stats, a data-flow view of your pipelines, and coding agents working side by side. Every command, alias and full-screen program you use today keeps working unchanged.

Status: early development (P0–P4 of 7 done). Working today: tabs and splits of real zsh/bash shells, a tab bar that shows what each tab is doing (running ⠋, downloading ◴ with a progress bar, failed ✖, new output •), a status bar, split layouts, your tabs restored after a restart, custom keys, and a one-key switch to basic view, which looks exactly like a plain terminal. Plus a files pane (tree, list, columns, grid, git changes, find, sizes, recent, preview) that follows your shell, a system pane (CPU, memory, disk, network, I/O, temperatures, processes), download/install progress for git, npm, pip, uv, brew, docker, cargo, curl and friends, sv data commands (nushell-style tables in bash/zsh) with an interactive table viewer, a Flow pane that shows the running job and meters pipelines stage by stage, and coding agents side by side (Claude Code, Codex, Gemini CLI, Aider or any command), each in its own git worktree, with one place to answer their approval prompts. Agents can start sub-agents, run as a team from team.yaml, or be planned from a goal on the agent board (alt+g). See docs/ROADMAP.md.

Why

• One binary, tiny footprint. Written in Rust. Budget: ≤ 8 MB binary, ≤ 15 MB memory, < 0.5 % CPU when idle. The current build is ~1.8 MB and uses ~5.6 MB of memory with three tabs plus the files and system panes open.
• Nothing to relearn. Your .zshrc / .bash_profile load as usual; vim, less, fzf, ssh and git all behave as before.
• Off is one command away. sv off hides the panels, sv exit leaves completely.

Install

macOS or Linux, with zsh or bash.

brew install avmg0/tap/shellvisor                     # Homebrew (macOS, Linux)
curl -fsSL https://raw.githubusercontent.com/avmg0/shellvisor/main/scripts/install.sh | sh   # or: prebuilt binary into ~/.local/bin, checksum-verified
cargo install --git https://github.com/avmg0/shellvisor shellvisor                           # or: build it (Rust 1.85+)

Debian / Ubuntu (x86_64 and arm64; glibc 2.39 or newer, e.g. Ubuntu 24.04, Debian 13): download shellvisor_<version>_amd64.deb (or _arm64.deb) from the latest release and sudo apt install ./shellvisor_*_amd64.deb.

Arch Linux: the AUR package shellvisor-bin (yay -S shellvisor-bin, or git clone https://aur.archlinux.org/shellvisor-bin.git && cd shellvisor-bin && makepkg -si).

Then run shellvisor. Inside it, sv is always available; Homebrew and the install script also put sv next to shellvisor so sv on works from a plain terminal (after cargo install, link it once: ln -s "$(command -v shellvisor)" ~/.cargo/bin/sv).

sv autostart on starts Shellvisor in every new terminal window (it adds a short, marked block to ~/.zshrc or ~/.bashrc; it skips tmux, SSH sessions and editor terminals, and quitting Shellvisor leaves you in your normal shell). sv autostart off removes it.

Release archives are checksummed and carry a signed build-provenance attestation — see docs/RELEASING.md.

Use

shellvisor                 # start with your login shell
shellvisor --shell bash    # or pick: zsh, bash, or a full path

Key / command	What it does
F1	all keys
alt+t · F10	new tab (same folder)
alt+1…9 · alt+[ / alt+]	go to tab · previous / next
alt+r · alt+w	rename · close tab (if something still runs: Stop & close, Keep in background, or Cancel)
alt+\ · alt+-	split side by side · stacked
alt+arrows · F6	move between splits
alt+shift+arrows · F5	resize · zoom a split (or drag the border; sv resize left 2, sv resize 30%)
F7 · alt+l	rearrange splits: columns → rows → main + side → grid
F2 · sv files	files pane: open · focus · close
F3 · sv sys	system pane: open · focus · close
F8 · sv flowpane	flow pane: the job running in the shell, or sv flow meters
sv pane preview|agents|activity	more pane kinds (also in the layout editor and the palette): the file picked in the files pane, every agent's state and changes, downloads and installs. A second tool pane stacks under the first
sv pane ports|docker|logs|http	panes for the services you run — see Service panes
F4	explore the last sv table: sort, filter, copy
alt+;	command bar: ls | where size > 1mb | sort-by size -r → table
F9 · shift+F9	agents tab · new agent
alt+a	agents waiting for approval: y allow · n deny · a always
sv layout dev	files + shell + system + flow (also monitor, files, data, agents; or alt+m)
alt+e	layout editor: start from a preset or a saved layout, add shell / files / git / system / thermals / flow panes (keys, or drag one from the palette onto a pane — a dashed zone shows where it lands), remove, resize (keys or mouse), undo; nothing changes until ⏎, esc puts it back. Save by name, as the default, or for this folder (sv layout <name> opens a saved one)
ctrl+] j · sv activity	downloads & installs: progress bar, speed, time left; finished ones with c cd into it · o open in files (or click the download in the status bar)
alt+s · sv settings	settings: colour of the folder in your prompt, of the commands you type and of folders in lists, ls as a table, table borders, theme
alt+m	tab menu: Rename, Duplicate here, Change shell, Split right / down, Move to new window, Pin / unpin, Mute alerts, Close — then panes, layouts and the rest
alt+` · sv off / sv on	basic view ⇄ full view
ctrl+] then a letter	leader key — every shortcut, in every terminal (ctrl+] ? lists them)
mouse	click a tab or split to focus it · drag the border between splits to resize · wheel scrolls back
ctrl+q · sv exit	quit Shellvisor
sv status	is Shellvisor running here? which shell? which version is running?
sv doctor	checks this terminal: versions (and old copies on PATH), 24-bit colour, UTF-8, shell hooks, mouse, autostart, and — press alt+1 when asked — Option-as-Alt; says how to fix each (--no-keys skips the key test)
sv bug · sv crashes	a crash saves a report on this computer (version, OS, terminal, shell, the panic and a backtrace, with your home folder and user name replaced) — nothing is sent. sv bug shows it and opens a new GitHub issue with it filled in, for you to read and submit; --print only prints it
sv selftest [shell…]	starts your shells (on macOS also the built-in bash 3.2) the way Shellvisor does, with the hooks and your own rc files, out of sight, and checks the prompt and how long it takes, cd tracking, exit codes, the command text and running/finished; paste the output into an issue if something fails
sv power on|off|auto	low-power mode (auto: on while on battery)
sv theme light|dark|auto	Shellvisor's own colours for a light or dark terminal

The window

The top row says where you are and how the machine is doing: the folder, shell and pid on the left; downloads, agents, approvals waiting, live / low power, CPU, memory and a clock on the right. Under it, the tabs: each says what it's doing — a spinner while a command runs (with a download's %), ✔ when a long one finished, ✖ 1 when one failed, ? when a command asks for a password or yes / no, • new output, ! a bell, ◆ an agent. Pinned tabs are just an icon and stay at the left; muted tabs show no marks or toasts. A tab kept in the background leaves the bar for a ◌ 1 in background chip (click it, or alt+N, to bring it back). The bottom row lists the keys for the pane you're in. sv layout focus is one shell with a rail of the other panes and a strip for the folder, branch, job, CPU and memory.

On start, Restore last session? lists the saved tabs with a tick each (ssh panes start unticked): space ticks, ⏎ restores them, n starts fresh. With Restore scrollback on in settings (off by default), each shell's history comes back too, above a restored from the last session line; it's kept as plain text in Shellvisor's state folder (scrollback/, readable only by you) and written every 2 minutes and on quit.

Desktop notifications (settings, on by default): when a command that ran 10 s or more finishes, or an agent finishes, fails or needs your approval, and you aren't looking at it — the terminal window is in the background, or that split isn't on screen — Shellvisor sends a notification (Notification Center on a Mac, notify-send on Linux). Muted tabs don't.

Files pane

Eight views, numbered as in the header — 1 Tree (with indent guides) · 2 Columns (parent | folder | preview; type a name to jump to it, and the commands are capitals there: I insert · C cd · E edit · P preview) · 3 List (NAME, SIZE, MODIFIED, GIT, TYPE; s sorts, space marks files, y copies their paths, m puts mv -i … at your prompt) · 4 Grid (a card per entry: item count, image size or file size, coloured by type; + / − change the card size) · 5 Size (a treemap and bars of what takes the space; x asks, then moves it to the Trash) · 6 Git (staged, changes, untracked and by agent, with the diff beside them) · 7 Find (names or text inside files, with a preview at the line) · 8 Recent (time, who changed it — you or an agent — and what happened; u undoes an agent's edit to that file, after a yes, with the edited copy kept in the Trash); tab cycles. It follows the folder your shell is in, and refreshes after every command. In the dev layout the preview sits in its own box under the tree.

Key
↑↓ j k · ⏎	move · open folder / open file in $EDITOR
→ ← l h · ⌫	expand · collapse · go up a folder
i · c · e	type the path at your prompt · cd there · edit
p / space · J K	preview (with colours; diffs in the git view) · scroll it
/ · . · r · f	filter · hidden files · refresh · stop/start following the shell

In find, type part of a name; tab switches to searching inside files (⏎ runs it). Inside git repos, .gitignore is respected.

System pane

CPU (a history chart and a cell per core), memory, swap, disk and temperature gauges, a Therm row with the temperature history, network, disk I/O, load, Shellvisor's own usage, and the busiest processes with CPU% and MEM% (c / m sort by CPU / memory). It reads nothing while it's hidden, and refreshes every 2 s (5 s in low-power mode).

t switches to the thermal view: every sensor with its critical temperature, a temperature history per group (cpu, gpu, battery, disk), and whether the CPU is being slowed by heat — the clock against its top speed on Linux, macOS's CPU speed limit on a Mac. When the machine gets hot enough to slow down, Shellvisor tells you once (at most every 10 minutes).

Mac users: alt shortcuts need your terminal to send Option as Alt — Terminal.app: Settings → Profiles → Keyboard → Use Option as Meta key; iTerm2: Profiles → Keys → Left Option key → Esc+. The first time Option types a character instead, Shellvisor shows how to fix it for your terminal, with Test again to check. The leader key ctrl+] always works.

Selecting text and right-click: drag in a pane to select its text (only that pane's, even with splits) — it's copied to the clipboard when you let go; double-click selects a word, triple-click a line. Right-click opens a menu: Copy, Paste, Select all, Open link (on a URL), Split side by side, Split stacked. When the program in a pane uses the mouse itself (vim with mouse=a, htop…), hold shift to select. Your terminal's own selection still works too: hold fn while dragging (Terminal.app) or Option (iTerm2), or set mouse: false in the config.

More of what a terminal does, per pane:

• Find (ctrl+] /, or right-click → Find…): searches the pane's whole scrollback, highlights the matches, ⏎/↓ older, ↑ newer, esc closes. Lower-case searches ignore case. ctrl+r switches to a regular expression (^error.*timeout); after ⏎, n / N step to the older / newer match like less, and / edits the search again.
• Clear (ctrl+] k, or right-click → Clear): clears the pane and its scrollback; the shell redraws its prompt. clear itself now empties the scrollback too, like Terminal.
• Option-click on the line you're typing moves the cursor there; ctrl-click a link opens it (terminals don't pass ⌘ with clicks).
• Hints when you might be stuck, on the pane's border: an unclosed quote (quote>), an unfinished command, vim (Esc then :q!), less / man (q), nano, top, a Python or Node prompt, ssh.

Command palette (ctrl+] space): type a few letters to find any action, setting, saved session, layout, tab or serial port, and ⏎ runs it — no shortcuts to remember. It also lists your recent commands (Run: …, ⏎ runs one again in the focused shell), and what you use often and lately comes first.

Broadcast typing (ctrl+] B, or the palette): what you type goes to every shell in the tab at once (several servers, one command); panes show ⇶ broadcast, ctrl+] B again stops it.

Failed command card: when a command exits with an error, a card over its pane shows the exit code, the command, how long it ran and its last lines; ctrl+] c copies the command and error (for an issue or a chat), ctrl+] r runs it again, and ctrl+] ? asks an agent (Claude Code, Codex, Gemini or Aider, whichever is installed) why it failed — it gets the command, exit code and last lines, and is told not to change any files. Programs whose exit code isn't an error (vim, less, grep, diff…) and ctrl+C don't get one; turn it off in settings.

Saved sessions, logging and more (like PuTTY):

• sv ssh save prod deploy@10.0.0.5 -p 2222 -i ~/.ssh/prod -L 8080:localhost:80 saves a connection (keepalive every 30 s unless -k 0; -- cmd runs a command instead of a shell); sv ssh prod opens it in a new tab named after it; sv ssh (or ctrl+] S, or the tab menu) lists your saved sessions and the hosts in ~/.ssh/config; sv ssh rm prod. Your own ssh, keys and config are used.
• Port forwards (ctrl+] P, or sv ssh forward [NAME]): every saved session with its local (-L), remote (-R) and SOCKS (-D) forwards — listening or not, connections, bytes in and out — and Add a forward without reconnecting. A busy port says what holds it (1080 is used by ssh -D (pid 9112)) and p moves to the next free one; ⏎ opens a local forward in the browser, c copies its address, space pauses, x closes it. Each forward runs its own ssh -N (your keys and config; it needs a key or ssh-agent login) and Shellvisor relays its connections, which is how it counts them; the ssh you type in is left alone. Forwards saved with "open on login" start with the session's tab and stop with it.
• Every host at once: mark sessions with space in the picker (a marks all) and ⏎, or sv ssh all [NAME…]: they open in one tab, a split each, with broadcast on, so what you type goes to every server.
• When an ssh session drops, ctrl+] R (or right-click → Reconnect) runs it again.
• Duplicate session (right-click, tab menu): a new tab in the same folder, reconnecting to the same server.
• Log to file (sv log start [file], sv log stop, right-click): everything the pane shows, as plain text (colours and progress-bar redraws taken out), in ~/shellvisor-logs/ by default, each line starting with the time ([22:14:03] ; --plain leaves it out). The pane title shows ⏺ logging. sv log list lists the logs; sv log view [N|file] opens one in the table viewer (time and text columns: filter, sort, copy), or in your pager outside Shellvisor.
• Serial consoles: sv serial lists the ports (USB adapters, boards); sv serial /dev/tty.usbserial-1410 115200 opens one in its own tab (default 115200 baud). Keys go straight to the device; ~. at the start of a line quits, like cu.
• Remote files (ctrl+] F, or the palette) over the tab's ssh session: a pane listing the server's folders; ⏎ opens, ⌫ goes up, d downloads into your local folder, and dropping files from Finder on the pane uploads them. It reuses the session's options (port, key, user, jump host) with one shared connection; it needs a key or ssh-agent login (a password prompt can't be answered in the background).
• Right-click pastes like PuTTY if you set Right-click: paste in settings (ctrl+right-click still opens the menu); middle-click always pastes.

ls as a table

Inside Shellvisor, ls (and ls <folder>, ls -a) prints a table like nushell's — name, type, size, modified — with folders in your folder colour, and F4 explores it. ls -l and any other flag, ls in a pipe or script, and command ls are the real ls. Turn it off in settings (alt+s).

Downloads & installs

Commands that download or install — git clone/pull, npm/pnpm/yarn/bun install, pip, uv, poetry, conda, brew, apt, docker pull, cargo, go, gem, curl, wget, rsync, ollama pull, huggingface-cli download and more — get the loading ring and a thin progress bar in the pane title, the ring in the tab, job: ◴ pip 52% · ETA 9s in the status bar and a badge at the top right (◴ 2 downloads · 62% · 6.1 MB/s). Speed and time left come from what the tool prints (git, curl, wget, pip, tqdm…); otherwise the time left is worked out from the progress:

bash · ~/work · ◴ git clone ━━━━━━╸━━━ 62% · ETA 6s

• The files pane puts the spinner and % on the folder or file being filled (the clone, node_modules, the downloaded file).
• Coding agents that run an install show it on their column too (spotted on screen: Claude Code's Bash(npm install), $ … lines).
• When it's done the tab shows ✔ / ✖ for 5 s and a toast says so (✔ git clone finished · 412 MB in 38s); for a clone or a download Shellvisor can find, c cds into it and o opens it in the files pane (for about 12 s, while the toast shows, and only at an empty prompt — once you've typed something, c and o are just letters; ctrl+] c / o always work).
• ctrl+] j (or sv activity, or a click on the badge or the status bar) opens the activity list: a card per download with the command and where it comes from, the bar, the tool's own progress line, and amount / speed / time left; the last 20 finished below. ⏎ goes to its shell, p pauses a running one (and resumes it), x cancels it like ctrl+C, c / o as above, x on a finished one clears the list. Downloads from earlier sessions are listed below (earlier · 2 h ago), and r runs any finished one again in the focused shell.
• Settings: spinner style (ring ◴, braille ⠋, bar ▰▱▱▱) and bar or percent only.

Settings

alt+s (or sv settings) opens a settings screen with a live preview:

• the colour of the folder in your prompt (and bold) — Shellvisor's hooks colour %1~ / %~ (zsh) or \W / \w (bash) in whatever prompt you have, no dotfile editing; prompts drawn by tools like starship are left as they are
• the colour of the commands you type — blue by default, so your commands stand apart from their output, which stays in the normal text colour; none turns it off. With zsh-syntax-highlighting its colours win
• the colour of folders in lists — the files pane and ls / sv tables
• these colours are your terminal's own 16 (plus orange), so the profile decides the exact shade: with the Shellvisor profile, cyan is the design's #6cc9d6 — the same as a prompt that draws its folder in cyan
• ls as a table on/off, table borders (rounded or plain), theme
• loading spinner style and download progress as a bar or percent only
• right-click: menu (default) or paste (like PuTTY)
• mouse: shellvisor (default — click splits, drag borders, wheel scrollback, select text, right-click menu) or terminal (the terminal keeps the mouse: its own selection, right-click menu with Mark / Bookmark, ⌘-click links; you move between splits with keys)
• colours: auto, 24-bit or 256. Terminal.app shows 24-bit colour from macOS 26; before that it has 256 colours, which have no very dark blue — Shellvisor then leaves the page to the terminal's own background, and sv terminal-colors profile imports a ready-made Shellvisor profile for Terminal.app (packaging/terminal/Shellvisor.terminal: background #0b0e12, text #d6dbe3, the 16 ANSI colours from the design, JetBrains Mono 14) — make it the default in Terminal → Settings → Profiles. sv terminal-colors alone just sets your current profile's background and text (sv terminal-colors undo puts yours back). Typing hex values into the colour picker yourself? Set it to sRGB first, or Display P3 shifts them
• dark background: design (default) paints Shellvisor in the design's palette — a very dark blue-grey page #0b0e12, panels #11151b, shells on #0e1217, borders #262c36, text #d6dbe3, amber / cyan / green / red accents — or terminal to keep your terminal's own background. Programs inside shells keep their own colours; basic view always looks like your plain terminal. Terminals without 24-bit colour (e.g. older Terminal.app) get the nearest 256-colour shades

Choices are saved in ~/.local/state/shellvisor/settings.yaml (your config.yaml is never rewritten) and shells pick them up at the next prompt.

Data commands

sv also turns command output into tables you can filter and sort — nushell-style, from inside bash or zsh:

sv ls | sv where size gt 1mb | sv sort-by size -r     # stage by stage…
sv 'ps | where cpu gt 5 | sort-by cpu -r | first 10'  # …or one quoted pipeline
sv open package.json | sv get dependencies
sv open sales.csv | sv group-by country
ps aux | sv from ssv | sv where user eq root | sv to csv

Sources: ls ps host df ports env history open git-log git-status. Filters: where select reject sort-by reverse first last skip uniq get group-by count sum avg min max columns describe. Formats: from json|csv|tsv|yaml|toml|ssv|lines, to json|jsonl|csv|tsv|md|yaml|text. sv data lists them all.

On the terminal you get an aligned table; between sv stages rows travel as JSON lines, so jq works on them too.

Inside Shellvisor, F4 opens the last table full-screen: ←→ pick a column, s/S sort, / filter (text, or a condition like size > 1mb), c / J / m copy as CSV / JSON / Markdown, ⏎ types the cell at your prompt. It stays quick with 100k rows. alt+; opens a command bar for the same pipelines without the sv prefix — the result opens in the table viewer, or alt+⏎ puts it at your prompt.

Flow

sv flow 'cat access.log | grep " 500 " | cut -d" " -f7 | sort | uniq -c | sort -rn'

runs the pipeline with a meter between every stage (sv flow save errors '…' saves it, sv flow errors runs it again, sv flow list, sv flow rm errors) — lines and bytes in and out, % kept, rate, the stage holding everything up (◀ slowest), each stage's errors and the last lines of output — and prints a summary at the end. The Flow pane (F8, or sv layout data; F5 to zoom) shows it live as on the design board: a card per stage (status, in / out / rate / kept, a sparkline, its latest line) with arrows showing what each keeps, a throughput chart between stages over the last 30 s, the slowest stage and why, the output, and stderr from every stage, tagged; narrow panes get a compact table; when nothing is metered it shows the job your shell is running right now: its processes, CPU, memory, read/write rates and pipes (rates and pipes on Linux).

Agents

_{The agents in this screenshot are a scripted stand-in; any CLI agent fills the columns the same way.}

sv agent new claude --name api 'add a POST /alerts endpoint'   # or codex, gemini, aider
sv agent new --cmd 'ollama run llama3' --name local            # any other agent CLI
sv agents                                                      # all agents as a table
sv connect                                                     # installed CLIs, logins, MCP servers, ssh hosts

Each agent gets a column in the agents tab (F9). In a git repository it works in its own worktree and branch (.shellvisor/worktrees/<name>, branch agent/<name>), so agents never edit the same checkout — or yours. The top of each column shows its state (working ⠋, ⚑ approval, finished, paused), its CLI and worktree, how long it has run and its tokens (Claude Code and Codex, read from their own session logs), and its task; the bottom shows the files it changed with +/− lines. Type in a column to message that agent. On a wide screen the tab also has an orchestrator column on the left — the goal, the task graph, the first approval waiting (allow / deny / always), files two agents both touched — and a message bus of who handed what to whom underneath. ctrl+] T tells every agent the same thing; ctrl+] Z / U pause and resume them all; ctrl+] Y turns on sync scroll, so scrolling one column scrolls them all. The files pane marks files agents have touched (◆ name).

The New agent form (shift+F9) has a card per CLI (the ones not installed are dimmed), the name and folder, its own worktree or the shared folder, which shell it runs in, the first instruction, approvals (ask for installs, network and push, or full auto) and a stop after N minutes limit that pauses it. If you already started claude (or another CLI) in a shell, it offers Attach as column.

MCP servers (ctrl+] M)

sv mcp lists the MCP servers your agents can use — from Claude Code, Codex, Gemini and the project's .mcp.json — and, inside Shellvisor, opens two screens. The first shows each server's state from a real handshake, its tools, resources and prompts, which secrets are set (never their values) and who uses it; t tries a tool with a form built from its input schema. A ⚠ marks a tool whose description changed since it was last seen (a changed description can quietly change what an agent does with it); d shows the old and new text. The tabs show how many tokens each server's tool list takes in every agent's context. ⏎ on a traffic row (or l on a server) shows one call in full: the request and the result as pretty JSON, when, which agent, how long, the permission rule that let it through, and the line in the agent's log; next to it the server's process (cpu, memory, how long it has run, which agent started it) with s stop / r restart / k kill, what to do if it crashes, and its log (what Claude Code logged about it, plus every call and check), with / search and f follow. Press 2 for live traffic (every MCP call in Claude Code, Codex and Gemini CLI logs, with size and time), a permissions grid (allow / ask / never per server or tool, per agent) and Add a server, which checks the server before it writes it to each agent's config.

Reviewing an agent's work (board 21)

sv agent diff api (or ctrl+] D in its column, or d on the agent board) shows what it changed before you merge: its files with lines added and removed (* not committed yet), its commits, and checks — the tests it last ran (from its own output), whether another agent changed the same files, files you changed too. The diff is coloured, unified, side by side or the whole file (v), n / N jump between changes, ↑↓ between files. m merges into your branch, S squashes it into one commit, t sends the agent a message, o shows the file in the files pane, e opens it in $EDITOR at that line, x (twice) throws the branch and worktree away. Approve for a while (A): its approval prompts answer themselves for 15 minutes, an hour or the rest of its task, for the kinds you tick (read / edit / test / lint, install, network / push / delete).

Agents that start agents

Every shell inside Shellvisor can reach it over a private socket, so an agent (or you, or a script) can run a team:

sv agent spawn --name tests 'write tests for the alerts endpoint'   # from inside an agent: a sub-agent
sv agent send tests 'cover the 429 case too'                         # type a message into it
sv agent wait tests                                                  # until it has finished its task
sv agent tree                                                        # every agent, under its parent
sv agent logs tests -f                                               # follow what its screen shows
sv agent pause|resume|stop api --tree                                # an agent and all its sub-agents
sv agent log                                                         # who spawned and messaged whom

A sub-agent works in its parent's folder (and worktree) and inherits the approvals its parent set to "always". Trees are limited — by default 3 levels deep, 10 agents running, 3 sub-agents per agent (agents.limits in config.yaml); a spawn over a limit is refused with the reason, which the asking agent sees. When Claude Code runs its own helper agents (its Task tool), the column title shows them as +N helpers and sv agent tree lists them under it.

Teams: team.yaml

A team file says who is on the team, who may start whom, and what happens when something goes wrong. sv agent run --init writes a starter .shellvisor/team.yaml:

team:
  name: price-alerts
  budget_tokens: 2000000   # past this, every agent of the team pauses
  max_agents: 10
  max_depth: 3             # lead › agent › sub-agent
agents:
  - id: lead
    cli: claude
    role: orchestrator     # gets the goal, and is told who it can start
    can_spawn: [api, tests]
  - id: api
    cli: claude
    worktree: true
    max_children: 3        # may start sub-agents of its own
    approve: [install, network]   # answered "always" for it
    mcp: [github]          # checked: is this MCP server set up?
  - id: tests
    cmd: ./my-test-agent.sh   # any command; it gets the task in $SHELLVISOR_TASK
    start: after:api       # now (default) · after:<id> · spawned
on:
  - event: tests.failed    # started, done, failed, exited, needs_approval, or your own
    send: api
    text: "fix failing tests: {log}"   # {log} {agent} {event} {goal}

sv agent run team.yaml 'add price alerts' --dry-run   # check it and show the plan
sv agent run team.yaml 'add price alerts'             # start it
sv agent emit failed '2 tests failed'                 # from an agent: fire tests.failed
sv agent budget                                       # tokens used of the budget
sv agent budget 3M                                    # raise it — resumes what the cap paused
sv agent stop --all

Mistakes are reported before anything starts, with the agent and field (agents[2] (tests): start after:db — no other agent called db). Members listed in someone's can_spawn start when that agent spawns them; an agent may only start the names in its can_spawn, or any sub-agent if it has max_children. The budget counts tokens, not money — Shellvisor reads them from Claude Code and Codex session logs, and other agents can report theirs with sv agent usage <tokens>.

Agent board (alt+g)

Four views over everything agents are doing (tab switches; sv agent board tree|timeline|log opens one):

• Plan — type a goal (or run sv agent plan 'add price alerts'). A planner reads the repository and proposes tasks in stages, with scopes, estimates in tokens and overlap risks. Edit a title (e), reassign the agent CLI (a), drop a task (x), set how many run at once (+/-), a token budget (b) and the approvals for this dispatch (p: auto answers read, edit, test and lint and refuses delete; ask asks for everything; full auto answers everything but delete), re-plan (r). ⏎ dispatches everything; s runs one stage at a time (⏎ releases the next). Each task gets its own worktree and branch; once all are done a reviewer agent compares the branches and reports.
• Tree — who spawned whom, status, tokens and files, totals per branch, and the selected agent's details: spawned by, via, worktree, its instruction and latest output. ← / → fold and open a branch, i messages the selected agent, + starts a sub-agent under it (type its task), c promotes a sub-agent to a column of its own, p pauses or resumes a branch, k stops it, d reviews it, m merges an agent's branch into your checkout, ⏎ jumps to its column.
• Timeline — every agent over time: working, waiting, approval, paused, done.
• Log — spawns, messages, events, refusals and budget stops.

The planner is claude -p, codex exec - or gemini, whichever is installed; set agents.planner in config.yaml to use another command (it gets the prompt on stdin and prints JSON).

Ready-made teams

sv agent templates lists teams you can start without writing a file — feature (lead splits the goal · builder · tests · reviewer), bug-hunt (reproducer writes a failing test · fixer · verifier), review (two read-only reviewers), refactor (planner and two parallel workers, tests after) and docs (writer · checker that runs every example):

sv agent run --template bug-hunt 'login fails when the email has a +'
sv agent run --template feature --cli codex 'add CSV export' --dry-run
sv agent run --init --template review           # start from one: writes .shellvisor/team.yaml
sv agent template save my-team                  # your own (from .shellvisor/team.yaml), next to the built-in ones

The New agent form (shift+F9) has a team row: pick a template with ← → and the instruction becomes the team's goal.

Tokens, replay and the merge queue

• Tokens per step. Once a plan is dispatched, every step shows the tokens it used (its agent plus the sub-agents it started), the heaviest is marked ▲, and steps that went past their estimate say by how much — the first prompts worth tuning.
• Replay. Each agent is recorded while it runs: its screen when it changes, status changes, the files it touched and every approval with who answered it. sv agent replay NAME (or R on the board's Tree) steps through it: ← → frame by frame, ] [ to the next event, space plays. Recordings stay on this computer (the newest 40; agents.replay: false turns them off).
• Merge queue. sv agent queue (or Q on the Tree) takes the finished agents one at a time: commits what they left uncommitted, rebases their branch onto yours, runs the tests (--test 'cmd', agents.test in config.yaml, or cargo / npm / pytest / go / make, whichever the project uses) and fast-forwards your branch. It stops at the first conflict (the rebase is undone and the files named) or failing test, so everything merged has passed. --dry-run shows what it would do.

When agents ask for permission, alt+a lists every waiting prompt; y / n / a answers it — Shellvisor types the right key for that CLI. Already running an agent in a normal tab? sv agent attach turns that split into an agent column.

Service panes

Open them with sv pane …, the layout editor (alt+e) or the palette:

• Ports (sv pane ports) — what is listening, the process and the tab that started it. ⏎ opens it in the browser, t goes to that tab, k stops it (K kills), c copies the URL.
• Docker (sv pane docker) — containers from docker or podman. l follows a container's logs in a split, x opens a shell inside it, s starts / stops, r restarts, a shows stopped ones too.
• Logs (sv pane logs app.log worker.log, or every *.log here and in logs/) — follows several files at once, a colour per file, errors red and warnings amber. / filters by text or with the data commands (where level == error, where message =~ timeout | last 50), F4 opens what is shown in the table viewer, space pauses, a / x add or remove a file.
• HTTP (sv pane http http://localhost:3000/alerts) — a small request runner: m method, u URL, h headers, b body, ⏎ sends. The answer shows status, time, size and pretty JSON; ↑ ↓ go through earlier requests; c copies it as a curl command.

Configuration

~/.config/shellvisor/config.yaml — every key is optional:

shell: zsh              # zsh, bash or a full path (default: $SHELL)
scrollback_lines: 5000  # lines of history kept per shell
shell_integration: true # report folder / command / exit code to Shellvisor
mouse: true             # wheel scrolls history
start_view: full        # full (tabs, status bar) or basic (just the shell)
restore: ask            # reopen last session's tabs: ask, always or never
low_power: auto         # slower refresh + animations: auto (on battery), on, off
theme: auto             # Shellvisor's own colours: auto (from $COLORFGBG), dark, light — also: sv theme
agents:
  worktree: true        # each new agent works in its own git worktree + branch
  approvals:            # answer agents' permission prompts for you: auto | ask
    test: auto          # read edit test lint install network push delete command
  limits:               # how big agent trees may grow
    max_depth: 3        # sub-agents of sub-agents …
    max_agents: 10      # running at once
    max_children: 3     # sub-agents per agent
  planner: claude -p    # turns a goal into a task plan (alt+g → Plan)
keys:                   # change or turn off any shortcut (F1 lists them all)
  new_tab: alt+n
  rename_tab: none      # frees alt+r for your shell

Keys are written like alt+t, ctrl+], f7, alt+shift+left, shift+pageup. Shellvisor refuses keys without ctrl/alt (they would stop you typing) and tells you about clashes.

Sessions

Shellvisor remembers your tabs, splits, tab names, folders and files/system panes in ~/.local/state/shellvisor/session.yaml as you work, so it survives closing the terminal window. Next time it asks whether to reopen them. Commands are never re-run.

How the shell integration works

Shellvisor adds small hooks to your shell without editing your dotfiles:

• zsh starts with a temporary ZDOTDIR whose files source your real .zshenv, .zprofile, .zshrc and .zlogin, then add precmd/preexec hooks.
• bash starts with --rcfile, which runs your normal login files, then adds a PROMPT_COMMAND and a DEBUG trap. Works with macOS's bash 3.2 and newer bash. Note: this replaces an existing DEBUG trap.
• Other shells run fine, just without the hooks.

The hooks print invisible escape sequences (OSC 7 for the folder, Shellvisor's own OSC 7770 for the rest) that Shellvisor reads and removes. Command history with exit codes and durations is kept in ~/.local/state/shellvisor/history.jsonl.

Development

cargo test --all                                       # unit + end-to-end tests (real bash/zsh in a PTY)
cargo build --release
cargo run --release --example bench -- --check         # performance budget
SV_FUZZ_ROUNDS=50000 cargo test --release random_input # longer random-input run (weekly in CI)

Every release is measured on the same GitHub runner and charted:

• docs/ARCHITECTURE.md — how it is built
• docs/ROADMAP.md — phases P0 → P6

License

Apache License 2.0 — see LICENSE and NOTICE.