FXCode
SIGN IN →
Doc. 11 — Features

Parallel work (worktrees)

Several agents working at once on the same repo, each in its own git worktree, with its session, clash warnings and cleanup when they finish.

One agent per worktree, one task per branch. When you run several agents at once on the same repository, each one works in its own git worktree: a separate folder with its own branch, so their changes don’t step on each other. FXCode knows who is where, warns you when two are about to clash, and tells you which folders are left over when they finish.

It builds on branches and PRs: the branch of each line of work carries the task id, so the GitHub webhook recognizes it just the same.

Open a line of work

# From the repo (any worktree)
fxc tasks start cm4k2x9ab0001 --worktree
# ✓ Login con GitHub: Working · feat/fxc-cm4k2x9ab0001-login-con-github
# Session: claude-code on my-laptop (C:/code/tienda-fxc-ab0001)
#
# Worktree ready. Enter it with:
#
#   cd "C:\code\tienda-fxc-ab0001"

With --worktree, fxc tasks start:

  1. Creates the worktree ../<repo>-fxc-<short id> next to the main one, on the branch feat/fxc-<taskId>-<title-slug> (or reuses the branch if it already exists). It starts from --base <branch> or, if you don’t pass it, from the branch of origin/HEAD, main or master.
  2. Moves the task to Working (the first animated status of the catalog; --status picks another one).
  3. Records the work session.
  4. Prints the path to enter.

It runs nothing else: it doesn’t install dependencies or launch the agent. Without --worktree, fxc tasks start <id> does steps 2 and 3 in the current directory.

The work session

Every fxc tasks start and fxc tasks finish sends the git context of where it runs:

Data Where it comes from
Branch git rev-parse --abbrev-ref HEAD
Worktree and whether it’s the main one git rev-parse --show-toplevel and git worktree list --porcelain
Machine the computer name (hostname)
Agent --agent <name> or the environment variables each one sets: CLAUDECODE (claude-code), CODEX* (codex), CURSOR_TRACE_ID (cursor), GEMINI_CLI (gemini)… If there is none, manual
Files touched git diff --name-only <base>...HEAD plus what’s pending and uncommitted, up to 300 paths

With that, FXCode keeps one session per task, machine and worktree: start, last heartbeat and end.

  • Heartbeat. Any fxc command on that task (tasks get, update, comment, arch link, arch focus --task…) refreshes it. To refresh it on purpose (and send the files touched): fxc tasks heartbeat <id>.
  • Idle. A session without a heartbeat for 15 minutes turns “idle”: it stays in the panel, dimmed, but no longer counts for clashes.
  • End. fxc tasks finish <id> closes it.

The “In parallel” panel

Every project has the In parallel tab: one row per open session with the task, the agent, the machine, the branch or PR, the worktree and the last activity. Below it, the architecture diagram with the pieces the active sessions touch lit up (the ones linked to their task and the ones they have in focus). It refreshes by itself.

Possible clash

A red warning appears when two active sessions touch the same piece of the architecture, or the same files (the ones the CLI sends in its heartbeats). The piece turns red in the diagram. It’s a warning, not a lock: two agents can touch the same API without stepping on each other, but it’s worth knowing before you merge.

The same from the terminal:

fxc worktrees status --project-id <projectId>
# … table of sessions …
# ! Possible clash: «Pagos recurrentes» and «Login con GitHub» (pieces api; files src/shared.ts)

Clean up when done

fxc worktrees            # the worktrees of the current repo: branch, task, status and whether it's merged
fxc worktrees prune      # offers to delete the merged ones or those whose task is finished
fxc worktrees prune --yes

fxc worktrees matches each worktree to its task by the id in the branch or by the recorded session. prune offers to delete those whose branch is already merged into the base or whose task is finished (or PR merged), and asks for confirmation unless you pass --yes. It never deletes:

  • the main worktree or the current one;
  • one with uncommitted changes (it warns you and leaves it);
  • a locked one (git worktree lock);
  • one whose branch is “merged” but whose task is still Working (a freshly created branch with no commits is also contained in the base).

It deletes with git worktree remove. On Windows, if that fails because of paths that are too long, it deletes the folder and runs git worktree prune. Branches are not deleted.

On the web, the panel shows “N worktrees to clean up” with the machine and folder of each one. The web can’t delete anything on your machine: run fxc worktrees prune in the repo on each one.

From an agent over MCP

Tool What it does
report_work_session Opens or refreshes the session of a task (end: true closes it). In the local MCP it takes the git context of the server’s directory; in the remote one you pass branch, worktreePath, hostname, agent and files
parallel_work The project’s panel: sessions, possible clashes and worktrees to clean up

Rule for agents

When you launch work in parallel, open each line with fxc tasks start <id> --worktree and work inside that folder. When done, fxc tasks finish <id> from the worktree and, once the branch is merged, fxc worktrees prune.