Show HN: Agenttab – Status Icons for Claude Code, Codex and OpenCode Tabs

Developer marciob released agenttab, a macOS tool that displays AI agent state as icons in terminal tab titles for Claude Code, Codex, and OpenCode. The tool maps states to icons — a blank title when the agent waits for a prompt, ◐/◑ while working, ⚠ when awaiting permission, and the shell title when the session ends — and installs via a curl script into ~/.local/bin. It requires jq and, for Codex 0.157 or later, lsof, and works by adding hooks to each agent's settings file.

agenttab shows the state of an AI agent in the title of its terminal tab. It works with Claude Code, Codex, and OpenCode. The title is <state icon <text , for example ◑ Terminal title customization . | Icon | State | |---|---| | none | The agent waits for your next prompt. | | ◐ ◑ in turn | The agent works. | | ⚠ | The agent waits for your permission. | | the shell title | The session ends. | The text is the title of the conversation. If the conversation has no title, the text is the name of the directory. - macOS. Linux can work, but nobody has tested it. - jq . Install it with brew install jq . - lsof , only for Codex. macOS has it. 1. Run the installer: curl -fsSL https://raw.githubusercontent.com/marciob/agenttab/main/install.sh | sh The installer puts agenttab in ~/.local/bin . It does not change the settings of an agent. From a clone, run ./install.sh . Then git pull updates the installed files. 2. If ~/.local/bin is not on the PATH, add it to ~/.zshrc : export PATH="$HOME/.local/bin:$PATH" 3. Add the hooks of your agent: Claude Code claude-code , Codex codex , or OpenCode opencode . 4. In Cursor or VS Code, set "terminal.integrated.tabs.title": "${sequence}" . Then the tab shows the title that agenttab writes. 5. Optional: add source ~/.config/agenttab/agenttab.zsh to ~/.zshrc . Then a terminal with no agent shows the name of the directory, or the running command. It also shows a name from Cursor a-name-from-cursor . 1. Add these hooks to ~/.claude/settings.json . If the file already has a hooks object, add each entry to the list of the same event. The hooks for Claude Code { "hooks": { "SessionStart": { "matcher": "startup|resume|clear|compact", "hooks": { "type": "command", "command": "agenttab hook idle", "timeout": 5 } } , "UserPromptSubmit": { "hooks": { "type": "command", "command": "agenttab hook busy", "timeout": 5 } } , "PostToolUse": { "hooks": { "type": "command", "command": "agenttab hook busy", "timeout": 5 } } , "Notification": { "matcher": "permission prompt", "hooks": { "type": "command", "command": "agenttab hook wait", "timeout": 5 } } , "Stop": { "hooks": { "type": "command", "command": "agenttab hook idle", "timeout": 5 } } , "SessionEnd": { "hooks": { "type": "command", "command": "agenttab hook end", "timeout": 5 } } } } 2. Add export CLAUDE CODE DISABLE TERMINAL TITLE=1 to ~/.zshrc . Then Claude Code does not write its own title. 3. Start a new session. Sessions that already run do not load the new hooks. Each account has its own settings file, in the directory of CLAUDE CONFIG DIR . Add the hooks to the settings file of each account, for example ~/.claude-work/settings.json . An account with no hooks shows no title, because CLAUDE CODE DISABLE TERMINAL TITLE applies to all accounts. Type /rename <name in Claude Code. agenttab then shows that name in place of the title that Claude Code made. The name shows at the next change of state. This section applies to Codex 0.157 or later. 1. Add these hooks to ~/.codex/hooks.json : The hooks for Codex { "hooks": { "SessionStart": { "hooks": { "type": "command", "command": "agenttab hook idle codex", "timeout": 5 } } , "UserPromptSubmit": { "hooks": { "type": "command", "command": "agenttab hook busy codex", "timeout": 5 } } , "PostToolUse": { "hooks": { "type": "command", "command": "agenttab hook busy codex", "timeout": 5 } } , "PermissionRequest": { "hooks": { "type": "command", "command": "agenttab hook wait codex", "timeout": 5 } } , "Stop": { "hooks": { "type": "command", "command": "agenttab hook idle codex", "timeout": 5 } } , "Interrupt": { "hooks": { "type": "command", "command": "agenttab hook idle codex", "timeout": 3 } } , "SessionEnd": { "hooks": { "type": "command", "command": "agenttab hook end codex", "timeout": 5 } } } } The timeout of the Interrupt hook must be 3 seconds or less. 2. Add this to ~/.codex/config.toml . Then Codex does not write its own title. tui terminal title = 3. Start Codex and type /hooks . Codex runs a new hook only after you trust it, so trust each agenttab hook. The text of the title is the name of the thread, from ~/.codex/session index.jsonl . The interactive Codex runs its turns in a shared daemon, and that daemon runs the hooks. The daemon has no terminal. Thus agenttab finds the codex process that has a terminal and runs in the directory of the thread. If two Codex sessions run in the same directory, agenttab cannot find the correct tab. Then it writes no title. OpenCode has no hooks. The plugin opencode/agenttab.js reads the events of the session and runs agenttab set <state <text . 1. Clone this repository. 2. Link the plugin: ln -s "$PWD/opencode/agenttab.js" ~/.config/opencode/plugins/ 3. Add export OPENCODE DISABLE TERMINAL TITLE=1 to ~/.zshrc . The plugin ignores the busy and idle states of a subagent session. A permission request from a subagent shows the wait icon, because it waits for you too. The extension in cursor/ adds the command Rename agenttab . To use it, right-click the tab of a terminal. The command palette also has it, as Terminal: Rename agenttab . An empty name gives the automatic title back. The name comes before /rename and before the automatic title. The extension writes the name to ~/.cache/agenttab/<tty .name and runs agenttab refresh . The zsh hook reads the same file, so a terminal with no agent also shows the name. Do not use the built-in Rename item. It makes the name of the tab static. Then the tab ignores the title that agenttab writes, and the icon does not show. A rename with an empty name does not make the tab dynamic again VS Code issue 333933 . To recover, close that tab and open a new one. To build and install the extension: cd cursor npx @vscode/vsce package --allow-missing-repository cursor --install-extension agenttab-0.1.0.vsix Write the file ~/.config/agenttab/config . Each line is optional: ICON IDLE="" ICON BUSY="◐ ◑" several frames, separated by spaces, make an animation ICON WAIT="⚠" SPIN INTERVAL="0.8" seconds between two frames TEXT="topic" topic: the title of the conversation. folder: the name of the directory. An empty icon gives a title with no icon. The hook is a shell script. It runs for approximately 60 ms at each change of state, and then it stops. The hook prints nothing, so it adds no tokens to the conversation. While the agent works, one shell loop shows the frames. It uses approximately 2 MB. It stops when the agent stops work, when the agent process ends, or when the terminal closes. A busy icon with one frame starts no loop. MIT