Agent CLI support

What it is

Ghostex treats each supported agent CLI as a launch engine. When you start a session from a project header, the Quick section, or ghostex create-agent, Ghostex runs the configured command inside a Ghostty terminal pane and tracks the row in gxserver so every client — macOS, Android, iOS, TUI, and SSH attach — sees the same status and resume identity.

Agents are not embedded GUIs (except T3 Code, which uses a dedicated pane type). Most launch engines are standard terminal CLIs wrapped with optional zmx persistence, agent hooks, and Accept All permission flags.

Built-in launch engines

These agents appear in the default launcher unless hidden. Order in Settings reflects the daily-selection flow: T3 Code first, then Codex, Claude, Cursor CLI, Pi Agent, OpenCode, Gemini, Copilot, Factory Droid, Grok Build, Antigravity CLI, and Amp CLI.

Additional restorable agents are available when you enable or configure them: Rovo Dev (acli rovodev run), Hermes Agent (hermes), CodeBuddy, Qoder (qodercli), Kiro CLI (kiro-cli chat --agent ghostex), and OMP (omp).

How Ghostex tracks agents

• Each session row stores agentId, launch command, icon, and optional Accept All mode.
• gxserver owns runtime Accept All flag insertion and command shaping so macOS, CLI, TUI, and mobile cannot diverge.
• Installed agent hooks report working, attention, idle, first-prompt, and resume metadata directly to gxserver.
• Terminal-title sync keeps sidebar cards aligned with live agent titles for Codex, Claude, Cursor CLI, Copilot, Gemini, OpenCode, Pi, and others.
• Live-process identity repair recognizes path-based agent executables so one terminal cannot inherit another row's status.

Accept All settings

Settings → Agents includes a global agentAcceptAllEnabled toggle. Per-agent Accept All modes are inherit, enabled, or disabled. gxserver applies the correct vendor flag at launch time.

Agent hooks

Ghostex can install gxserver-managed hooks for supported CLIs. Hooks write sidecar status that gxserver ingests even when the macOS sidebar is not actively polling — this is how Android and iOS receive working/attention/idle updates over SSH.

First launch and Settings → Agents offer Install Agent Hooks. Kiro CLI and OMP are hook-supported but hidden from the primary launcher by default. After installation, hook status appears in the Agents settings panel.

Configure custom agents

Use the configure-agent modal or CLI to add custom launch engines with your own agentId, display name, command, and icon. Custom agents participate in sidebar ordering via storedOrder and can be saved with:

ghostex save-agent --agent-id my-agent --name "My Agent" --command "my-cli"

Run a configured button from the shell:

ghostex run-agent my-agent
ghostex create-agent codex --group-id <project-id>
ghostex click-button agent codex

Default prompt agent

Settings → Agents includes defaultPromptAgentId (default: codex). Automated flows — Git helper prompts, Project board Start Work, and worktree first prompts — use this agent instead of hardcoding one vendor.

This is separate from session title generation, which has its own agent selector documented on the Auto session naming page.

CLI commands

Short alias: gx replaces ghostex for all of the above when installed.

Tips

• Hide built-in agents you do not use from Settings → Agents; hidden agents stay restorable if previously configured.
• Reorder agents in Settings so your daily driver appears first in project headers and Quick.
• If status flickers during spinner-heavy activity, ensure hooks are installed — gxserver prefers hook sidecars over title-stream heuristics.
• T3 Code resolves the packaged runtime path on macOS; do not replace its launch command unless you know the desktop bootstrap requirements.
• Codex title-generation and board-title jobs run as ephemeral internal work so they never create restorable Codex sessions.