Terminal Shell and Environment

  • Desktop app
  • All plans
View as Markdown

What it does

Decides what every terminal AgentsRoom opens starts with: agents, dev commands, blank terminals, and agents started from the phone. By default it is your account's shell with its startup files, as always. You can instead start every terminal with the shell and the env variables of your Ghostty configuration, or with a shell you pick (fish, bash, zsh...), and add folders in front of PATH. It answers "my tools work in Ghostty (or in fish) but my agents cannot find them".

Where to find it

Settings > Terminal > Shell and environment (source picker) and, just below, Extra PATH folders. The Settings search finds both ("shell", "Ghostty", "PATH").

How to use it

  1. Open Settings > Terminal > Shell and environment.
  2. Pick a source:
    • Default shell: your account's shell ($SHELL, then the system's user record), with its startup files. Nothing else is added.
    • Same as Ghostty: AgentsRoom reads Ghostty's configuration files (~/.config/ghostty/config and config.ghostty, then on macOS ~/Library/Application Support/com.mitchellh.ghostty/, config-file includes followed). The shell is the program of Ghostty's command setting (without one, Ghostty and AgentsRoom both use your default shell). Every env = KEY=VALUE line is added to the terminal's variables. The block shows which files were read, the shell, the variable names (never their values) and what was set aside. Files are read again at every launch, so an edit in Ghostty reaches the next agent without restarting AgentsRoom.
    • Custom shell: type the full path of a shell, or click one of the shells found on the computer.
  3. The line under the picker says which shell terminals start with ("Terminals start with /opt/homebrew/bin/fish."). When the choice cannot be used, it says so and terminals start with the default shell instead: nothing is left without a terminal.
  4. Optional: in Extra PATH folders, write one folder per line (~/bin, /opt/tools/bin; a line like /a/bin:/b/bin is split). They go in front of PATH in every terminal and are used to detect installed CLIs, so a CLI installed there no longer shows as missing. Saved when you leave the field.

Applies to terminals opened afterwards. Agents already running keep their shell until they are restarted.

Settings

  • terminalEnvSource (global, Settings > Terminal > Shell and environment): login (default), ghostty or custom. Machine-local, never synced to your other computers.
  • terminalShellPath (global, same block, shown for Custom shell): absolute path of the shell. macOS / Linux: zsh, bash or fish. Windows: powershell.exe or pwsh.exe. Started as a login shell. Default empty.
  • terminalExtraPathDirs (global, Settings > Terminal > Extra PATH folders): absolute folders, ~ allowed, put in front of PATH whatever the source. Default empty.
  • terminalStartupCommand (Settings > Terminal > Startup command) still runs after the shell starts, whatever the source.

Agent tools (MCP)

  • settings_list / settings_get / settings_set with the three keys above (scope: "global"). An agent can switch the source for the user when asked.

Providers

All providers, no difference: the shell starts whatever CLI the agent runs.

Mobile

No setting on the phone: the shell is a property of the computer. Agents started from the phone run on the computer and use the shell picked there (it overrides the /bin/zsh older phone builds used to send).

Limits

  • The terminal itself stays AgentsRoom's: statuses, the message box, the conversation view, the phone, teams and MCP tools keep working because AgentsRoom owns the terminal. Ghostty does not render the agent and is not opened: its environment is reused, not its window. Rendering speed is AgentsRoom's own GPU renderer (Settings > Terminal > GPU acceleration).
  • Shells AgentsRoom cannot type commands into are refused: nu, xonsh, elvish, tcsh, cmd.exe, and also dash, ksh and sh (AgentsRoom loads the agent's launch script with source, which only zsh, bash and fish have). If Ghostty's command starts something that is not a shell (tmux, zellij, an editor), the default shell is used and the block says why.
  • $SHELL is not changed: the command tools inside the CLIs (for example Claude Code's Bash tool) keep using your account's shell. PATH and variables do reach them.
  • Ghostty variables named like the ones AgentsRoom sets itself (TERM, PATH, account folders, AGENTSROOM_*) are not applied; an env = PATH=... line adds its folders in front of PATH instead of replacing it.
  • Your shell's startup files run after AgentsRoom sets PATH and can reorder it (macOS path_helper).
  • Windows: no Ghostty; Custom shell accepts only Windows PowerShell and PowerShell 7.
  • Linux: Ghostty is read from $XDG_CONFIG_HOME/ghostty/ only.

Common questions

  • Can agents run inside Ghostty instead of AgentsRoom's terminal? No. AgentsRoom must own the terminal to read statuses, type your messages and stream to the phone. It reuses Ghostty's environment (shell, env variables, PATH) so agents see the same tools.
  • My tools work in Ghostty but agents say "command not found". Pick Same as Ghostty, or Custom shell with the shell Ghostty uses, or add the tool's folder in Extra PATH folders.
  • Can I use fish (or bash) for agents while my account stays on zsh? Yes: Custom shell, then pick fish in the list or type its path.
  • I edited my Ghostty config, do I need to restart AgentsRoom? No. The next terminal reads it again. Agents already running keep their environment until restarted.
  • Why is my shell refused? AgentsRoom types commands into the terminal in zsh/bash, fish or PowerShell syntax, and loads the launch script with source. Other shells would receive lines they cannot read, so the default shell is used instead.
  • Where do I set an environment variable for every agent? Ghostty's env lines with Same as Ghostty, or the environment variables blocks of Settings > Providers, the project settings or an agent (Secret Manager explains how a stored secret reaches an agent).

Related