codex-ghostty-title

Codex CLI lets you rename a session with /rename, but Ghostty does not automatically pick up that new name for the tab. This hook watches the active Codex session name and updates the Ghostty tab/window title when the Codex session is renamed.

In plain terms: run Codex in Ghostty, rename the Codex session, and the terminal tab follows.

What It Does

• Installs a Codex lifecycle hook.
• Starts a small watcher for the active Codex session.
• Reads the current session title from Codex local state.
• Falls back to session_index.jsonl when needed.
• Sends terminal title escape sequences that Ghostty understands.

This is a workaround until Codex has native terminal title support for session renames.

Requirements

• macOS or Linux
• Python 3.9+
• Codex CLI with hooks enabled
• Ghostty

Install

Clone the repo, then run:

./install.sh

The installer:

• copies codex_ghostty_title.py to ~/.codex/hooks/
• merges hook entries into ~/.codex/hooks.json
• backs up ~/.codex/config.toml
• sets terminal_title = [] under [tui]

After installing:

1. Restart Codex CLI.
2. Run /hooks.
3. Review and trust the new hooks.
4. Use /rename in Codex.

Why terminal_title = [] Is Needed

Codex has its own terminal title renderer. If it is left enabled, it can overwrite the title set by this hook. The installer sets:

[tui]
terminal_title = []

That leaves terminal title control to the hook.

Ghostty Note

Do not set a fixed Ghostty title = ... in your Ghostty config if you want dynamic titles. A forced title makes Ghostty ignore title updates from programs running inside the terminal.

Manual Hook Configuration

If you do not want to use the installer, copy the script manually:

mkdir -p ~/.codex/hooks
cp codex_ghostty_title.py ~/.codex/hooks/
chmod +x ~/.codex/hooks/codex_ghostty_title.py

Then add the hook configuration shown in examples/hooks.json and set the TUI title setting shown in examples/config.toml.

How It Works

Codex hooks do not currently expose a dedicated "session renamed" event. This tool uses available lifecycle hooks to start a watcher, then polls Codex local session state for the active session title. When the title changes, it writes OSC 0, OSC 1, and OSC 2 title escape sequences to the terminal.

Uninstall

Run:

python3 ~/.codex/hooks/codex_ghostty_title.py --uninstall

This removes the hook commands from ~/.codex/hooks.json. It does not delete the installed script or restore terminal_title; restore your backed-up config.toml if desired.

Tests

python3 -m unittest discover -s tests

License

MIT