Skip to content

Environment variables

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). In a shell step that runs in each repository, that repository’s base branch.
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)
FACTORY_REPOS In a folder of several repositories: the repository paths, one per line. Empty otherwise.
FACTORY_CHANGED_REPOS The repositories the run has changed so far, one per line
FACTORY_REPO In a shell step that runs in each repository: the path of the repository it’s running in, e.g. services/api

Using them in a shell step avoids quoting issues entirely:

Terminal window
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.

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 → General → 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.

The global, project and step editors (layers 2–4) have an eye button on each row. It decides whether AI assistants connected through the MCP server can read the value. Values are hidden (crossed-out eye) by default; click the eye to let assistants read one. Steps get every value either way.

Variables Jimothy sets for child processes

Section titled “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.

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 → General → 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.

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:

Terminal window
# 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).