Configuration

PRIMA Bot reads its settings from one file, ~/.config/prima-bot-remote-server/config. The installer writes it from config.example the first time it runs and never overwrites it afterwards.

The Settings File

The file uses shell syntax, with one setting per line in the form NAME="value". Only WORKSPACE_DIR is required.

Setting	Default	What it sets
WORKSPACE_DIR	none	The folder every session works in
CLAUDE_BIN	~/.local/bin/claude	The Claude Code program PRIMA Bot runs
PERMISSION_MODE	default	What sessions may do without asking, as Using PRIMA Bot Securely describes
SESSION_NAME	the Mac’s short host name	The name shown in the Claude app and at claude.ai/code
SPAWN_MODE	same-dir	Where each new session works
SCREEN_NAME	prima-bot	The name of the hidden screen window

A completed file looks like the example below.

WORKSPACE_DIR="$HOME/Documents/Example Consulting"
CLAUDE_BIN="$HOME/.local/bin/claude"
PERMISSION_MODE="default"
SESSION_NAME="My Workspace"
SPAWN_MODE="same-dir"
SCREEN_NAME="prima-bot"

Restart PRIMA Bot after you change a setting, with the restart command in Everyday Controls.

Choosing the Claude Code Program

Set CLAUDE_BIN to the Claude Code you keep up to date. Run which claude in Terminal to find its path. An older copy of Claude Code elsewhere on the Mac may lack the crash recovery that server mode gains in version 2.1.238.

Spawn Mode

Value	What happens
same-dir	Every session works in WORKSPACE_DIR
worktree	Each new session gets its own git worktree, a separate copy of the files on its own branch, so sessions cannot overwrite each other

The worktree setting needs a workspace that is a git repository.

Environment Variables

Two environment variables change where the scripts look.

Variable	Used by	What it changes
PRIMA_BOT_CONFIG	The launcher and uninstall.sh	The path of the settings file
PRIMA_BOT_LABEL	install.sh and uninstall.sh	The LaunchAgent label, which is com.<your-user-name>.prima-bot-remote-server by default

The PATH the Launcher Sets

macOS starts background jobs with a short list of program folders. Many connectors, also called MCP servers, need node, npx, uvx or bun, which live in other folders. The launcher sets a full PATH that covers ~/.local/bin, ~/.bun/bin, /opt/homebrew/bin and /usr/local/bin. If a connector needs a program in another folder, add that folder to the PATH line in the launcher source and run ./install.sh again.