Auto session naming

What it is

New agent sessions start with a generic title until Ghostex learns a better name. First-prompt auto naming sends your opening message to a headless title-generation agent and applies the result as the session title. Manual Generate Name (Cmd+R → Generate Name) runs the same pipeline on demand for an existing session.

Many agents also sync titles from their terminal window (Codex, Claude, Cursor CLI, etc.). Ghostex merges terminal-synced titles with generated names and avoids overwriting meaningful titles with redundant rename commands.

First-prompt flow

• You submit the first user message in an agent session.
• gxserver receives the prompt plus firstPromptTitleGenerationAgent from Settings.
• A headless agent summarizes the prompt into a short title (30 second timeout).
• The native terminal shows a blocking Generating title overlay while input is suppressed.
• gxserver stages the rename command (e.g. /rename <title> for Codex, bare /rename for Claude).
• macOS submits the staged command through sendTerminalEnter — not typed carriage return.
• Sidebar cards show Generating title until gxserver clears isGeneratingFirstPromptTitle.

Title generation agent settings

Settings → General (session titles section) configures title generation separately from defaultPromptAgentId:

Settings previews the exact headless command Ghostex will run:

# Codex (default)
codex exec --ephemeral --skip-git-repo-check -m gpt-5.4-mini ...

# Cursor CLI
cursor-agent --print --yolo --trust --output-format text '<title generation prompt>'

# Claude
claude -p --model haiku <<'PROMPT'
<title generation prompt>
PROMPT

# Grok Build
grok -p --model grok-composer-2.5-fast --output-format plain ...

Terminal title sync

Agents that update their own terminal titles can drive sidebar cards without generated renames:

• Supported: Codex, Claude, Cursor CLI, Copilot, Gemini, OpenCode, Pi, Antigravity, Hermes, Qoder, Rovo Dev, and aliases like Claude Code or cursor-agent.
• First-prompt generation preserves meaningful terminal-synced titles instead of sending redundant /rename commands.
• Codex resume validates exact thread ids and falls back through filtered title lookup — internal codex exec title jobs do not overwrite resume identity.
• zmx title streams heartbeat spinner frames slowly enough to preserve working status without flooding gxserver.

Manual rename

• Cmd+R (renameActiveSession) opens the rename modal for the focused session.
• Session context menu → Rename opens the same modal with the current title.
• Rename → Generate Name runs title generation with the modal's agent choice.
• Generate Name keeps the Generating title overlay until the rename is applied or submitted.
• renameSessionOnDoubleClick (default: false) opens rename when you double-click a session card.
• ghostex rename-session <sessionId> <title> renames from CLI; Android uses --session-id --title flags.

Cancellation & retries

• Cancelling first-prompt title generation prevents a stale result from renaming the session later.
• A subsequent user prompt can retry title generation after cancellation.
• Claude first-prompt naming stages bare /rename; gxserver exposes a separate staged-command submit flag from titleSource: generated.
• Codex title generation uses --ephemeral so generated titles never create restorable Codex sessions.
• Internal prompt jobs (board titles, etc.) run as ephemeral work and do not appear as restorable sessions.

Bundled skill

Ghostex ships $ghostex-generate-title as a bundled agent skill. Install it from Settings → Agents or the CLI so external agents can request title generation through the same gxserver pipeline.

Cursor Agent can also generate session titles, Git prompts, worktree prompts, and Project board ticket titles when it is the selected prompt agent.

CLI commands

Tips

• Use Codex for title generation if you already rely on Codex hooks — ephemeral exec avoids polluting session history.
• Switch to Grok Build or Cursor CLI in Settings if you prefer those models for short summarization tasks.
• If titles feel generic, edit customSessionTitleGenerationCommand with a tighter system prompt placeholder.
• Watch the sidebar Generating title indicator — if it sticks, check gxserver logs; generation times out after 30 seconds.
• For Claude sessions, expect bare /rename staging — Ghostex submits Enter after gxserver applies the command text.