Connect Your Coding Agent

Nash can show coding-agent activity in the tab title and a badge in the agent's pane. The tab aggregates activity from its splits; the pane badge tells you which agent is working or needs your attention.

For Claude Code and Antigravity CLI (agy), install Nash's lifecycle hooks once. You do not need to copy hook JSON by hand or install a separate Python adapter. For Pi, Nash 0.9.6 or newer installs an extension that also reports waiting and failure states.

Before you start

Install Nash 0.5.8 or newer, which includes the hook installer. The latest release is recommended.
Install and set up Claude Code, Antigravity, or Pi separately. Nash connects their status reporting; it does not install the agent itself.
Open a shell inside Nash and check that the CLI is available:

nash --version
nash agent-status --help

1. Install the agent integration

For Claude Code:

nash agent-status install claude-code --dry-run
nash agent-status install claude-code

For Antigravity CLI:

nash agent-status install agy --dry-run
nash agent-status install agy

The dry run previews changes without writing files. The second command registers the hooks in your user-wide agent configuration, covering every project.

For Pi (Nash 0.9.6 or newer):

nash agent-status install pi --dry-run
nash agent-status install pi

Pi uses a Nash extension rather than hooks. Installation turns off Pi's own Terminal progress setting so the two status writers do not conflict.

To configure all supported agents at once:

nash agent-status install

With no agent name, the installer configures Claude Code, Antigravity, and Pi, even if you only use one. Name your agent to avoid creating configuration for agents you do not use.

What changes?

Agent	User-wide configuration (default)	Project configuration
Claude Code (`claude-code`)	`~/.claude/settings.json`	`.claude/settings.json`
Antigravity CLI (`agy`)	`~/.gemini/config/hooks.json`	`.agents/hooks.json`
Pi (`pi`)	`~/.pi/agent/extensions/nash-agent-status.ts` and `~/.pi/agent/settings.json`	`.pi/extensions/nash-agent-status.ts` and `.pi/settings.json`

Project paths are relative to the selected project directory. If you set CLAUDE_CONFIG_DIR, Nash uses that directory instead of ~/.claude for Claude Code's user-wide settings. Pi uses $PI_CODING_AGENT_DIR instead of ~/.pi/agent when set. A project must be trusted in Pi before it loads that project's extension and settings.

Installation merges Nash's hooks into existing settings and preserves unrelated configuration. Running it again is safe: it does not duplicate registered hooks. JSON formatting may change, so review the diff if you track these files in version control. If an existing configuration cannot be parsed as JSON, the command stops without writing the managed configuration files.

2. Restart the agent

Exit any running agent session and start it again in a Nash pane. Agents read their hooks at startup; installing hooks does not update an already-running session. For Pi, restarting or running /reload loads the extension.

After updating Nash, rerun nash agent-status install pi to refresh the copy installed in Pi's directory. nash agent-status show reports an outdated extension. Installation supports user and project scopes, dry runs, status inspection, and uninstall.

The installed hooks call $NASH_EXECUTABLE_DIR/nash. Nash supplies this environment variable to its panes, so the hooks use the executable belonging to the terminal you are running. These hooks are intended for agents launched inside Nash.

3. Verify the integration

nash agent-status show

This reports the managed agents' user and project configuration paths, hook registration or Pi extension status, and whether the current shell is a Nash pane. An unused agent showing no configuration is normal.

Start your agent, submit a prompt, and watch the tab and pane badge:

State	What you see
Working	Animated green spinner
Waiting for your input	Solid orange circle
Finished, with an unread result	Green check-circle
Failed, with an unread result	Red alert-circle

The pane badge also records when a turn finished or failed. Returning to the worker pane acknowledges its tab outcome; typing in that pane clears its outcome badge. If you are already watching the pane when work finishes successfully, the tab does not need to show an unread completion.

The waiting indicator depends on the agent's events. Claude Code reports blocking permission prompts, MCP input requests, and certain usage-limit states. Antigravity reports its ask_question tool; its permission prompts do not have a distinct hook event that Nash can identify.

With the bundled configuration, working spinners keep animating while Nash is in the background: the tab spinner since 0.7.4 and the pane badge spinner since 0.8.1. This uses the visible tab bar's animation scheduling; it does not keep other terminal animations running while unfocused. Set animate_in_tab_processing_when_unfocused = false under [tab] in nash.toml to stop background spinner animation.

Project-only setup

User-wide setup is recommended. To enable hooks for just one project, run this from its existing root directory:

nash agent-status install claude-code --scope project --dry-run
nash agent-status install claude-code --scope project

Replace claude-code with agy for Antigravity or pi for Pi. To select another existing directory, add --project-dir /path/to/project alongside --scope project.

Antigravity print mode (agy -p) loads only user-wide hooks. Use the default user scope if you want those runs to report status too.

Customize the pane badge

The pane badge is controlled by keys in the [pane] table of ~/.config/nash/nash.toml. The tab indicator is a separate setting, so changing these keys never changes what the tab shows. Nash applies the change when it reloads the configuration.

Key	Default	Effect
`pane_agent_status_indicator`	`"badge"`	`"badge"` draws the badge; `"none"` draws nothing in the pane.
`pane_agent_status_position`	`"top_right"`	`top_left`, `top_center`, `top_right`, `bottom_left`, `bottom_center`, or `bottom_right`.
`pane_agent_status_font_size`	`10`	Size in points of the timestamp. It also sizes the icon unless you set an icon size.
`pane_agent_status_icon_size`	follows font	Size in points of the state icon, apart from the timestamp. (Nash 0.8.1 or newer.)
`pane_agent_status_margin`	`'0.5cell'`	Gap between the badge and the two pane edges it sits against.
`pane_agent_status_background_color`	transparent	Background behind the badge, for example `"rgba(0,0,0,75%)"`.
`pane_agent_status_working_color`	`#39ff14`	Badge color while the agent works. The tab indicator uses this color too.
`pane_agent_status_paused_color`	`#ffa000`	Badge color while the agent waits for you. The tab indicator uses it too.
`pane_agent_status_finished_color`	theme green	Badge color after a finished turn.
`pane_agent_status_failed_color`	theme red	Badge color after a failed turn.
`pane_agent_status_finished_format`	`'%H:%M:%S'`	`strftime` format of the end time, in local time. `""` draws the icon alone.

For example, to move the badge to the bottom-right corner and drop the seconds from the timestamp:

[pane]
pane_agent_status_position = "bottom_right"
pane_agent_status_finished_format = '%H:%M'

An empty string ("") means "use the default" for the color and icon-size keys. Nash hides the badge in a pane that is too small to hold it, and the tab indicator still shows the state.

Agent alert sounds

Since Nash 0.9.6, the bundled configuration enables sounds when a turn fails, pauses for your input, or finishes in a pane you are not watching. Upgrade sync adds these settings to existing installs.

Edit ~/.config/nash/nash.toml:

[agent_alerts]
enabled = true
volume = 0.5
when_watched = false
failed = 'Basso'
paused = 'Submarine'
finished = 'Glass'

Set enabled = false to disable all agent sounds.
when_watched = true also plays alerts for the selected pane of the focused window. By default, that pane is silent when no overlay covers it.
volume ranges from 0 to 1 and controls macOS playback.
Each state accepts a macOS system sound name, an absolute or ~/ sound-file path, or false to silence just that state. true or "" restores its default sound. Commenting out a state does not silence it.

On macOS, the defaults are Basso for failure, Submarine for a pause, and Glass for completion at half volume. Names are case-sensitive and can also refer to files in ~/Library/Sounds. If a sound cannot play, Nash falls back to the system bell. Linux and Windows use the system bell for every state; Wayland plays no sound. Named sounds, files, and volume customization are macOS-only.

A state must hold for 300 ms before its alert plays, avoiding a completion sound immediately before a reported failure. Nash's stale-process recovery and confirmed-interrupt clears are silent. Alerts follow any program reporting OSC 9;4 progress, not only the supported coding agents. Without the bundled settings, the built-in enabled default is false.

For the visual glow when returning to an agent result, see Pane flashes.

Troubleshooting

The install command is missing

Check nash --version and update through the download page. Hook installation requires Nash 0.5.8 or newer. If your shell cannot find nash, open a new shell inside Nash and retry.

Hooks are registered, but no status appears

Restart the agent after installation.
Run nash agent-status show from the pane where you launch it. Check the reported path and registration state, and confirm it identifies a Nash pane.
For project hooks, launch the agent from the project you configured. For agy -p, use user-wide hooks instead.
If you use a custom Lua format-tab-title callback, it remains authoritative: Nash does not insert its native indicator into your custom title. The callback must render tab.activity itself.

To check Nash's rendering independently of the agent, run this in a Nash pane:

# Start work, then clear it after five seconds.
printf '\033]9;4;3\033\\'; sleep 5; printf '\033]9;4;0\033\\'

Switch to another tab or split during the delay to see an unread completion on the original tab. If this works but agent prompts do not, check the hooks and restart the agent.

A tab keeps spinning after the agent stops

Nash records the pane's foreground process group when progress starts. If that group changes after the agent exits, crashes, or is killed, Nash clears the stale progress instead of leaving the tab spinning. This recovery needs an observable process group; Nash cannot infer an agent's exit just from a quiet pane inside a long-lived process such as tmux. A confirmed interrupt also clears progress after the pane settles, rather than treating every Ctrl+C as a completed turn. Multiplexer client panes clear their local progress mirror too, so an old state does not remain visible after Nash clears it.

Installation reports invalid JSON

Repair the configuration file named in the error, then retry. Nash will not replace configuration it cannot parse. Do not delete your existing settings just to install hooks.

Antigravity runs inside tmux

The Antigravity adapter detects $TMUX and wraps its status sequences for passthrough. If no status reaches Nash, check that your tmux configuration allows passthrough; registering hooks alone does not configure tmux. The nash agent-status agy EVENT adapter also accepts --tmux-passthru enable, disable, or detect (the default) when you need to override detection.

Remove the integration

Use the same agent and scope you installed:

# Remove user-wide Claude Code hooks.
nash agent-status uninstall claude-code

# Remove Claude Code hooks from the current project.
nash agent-status uninstall claude-code --scope project

Replace claude-code with agy for Antigravity or pi for Pi, or omit the name to remove all managed integrations in the selected scope. Uninstallation leaves unrelated settings and hooks alone. Pi's Terminal progress setting stays off; turn it back on in Pi's /settings if you want its own indicator instead. Restart the agent afterward, and use nash agent-status show to verify the result.

For a short overview, see the FAQ.