Environment variables

Variables exported to steps

Every shell step and every CLI harness process gets these variables. They’re also set while the workspace is being prepared (git clone / worktree), except where noted.

Variable	Value
`FACTORY`	`1` — lets scripts detect they’re running under Jimothy
`FACTORY_RUN_ID`	Run id, e.g. `run_0mfz2k1a9c3e5d7`
`FACTORY_RUN_NUMBER`	Run number, e.g. `42`
`FACTORY_PIPELINE`	Pipeline name
`FACTORY_PROJECT`	Project name (empty if the pipeline has no project)
`FACTORY_BRANCH`	The run’s git branch (empty during workspace preparation)
`FACTORY_BASE_BRANCH`	The workspace base branch (default `main`)
`FACTORY_WORKSPACE`	Absolute workspace path (empty during workspace preparation)
`FACTORY_ISSUE_KEY`	Issue key, e.g. `ENG-123`
`FACTORY_ISSUE_TITLE`	Issue title
`FACTORY_ISSUE_URL`	Issue URL (may be empty)
`FACTORY_ISSUE_DESCRIPTION`	Issue description, first 8,000 characters
`FACTORY_STEP_ID`	The current step’s id (steps only)

Using them in a shell step avoids quoting issues entirely:

gh pr create --base "$FACTORY_BASE_BRANCH" --head "$FACTORY_BRANCH" \
  --title "$FACTORY_ISSUE_KEY: $FACTORY_ISSUE_TITLE" \
  --body "Automated by Jimothy run #$FACTORY_RUN_NUMBER. $FACTORY_ISSUE_URL"

API harness steps don’t start a process, so these variables don’t apply to them.

How a step’s environment is built

Later layers override earlier ones:

#	Layer	Where to set it
1	The app’s own environment (whatever Jimothy was launched with), with `PATH` rebuilt and the non-interactive variables below	—
2	Global environment	Settings → Execution → Environment variables
3	Project environment	Project settings → Environment
4	Step environment	Step → Environment
5	`FACTORY_*` variables	Override layers 1–4
6	Harness `env`	CLI harnesses only; stored on the harness definition (not editable in the harness editor)

So a step’s Environment can override a global GH_TOKEN for one step, but it can’t change FACTORY_BRANCH.

Variables Jimothy sets for child processes

Variable	Value	Why
`PATH`	Extra PATH entries + login-shell `PATH` + the app’s `PATH` + common install directories	So CLIs installed with Homebrew, npm, pipx, bun, cargo, volta, … are found from a GUI app. See Auto-detection.
`CI`	`1` (unless `CI` is already set)	Many CLIs disable prompts and spinners in CI.
`NO_COLOR`	`1`	Plain output in logs.
`FORCE_COLOR`	`0`	Same.
`GIT_TERMINAL_PROMPT`	`0`	`git` fails instead of waiting for a username/password that nobody can type. Use SSH keys, a credential helper or `gh auth setup-git`.

These apply to harness processes, shell steps, workspace git commands, detection, model-list commands, and tailscale.

Variables harnesses read

Harnesses read their own credentials from the environment. Common ones:

Variable	Used by
`ANTHROPIC_API_KEY`	Claude API harness (default key variable); Claude Code model-list fetching; Claude Code itself if you use API-key auth; Aider
`OPENAI_API_KEY`	OpenAI-compatible API harness (default key variable); Codex (if not signed in); Aider
`GEMINI_API_KEY`	Gemini CLI; Gemini model-list fetching
`GH_TOKEN` / `GITHUB_TOKEN`	The `gh` CLI in PR steps
any name you choose	API harness …or environment variable field

Jimothy reads your login shell’s PATH but not its other variables. A key exported in ~/.zshrc is only visible if the app itself was launched from that shell (for example npm run dev from a terminal). For the packaged app, put keys in Settings → Environment variables, a harness’s API key field, or sign the CLI in with its own login command.

Harness detection and Models / Fetch latest use layer 1 only (the app environment), not the Settings, project or step environment.

App-level variables

These affect the Jimothy app itself. Set them before launching it.

Variable	Effect
`FACTORY_DATA_DIR`	Use this folder for all data instead of `<userData>/factory`. Useful for separate profiles, tests, or keeping data on another disk.
`SHELL`	The shell used to read your login `PATH` (default `/bin/bash`).
`CI`	If already set, passed through instead of `1`.

Example:

# macOS: start the packaged app with a separate data folder
FACTORY_DATA_DIR=~/jimothy-sandbox /Applications/Jimothy.app/Contents/MacOS/Jimothy

Jimothy allows only one running instance, whatever the data folder, so quit the other instance first (tray → Quit).