Appearance
tmux tools and agent teams
Some tools only know how to open panes through tmux. Claude Code's agent teams are the main one: in split-pane mode each teammate gets its own pane, but only under tmux or iTerm2. Ghosted can stand in for tmux, so those tools open real Ghosted panes instead.
Turn it on
In ~/.config/ghosted/config.toml:
toml
[terminal]
tmux_compat = trueThen ghosted server reload-config. Panes opened from then on get it; open a new pane (or tab) for an existing one.
To turn it on for one pane only, open the pane with GHOSTED_TMUX_COMPAT=1 in its environment (ghosted pane split --env GHOSTED_TMUX_COMPAT=1 …). GHOSTED_TMUX_COMPAT=0 turns it off for a pane when the setting is on.
Claude Code agent teams
With tmux compatibility on, start Claude Code in a pane with split-pane teammates:
sh
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude --teammate-mode tmux(or set "teammateMode": "tmux" in ~/.claude/settings.json; "auto" works too). Each teammate opens as a Ghosted pane beside the lead, named after the teammate, and you can click into it to talk to that teammate.
Ghosted doesn't recolour pane borders or rearrange the layout the way tmux would; teammates split the lead's pane like any other split.
How it works
A pane with tmux compatibility has:
- a
tmuxcommand first on itsPATHthat runsghosted tmux, TMUXandTMUX_PANEset the way tmux sets them, so programs know they are "inside tmux".
ghosted tmux understands the commands tools use to manage panes: split-window, send-keys, capture-pane -p, display-message -p, list-panes, list-windows, select-pane, respawn-pane and kill-pane. Pane ids look like tmux's (%12) and stay the same while a pane lives. Anything else (layouts, options, copy mode) fails with a message saying so, rather than pretending to work.
Commands that manage whole tmux sessions (tmux, new-session, attach, ls, …) go to your real tmux if you have one, so you can still run tmux inside a Ghosted pane.
If you use real tmux too
Your shell moves the shim down
PATH. On macOS, login shells reorderPATH, andbrew shellenvputs Homebrew first; if real tmux is installed there it wins. Check withcommand -v tmuxin a pane: it should end intmux-shim/tmux. If not, add this to the end of your~/.zshrc(or~/.bashrc):sh[ -n "$GHOSTED_TMUX_SHIM_DIR" ] && PATH="$GHOSTED_TMUX_SHIM_DIR:$PATH"Inside a real tmux session started from such a pane,
tmuxcommands go to that real tmux, as before.Tools that keep their own detached tmux sessions (Claude Squad and similar) run them in your real tmux, not as Ghosted panes.
tmux compatibility isn't available on Windows yet.