Skip to content

Workspaces

Every run executes in a workspace: the directory that agent CLIs and shell steps use as their working directory. The workspace is configured per pipeline (Pipeline settings → Workspace) or per project, and is prepared when the run moves to Preparing.

UI label Mode (JSON) Description in the app Needs Git branch per run Parallel-safe
Existing folder inplace Work directly in a folder on this machine. Git optional. No isolation between runs. Folder No No
Git worktree worktree Isolated worktree + branch per run from a local git clone. Parallel-safe. Local repository (a git clone) Yes Yes
Fresh clone clone Clone a git remote into a new folder per run. Repository URL Yes Yes
Empty folder scratch New empty directory per run. For non-code pipelines and demos. nothing No Yes

Branch name template is shown only for Git worktree and Fresh clone. Base branch is shown for those and for Existing folder, where steps that branch from it or open pull requests against it use it. Git worktree also has Copy untracked files into each worktree (see Untracked files in worktrees).

Existing folder and Git worktree also work with a folder that isn’t a git repository but holds several. See Several repositories in one folder.

The run works directly in the folder you choose, which doesn’t need to be a git repository. Nothing is created or checked out.

  • Every run of every pipeline using this folder shares it. Two runs at once will edit the same files. Set the pipeline’s Max concurrent runs to 1 if you use this mode for code changes.
  • {{run.branch}} and $FACTORY_BRANCH still contain a rendered branch name, but Jimothy doesn’t create or check out that branch. If your steps need a branch, create it yourself (for example in a first shell step).
  • The folder is never deleted by workspace cleanup.
  • New projects default to this mode.

The recommended mode for code. Jimothy uses your existing clone at Local repository and, for each run:

  1. Checks that the path exists and is a git repository, or a folder of git repositories (see below). Otherwise: … is not a git repository and has no git repositories in it - use "Existing folder" mode to work in a plain folder.
  2. Runs git fetch origin <base branch> in your clone. A failure (no remote, offline) is logged and ignored.
  3. Starts from origin/<base branch> if that ref exists, otherwise from the local <base branch>.
  4. If a branch with the rendered name already exists, appends -<run number> (for example jimothy/eng-42-17).
  5. Runs git worktree add -b <branch> <dir> <start>.
  6. Copies untracked files such as .env from your clone into the worktree (see Untracked files in worktrees).

Your clone’s own checkout is never touched, so you can keep working in it while runs happen. Each run has its own directory and branch, so runs are parallel-safe.

For each run, Jimothy runs git clone --branch <base branch> <url> <dir> in the workspaces folder, then git checkout -b <branch>. Use it when you don’t have a local clone, or want every run to start from a pristine remote state. It’s slower than a worktree for large repositories.

Git runs non-interactively (GIT_TERMINAL_PROMPT=0), so the URL must work without prompting: an SSH key loaded in your agent, a credential helper, or a token in the URL.

Creates an empty directory for the run. Use it for pipelines that don’t touch a repository (triage, reports, research, scheduled notifications) and for the Demo pipeline. A branch name is still rendered into {{run.branch}}, but there’s no git repository.

A workspace folder can hold several git repositories without being one itself, for example:

site/
├── api/ (git repository)
├── web/ (git repository)
└── infra/ (git repository)

Choose site/ as the Folder (Existing folder) or Local repository (Git worktree). If the folder is a git repository itself, runs treat it as one repository as usual.

Under the workspace settings, Repositories inside the folder lists the repositories, each as a folder path relative to the workspace (backend, services/api):

  • Detect adds every git repository directly inside the folder and guesses each one’s commands from its files (unless it has a Jimothyfile). Check what it guessed. Repositories deeper down, such as services/api, need Add.
  • Add adds an empty row.
  • Leave the list empty to use every git repository directly inside the folder. Hidden folders and node_modules are ignored.

Each row shows the folder, a branch tag when its base branch differs from the workspace’s, and a Jimothyfile tag when the repository has one. Expand a row to set its Base branch and its commands (Setup, Start, Test, Build, Lint). See Projects.

Paths must stay inside the workspace: no absolute paths and no ... Saving rejects a path like that (repository "…" must be a folder inside the workspace, like "backend" or "services/api") and a path listed twice. A listed folder that isn’t a git repository is left out of runs.

  • Git worktree: each run gets a worktree of every repository, laid out like the folder, in the run’s directory. They all use one branch name, the run’s. If that branch already exists in any of the repositories, all of them get -<run number> appended. Each worktree starts from its repository’s own base branch. Files in the folder outside the repositories aren’t part of the workspace. Cleanup removes every worktree.
  • Existing folder: the run works in the folder itself, as with a single repository.

The run log lists the repositories and where each starts, for example Repositories: api (from main), infra (from develop).

Before each step, the run compares every repository’s git status and HEAD with what they were when the run started. A repository counts as changed if its uncommitted changes differ or it has new commits. Changes made before the run started don’t count, so this works in Existing folder mode too.

The run page header shows a Repositories list with a filled dot next to each changed one. Shell steps can run once in each changed repository (see Run in), and templates can read {{run.repos}} and {{run.changedRepos}}.

Each repository’s base branch is the first of:

  1. the Base branch set on the repository in the app;
  2. the remote’s default branch as your clone recorded it (origin/HEAD);
  3. the workspace’s Base branch.

Worktrees start from it, and steps that run in each repository get it as {{run.baseBranch}}, {{repo.baseBranch}} and $FACTORY_BASE_BRANCH.

origin/HEAD is recorded when a repository is cloned and isn’t refreshed afterwards. If the remote’s default branch has changed since, run git remote set-head origin --auto in your clone. Repositories created with git init may not have one, so they use the workspace’s base branch.

A new worktree only has the files git tracks, so files like .env are missing. In Git worktree mode, Copy untracked files into each worktree copies untracked files from your local repository into each run’s worktree:

Option Copies
What .worktreeinclude lists, or .env files without one (default) The files the repository’s .worktreeinclude lists. Without that file: .env and .env.* at any depth, except inside node_modules.
Every ignored file (node_modules, build output, …) Everything git ignores.
Nothing Nothing.

.worktreeinclude sits at the repository’s root and uses gitignore syntax (the same file Worktrunk uses):

.worktreeinclude
.env
.env.local
apps/*/.env.local
config/credentials.yml
  • Files are never copied over a file the worktree already has.
  • Copying never fails the run. Errors are logged.
  • Where the disk supports it, copies are copy-on-write clones (APFS on macOS, btrfs or XFS on Linux), so even a large node_modules takes seconds and no extra space. Elsewhere they’re normal copies.
  • Folders that hold another git repository or worktree (such as .claude/worktrees/ or a vendored repository) are skipped: Didn't copy .claude/: it holds another git repository or worktree.
  • In a folder of several repositories, each repository uses its own .worktreeinclude.
  • Copied files don’t count as changes the run made.

The run log shows what was copied, for example Copied untracked files: .env, apps/web/.env.local (0.1s).

Per-run directories are created in Settings → General → Workspaces folder, which defaults to a workspaces folder inside the app’s data directory. Each run’s directory is named:

<workspaces folder>/run-<run number>-<issue key slug>

The issue key is slugified and cut to 24 characters, for example run-17-eng-42. If the key slugifies to nothing, the last six characters of the run id are used.

The workspace path is available as {{run.workspace}} and $FACTORY_WORKSPACE. On the run page, the header buttons Open workspace in editor and Reveal workspace folder open it.

The Branch name template is a template rendered with the run’s context (issue, run number, variables…). The default is:

jimothy/{{issue.key | slug}}

The rendered name is then sanitized:

  • Any run of characters other than letters, digits, _, ., / and - becomes -.
  • Runs of .. collapse to ..
  • Leading and trailing -, / and . are removed.
  • If the result is empty, the branch becomes jimothy/run-<number>. If it contains an empty path segment (such as a//b), it becomes jimothy/<slug of the name>.

Examples:

Template Issue key Run # Branch
jimothy/{{issue.key | slug}} ENG-42 17 jimothy/eng-42
jimothy/{{issue.key | slug}}-{{run.number}} ENG-42 17 jimothy/eng-42-17
fix/{{issue.key | slug}}-{{issue.title | slug:30}} #12 3 fix/12-login-fails-with-sso
feature/{{issue.title}} — 5 feature/Add-rate-limiting (spaces become -)

The run’s branch is available as {{run.branch}} and $FACTORY_BRANCH; the base branch as {{run.baseBranch}} and $FACTORY_BASE_BRANCH (default main). In a step that runs in each repository of a folder of several repositories, these are that repository’s base branch.

When you Retry a run (or Retry from here), Jimothy reuses the run’s existing workspace and branch if the directory still exists (“Reusing workspace …”), so the retried steps see the previous steps’ changes. If the directory is gone, it’s prepared again from scratch.

By default workspaces are kept after a run so you can inspect or continue the work. To remove them automatically, turn on Settings → General → Delete a run’s workspace after it succeeds (branches are kept). When it’s on and a run succeeds:

  • Existing folder: nothing is removed.
  • Git worktree: git worktree remove --force <dir> in your clone (in each repository’s clone, for a folder of several), then the directory is deleted. The branch stays in your clone.
  • Fresh clone and Empty folder: the directory is deleted.

Failed and cancelled runs always keep their workspace, so you can debug and retry. To clean those up, delete the directories yourself (and for worktrees, run git worktree prune in your clone).

A pipeline (or project) whose workspace is incomplete can be saved, but runs can’t start. The editor shows the problem and the Start a run dialog reports Can't start: …:

Mode Problem
Existing folder “choose the folder to work in”
Git worktree “choose the local git repository, or use “Existing folder” for a folder that isn’t a git repo”
Fresh clone “set the repository URL”

If preparation fails at run time (folder deleted, git worktree add fails, clone fails), the run fails with Workspace setup failed: … and the git output is in the run log.