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.

Modes

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

Base branch and Branch name template are shown only for Git worktree and Fresh clone.

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

Git worktree

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. Otherwise: … is not a git repository - 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>.

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

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

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.

Where workspaces live

Per-run directories are created in Settings → 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

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).

Note

In Git worktree mode, a name collision is resolved by appending the run number. In Fresh clone mode the clone is new, so there’s no collision locally, but pushing may still conflict with an existing remote branch. Include {{run.number}} in the template if the same issue can run several times.

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

By default workspaces are kept after a run so you can inspect or continue the work. To remove them automatically, turn on Settings → 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, 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

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.