Frequently Asked Questions

Coding agents

How do I connect my coding agent to Nash?

In a Nash pane, install the status hooks for your agent:

# Claude Code
nash agent-status install claude-code

# Antigravity CLI
nash agent-status install agy

Run only the command for the agent you use, then restart the agent inside Nash. These commands require Nash 0.5.8 or newer and default to user-wide configuration. Add --dry-run to preview changes or --scope project to configure just the current project.

Nash then shows agent activity in its tab title and pane badge. See Connect Your Coding Agent for prerequisites, configuration paths, verification, troubleshooting, and removal.

Does Nash install the agent or replace my settings?

No. Install your agent separately. Nash merges its status hooks into the agent's existing configuration without replacing unrelated settings or hooks. It may reformat the JSON; use --dry-run first if you want to review the changes.

How do I check whether the hooks are installed?

Run nash agent-status show in the Nash pane where you launch your agent. It reports registration in both user and project configuration. Restart the agent after installation, then submit a prompt to check the indicators.

What do the status indicators mean?

A green spinner means working; an orange circle means waiting for your input. A green check-circle marks an unread completion, and a red alert-circle marks an unread failure. The pane badge identifies the worker in a split layout and shows when a turn ended.

Not every agent reports every waiting state. The setup guide explains the differences and how outcomes are acknowledged.

Can I move or resize the pane badge?

Yes. The pane_agent_status_* keys in the [pane] table of ~/.config/nash/nash.toml set its corner, size, colors, and timestamp format. Set pane_agent_status_indicator = "none" to hide the badge and keep the tab indicator. See Customize the pane badge.

Where can I see how this helps my workflow?

Read Know When Your Coding Agent Needs You for an introduction to tab and pane status, plus a quick start.

Pane navigation

How do I jump directly to another pane?

Hold Ctrl+Alt+Super (Control+Option+Command on macOS), then type the pane's number. Keep holding the chord to select another pane. Nash 0.9.4 skips folded panes and numbers only the unfolded ones. See Quick Pane Navigation.

Why does my pane-navigation shortcut still use Alt+Shift?

Alt+Shift was the original default in Nash 0.9.2. Upgrades preserve your saved chord. Set number_navigation_modifiers = "CTRL|ALT|SUPER" under [pane] in nash.toml to use the new default, or set number_navigation = false to turn number navigation off.

Why do commands and tasks change order in the palette?

Nash ranks them by recent and frequent use. When searching, stronger text matches still come first. The history stays on your machine and records no terminal content. See Command Palette.

Pane folding

How do I fold a pane in Nash?

Press SUPER+SHIFT+E (Command on macOS) to fold the active pane to a thin strip that shows its title. The program keeps running. Press SUPER+E, press Enter on a selected strip, or double-click the strip to unfold it. Folding needs Nash 0.7.0 or newer. See Pane Folding, or read Fold a Pane. Keep the Layout.

Does folding a pane stop the program in it?

No. A folded pane keeps running at the size it had, and the panes beside it take the space. Unfolding returns the pane to its place and size. See How Folding Rearranges Your Panes.

Why did SUPER+SHIFT+E not fold my pane?

Nash cannot fold the only pane in a tab, or the last unfolded pane. If a pane is maximized, the key restores the layout first. See Persistence and Limits.

Is a folded pane saved with my session?

Yes, since Nash 0.7.0. Session restore and multiplexer reconnects bring the strips back. See Session Restore.

Why does SUPER+M not minimize my window?

SUPER+M and SUPER+SHIFT+M walk the pane size ladder. Minimize Window has no default key. See Keys and Commands to bind one.

Sessions

Does Nash restore my windows after a restart?

Yes, when you ask. Nash saves every window, tab, and split when it exits, and it never reopens them by itself. After you start Nash, run Restore Saved Session from the command palette. In Nash 0.9.4, choose a save from the history; SUPER+Enter restores all its windows. Enter opens its window list, then a window's tab list, where Enter restores a single tab. Basic session restore needs Nash 0.2.0 or newer. See Session Restore.

Will a restore run my commands again?

If a pane was running a command when Nash saved, and shell integration is on, Nash types the command into the new shell and presses Enter. The restore dialog marks these panes with ▶. A command that already finished does not run again. Stop a command before you quit to avoid its restart. See Limits and Troubleshooting.

Why does the restore dialog say "No saved sessions yet"?

Nash has no saved sessions in the current configuration directory. Quit Nash from the menu once and start it again, or run Save Window Session. Start Nash with the same NASH_CONFIG_DIR or XDG_CONFIG_HOME each time, because the history lives in state/saved-sessions/ there. See Limits and Troubleshooting.

How do I keep programs running after I quit Nash?

Set enabled = true under [mux] in nash.toml and restart Nash. A background server then owns your panes. They survive closing a window, quitting, and updating. Show a session again with nash mux connect <session>. This needs Nash 0.5.6 or newer. See Multiplexer Sessions.

Updates and configuration

How do I update Nash?

Run nash update in a shell inside Nash. It finds the latest release, downloads the build for your machine, verifies it, and installs it over the running build. Use nash update --check to see if a release exists. Nash 0.6.0 or newer is required. See Updating Nash, or read Update Nash Without Leaving Your Terminal.

Will an update close my windows or lose my layout?

On macOS app bundles and Linux AppImages, nash update leaves your windows open by default. Nash saves your layout when it exits, and the session restore dialog offers it back. On those installs, nash update --restart restarts for you, but you must run it from another terminal.

Windows installer updates close running Nash processes, even without --restart. Save your work before updating. See Updating Nash and Session Restore.

Why will nash update not replace my Homebrew, apt, or Flatpak install?

Overwriting files that a package manager owns would corrupt its records. Nash detects these installs, prints the right command (for example brew upgrade --cask nash), and stops. nash update --check still tells you that a release exists. See Updating Nash.

Will an upgrade overwrite my configuration?

No. On the first launch of a new build, Nash only adds settings, tasks, and commands that your files lack. Your values, comments, and order stay as they are, and changed files get a .bak copy. Comment out a default to keep it off. See Configuration Sync.

How do I turn off the update notice?

Add check_for_updates = false to a table that custom.lua returns, in your configuration directory. The background check never installs anything. See Updating Nash.

Images

Does Nash show images in the terminal?

Yes. Nash 0.8.1 or newer supports the Kitty graphics protocol. It also accepts iTerm2 inline images and sixel. Try nash imgcat /path/to/image.png. Programs that use the Kitty protocol, such as Neovim image previews, need no setup. See Kitty Graphics Protocol and Other Image Protocols, or read Images That Behave Like Text.

Why does an image not appear?

When an image command fails, Nash does not send an error to the program. It writes the reason to its log. Press CTRL+SHIFT+L to open the debug overlay and look for a line that starts with kitty_img:. The troubleshooting guide explains each message.

Does Nash support images in Neovim and tmux?

Yes, since 0.8.1. Nash supports Unicode placeholders, which the snacks.nvim plugin uses to show images inside windows and floats. Programs also use them to place images in tmux. tmux must let the image sequences reach Nash. See Kitty Graphics Protocol.

How do I turn Kitty graphics off?

Create custom.lua in ~/.config/nash with return { enable_kitty_graphics = false }, then reload the configuration. Nash then ignores all Kitty graphics sequences, including capability queries. The setting has no key in nash.toml.

Images fail in a multiplexer session after I upgraded. Why?

Nash 0.8.1 changed the multiplexer protocol to version 48. A server that speaks an older version must be restarted. Run nash mux status to compare versions. nash mux restart closes every pane the server owns, so save your work first. See Kitty Graphics Troubleshooting.

Tabs, keyboard, and appearance

How do I turn off the cursor streak?

Set enabled = false under [cursor_wake] in ~/.config/nash/nash.toml. Do not delete the table, because the next configuration sync adds it again. See Cursor Wake.

Why does SHIFT+Enter act differently in a shell and in a full-screen program?

A shell cannot tell SHIFT+Enter from Enter, so Nash sends ESC CR, which zsh reads as a newline. A program that asks for an extended keyboard mode gets the real key. See Keyboard.

Why does Nash say "Quit disabled" when I press Cmd+Q?

The shipped nash.toml sets prevent_quit = true in the [system] table. Set it to false to let Nash quit. See Closing Panes & Zen Mode.

Does closing a pane end my tmux session?

No. When a pane closes, Nash only sends SIGHUP to a tmux client, so the client detaches. Nash never signals a tmux server that is outside the pane. The list is the persistent_process_names option. See Closing Panes & Zen Mode.

How do I change the theme or the terminal text color?

Run Themes from the command palette, or set theme under [ui] in nash.toml. A foreground value under [ui] overrides the theme's text color. See Themes & Colors.