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.
Existing folder
Section titled “Existing 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
1if you use this mode for code changes. {{run.branch}}and$FACTORY_BRANCHstill 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.
Git worktree
Section titled “Git worktree”The recommended mode for code. Jimothy uses your existing clone at Local repository and, for each run:
- 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. - Runs
git fetch origin <base branch>in your clone. A failure (no remote, offline) is logged and ignored. - Starts from
origin/<base branch>if that ref exists, otherwise from the local<base branch>. - If a branch with the rendered name already exists, appends
-<run number>(for examplejimothy/eng-42-17). - Runs
git worktree add -b <branch> <dir> <start>. - Copies untracked files such as
.envfrom 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.
Fresh clone
Section titled “Fresh clone”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.
Empty folder
Section titled “Empty folder”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.
Several repositories in one folder
Section titled “Several repositories in one folder”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.
Setting it up
Section titled “Setting it up”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_modulesare 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.
How runs use the repositories
Section titled “How runs use the repositories”- 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).
Which repositories a run changed
Section titled “Which repositories a run changed”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}}.
Base branch for each repository
Section titled “Base branch for each repository”Each repository’s base branch is the first of:
- the Base branch set on the repository in the app;
- the remote’s default branch as your clone recorded it (
origin/HEAD); - 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.
Untracked files in worktrees
Section titled “Untracked files in worktrees”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):
.env.env.localapps/*/.env.localconfig/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_modulestakes 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).
Where workspaces live
Section titled “Where workspaces live”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.
Branch naming
Section titled “Branch naming”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 asa//b), it becomesjimothy/<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.
Retries reuse the workspace
Section titled “Retries reuse the workspace”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.
Cleanup
Section titled “Cleanup”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).
Workspace problems
Section titled “Workspace problems”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.