Ghostex CLI

The Ghostex CLI connects to the running app (or gxserver control plane) to list sessions, attach, send messages, automate sidebar actions, and drive embedded browser panes. It is bundled with the macOS app and auto-linked on startup.

ghostexgxgxserver

Invocation

ghostex
gx
ghostex <command> [args...]
gx <command> [args...]

# Development / debugging bridge (requires running Ghostex app)
bun run cli -- state
node scripts/ghostex-cli.mjs state

Public docs use ghostex and gx. The debug CLI in scripts/ghostex-cli.mjs talks to the native WebSocket bridge on 127.0.0.1:58743 for reproducible UI testing.

Session commands

Option	What it does
`sessions \| s \| ls`	List running terminal sessions.
`find \| f`	Search agent prompt history with bundled zehn.
`attach \| a [selector]`	Attach to a provider session or open the picker.
`resume \| r`	Alias for attach.
`kill \| k <selector\|all>`	Close one session or every listed session.
`sleep / wake`	Sleep or wake sessions by selector.
`android-check`	Verify this Mac is ready for Ghostex Android (CLI, zmx, sessions).

Attach

gx sessions
gx a 1
gx attach --session-id <id> --project-id <id>
gx attach --session-id <id> --project-id <id> --prompt-editor monaco

Attach uses stored tmux, zmx, or zellij provider sessions when present. Without provider metadata it runs the supported agent resume command. The --session-id --project-id flag form is used by Android, iOS, and desktop remote SSH attach.

Selectors: alias, session id, provider session name, title, or project:title. Numeric aliases come from the last sessions list.

Workspace commands

ghostex state
ghostex create-session "Shell" --input "pwd"
ghostex create-agent codex --group-id group-2
ghostex send-message "Investigate logs" "please summarize output"
ghostex switch-project --path /Users/you/dev/project
ghostex add-project /path/to/repo --name my-project
ghostex focus-session --index 0

Input and readback

Option	What it does
`send-text`	Type text into a session.
`send-enter`	Send Enter.
`send-key`	Send ctrl-c, escape, tab, or arrows.
`send-message`	Type text and Enter.
`read-text`	Read terminal buffer (--lines, --visible, --json).
`rename-session`	Rename a session.
`rename-command`	Stage /rename <title> and submit Enter.

Browser namespace

gx browser --help
gx browser mcp
gx browser install-skill
gx browser open https://example.com --project-path "$PWD"

Skill install namespaces

gx browser install-skill
gx computer-use install-skill
gx agent-orchestration install-skill
gx generate-title install-skill
gx bd --help

gxserver lifecycle

gxserver is the background control plane for projects, sessions, zmx lifecycle, auth, and remote access. Closing the macOS app does not stop gxserver.

gx server start
gx server status --json
gx server stop
gx server stop-all

gx server stop stops only the control plane — not zmx/tmux/shell sessions.
gx server stop-all kills gxserver-tracked zmx sessions, then stops the control plane.

Global flags

Option	What it does
`--port <number>`	Native bridge port (debug CLI).
`--json`	JSON output where supported.
`--timeout <ms>`	Bridge request timeout.
`--ungrouped \| -u`	Flat session list with project name prefix.

Related docs

TUI mode

Remote SSH sessions

Browser use

Cross-model orchestration