Skip to content

Agents

ffgit works with the coding agents you already have: it starts the installed Claude Code and Codex CLIs, signed in with your own account. ffgit does not provide a model or resell tokens. Conversations themselves are covered on Chat.

  1. Choose Agents → Start agent task…, or Start agent task… in a branch’s menu. A new chat opens in Chat as a draft.

  2. Write the task, pick the agent, the login, the model and effort, and whether it works in this worktree or a new one. Templates fill the task with one of twelve ready-made prompts — such as a review that leaves git status as it is — or with your own.

  3. Start it. ⌘↩︎ starts it and keeps the draft, so the same task can go to another agent or model, each in a new worktree with the next free name.

A new worktree gets a free branch named after the agent and the task, in a folder beside the main checkout. From a branch’s menu the chat works in the worktree that has the branch checked out, or in a new worktree whose branch starts from it; Stack on makes that new branch a stacked branch.

Of several installs of Claude Code or Codex, ffgit runs the newest one that works. When it is behind the latest release, New chat says so and Update runs the agent’s own update in Terminal.

A new worktree for an agent can first run the project’s worktree setup: copy ignored files from the main checkout, run commands and check paths. It runs only after you reviewed every step, in the background with Cancel, and the agent starts once it is done.

  • Keep the setup On this Mac or In the repository, as .ffgit/worktree-setup to commit and share.
  • The editor starts from what the project already has for other tools — Codex’s local environment, Cursor’s worktrees.json, Conductor’s setup script, Claude Code’s .worktreeinclude — or a guess from its lockfiles and ignored .env files.
  • Steps find the main checkout and the worktree in $FFGIT_SOURCE_PATH and $FFGIT_WORKTREE_PATH.

Project actions… in a worktree’s menu keeps named commands, such as Run tests, and a settle script that runs when you settle a chat. In Chat, a chat’s menu runs them in its worktree, each as a tab in a drawer under the conversation.

An action whose name ends with [server] is a dev server: it gets a free port in $PORT and $FFGIT_PORT, the same one each time while it is free, so two worktrees’ servers never collide. Its tab shows the http://localhost:<port> address with Open, Copy and Restart once it listens.

For Claude Code, ffgit reads the status file Claude Code keeps for each running session (~/.claude/sessions/<pid>.json): working, waiting for permission or input, idle, or a response ready after a turn. A run started from ffgit also says what it waits for — Needs permission, Asking a question, Waiting for you, Rate limited, Error and more — from session-only hooks that are never written to your settings files. Chats ffgit runs report their status on their own stream.

Agents has two tabs:

  • Sessions — ffgit’s runs, live Claude Code sessions and discovered Codex and Claude Code sessions in one list or board: Needs you, Working, Ready, Errors, Idle. Filter by project, agent and status, and narrow the scope to a worktree, a project, the workspace or all projects. A double-click opens the chat in Chat.
  • Activity — one inbox for questions, ready responses and failures, with Needs you, Ready for review, Errors and All activity views. The rail and the bell count unread threads of the window’s workspace.

Jump to… (Cmd/Ctrl+K) finds chats, projects, worktrees, branches and menu actions by words in any order, and chats by their messages once you allow it (see Finding a chat). Waiting for you (Cmd/Ctrl+Shift+I) lists only the chats that wait for your answer, the longest waiting first.

The sidebar shows agents inside the project tree: status counts on each project, a glyph on each worktree and up to three agent rows under it. Worktrees group by state: active ones first, then Done (every commit already in the default branch) and Unavailable.

With Notify me when a chat needs me (off by default), a chat that waits or finishes while ffgit is in the background raises a macOS notification and the Dock counts the chats that wait. You pick the kinds (Needs you, Finished, Failed, Setup), the sound and whether a notification names the task. While ffgit is active, the window shows the same as a toast.

An agent ffgit starts in Terminal first gets a task baseline: the worktree as it is at that moment, stored as Git objects only, with no commit, ref, stash or index change. Compare with task start… shows Since task started, Current uncommitted changes and Commits since launch base, worded as changes observed, never as the agent’s.

A session’s detail shows everything its chat keeps on this Mac — the conversation, scratchpad and task output, images and plans, and the worktree an agent tool made for it — split into what can be freed (written again by the next run), what to free with care and what is kept.

  • The Agents list shows each chat’s size with totals per project, and the agent worktrees it counts.
  • Clean up chats… lists chats older than an age you pick and deletes them or frees their space, one at a time, skipping any that run or whose files a process holds.
  • Free build output… moves the build output and packages of agent worktrees to the Trash; .env, other ignored files and the worktrees themselves stay.
  • Remove agent worktrees by themselves, in Cleanup, removes idle agent worktrees by a rule you pick, with a recovery copy first.