Influxx Worktree Board, Statuses, and Merge Cleanup
Influxx keeps multi-agent work finishable with three ideas working together: isolated worktrees (workspaces), a Workspace Board with clear statuses, and an honest merge-and-cleanup loop that ends on your git host—not a fake “merge worktree” verb. This guide walks through creating a workspace, what isolation actually means, how board statuses and sidebar filters keep fleets legible, and how to review, merge, and delete worktrees safely after the branch lands.
Create a workspace (New Workspace)
Open New Workspace with ⌘N / Ctrl+N (also ⌘⇧N), or start creation from the worktree/command palette. In the composer, pick the project or repo, the agent, the prompt, the base branch, and the setup policy. Optionally link a GitHub, GitLab, or Linear task and enable smart naming. Confirm—Influxx creates the git worktree and can launch the agent in the first terminal. You can also start a workspace from the Tasks page when an issue is ready, or from the CLI when scripting fleets of experiments.
Composer fields that matter:
- Project / repo: Which tracked project owns the new checkout
- Agent: Which CLI agent to launch in the first terminal
- Prompt: The initial brief the agent receives
- Base branch: Where the feature worktree branches from
- Setup policy: run, skip, or inherit hooks/scripts on create
- Task link + smart naming: Optional host issue link and readable worktree names
Other entry points include the tab strip (new terminal / new agent / Quick Commands), Sidebar note Run (context pack plus CLI tab from a plan), Tasks (start workspace from a GitHub, Linear, or Jira item), Automations (scheduled prompt runs), and the Influxx CLI. Example CLI pattern (command name is influxx; Linux PATH installs may use influxx-ide; dev builds may use influxx-dev):
influxx worktree create --name feat-auth --agent codex --prompt "Implement OAuth" --json
influxx terminal create --worktree active --command "claude" --json
influxx terminal create --worktree active --command "claude" --json
Isolation is not a setting—it is the default. Agents do not share a dirty tree. Each worktree gets its own filesystem checkout, terminals, browser pages, and notes so parallel work stays honest.
Isolation model
Isolation means separate filesystem checkouts. Each worktree owns its terminals, browser pages, emulator state, and .influxx/notes. Setup scripts and hooks can run when a worktree is created (--setup run|skip|inherit). Sparse checkout presets are available in the composer when you only need part of a large repo. Parent lineage supports stacked work; use --no-parent (CLI) or the equivalent independent option in the product flow for competing experiments that should not inherit a parent chain.
What stays per-worktree:
- Checkout: A real git worktree path—not a shared dirty tree across agents
- Terminals and agents: Worktree-scoped PTYs; each agent tab is a real shell session in that tree
- Browser / emulator: Tabs and state bound to that workspace
- Sidebar notes: Plans under .influxx/notes/ in the worktree
- Review notes and comments: Diff line notes and the sticky workspace comment in worktree metadata
- Setup hooks: Per-repo bootstrap (install deps, env files) when policy allows
Stacked work vs independent experiments
Parent lineage is for stacked work: a feature worktree can sit in a chain so later work builds on earlier isolation. When you want independent experiments—same prompt, competing approaches—create sibling worktrees with --no-parent so they do not inherit parent lineage. Fan one plan across many agents by creating multiple worktrees, each with its own checkout and agent. Compare diffs, keep the winner, delete the rest. For a second agent on the same checkout, open a new terminal with a different CLI command instead of a new worktree.
Board and statuses
The Workspace Board is a kanban view over four statuses: Todo, In progress, In review, and Done. Use it to see every workspace’s stage without opening each terminal. The sidebar supports group-by, smart sort, and filters for sleeping workspaces so long-running or parked work does not hide active agents. Set a sticky comment on a worktree via Edit Worktree Details (Comment field; markdown-lite supported) or via the CLI: worktree set --comment. A non-empty comment shows a Workspace notes badge on the card; hover for the rendered comment and Edit notes. Comments are searchable in the worktree palette—they are short sticky fields, not documents in .influxx/notes.
Board statuses:
- Todo: Created or queued; not actively coding yet
- In progress: Agent or you are working in that worktree
- In review: Diffs and PR checks need human attention
- Done: Work accepted; ready for merge cleanup or archival sleep
Workspace comments are not the same as Sidebar notes or review notes. Sidebar notes are markdown plans you Run into an agent. Review notes are line comments on diffs you send back to an agent. The board comment is the one-liner that makes a card scannable in a multi-workspace day. Move cards deliberately as work advances so sleeping filters and smart sort keep the active lane visible.
Merge and cleanup
There is no special “merge worktree” product verb beyond git. The flow is: the agent works in a feature worktree; you review diffs, annotate, commit, and push from Source Control (⌘⇧G / Ctrl+Shift+G); you create a PR or MR and watch Checks / PR Checks; you merge on the git host (GitHub, GitLab, or your provider). After the branch is merged (or abandoned), delete the workspace in the UI—Delete Workspace runs a preflight for dirty state and lineage—or remove it from the CLI with worktree rm. Sleeping workspaces and board Done status help you park work before you remove it.
Merge & cleanup sequence:
- 1. Work: Agent (or you) codes in a feature worktree
- 2. Review: Diffs, annotate with review notes, commit, push from Source Control
- 3. Host review: Create PR/MR; watch Checks / PR Checks in-app
- 4. Merge: Merge on the git host—Influxx does not invent a separate merge-worktree action
- 5. Delete: Delete Workspace in the UI (preflight for dirty state / lineage) or influxx worktree rm
Preflight before delete
Preflight matters: if the worktree is dirty or sits in a parent lineage, the product warns before removal so you do not discard uncommitted work or break stacked dependents by accident. Prefer merging (or explicitly abandoning) and cleaning the tree before delete when the preflight complains. Losing a worktree does not un-merge a PR on the host—cleanup is local product state plus the git worktree checkout, not host history.
Practical recipe: parallel experiment
From the CLI (or twice from New Workspace with the same prompt): create two independent worktrees with different agents, same goal—for example exp-a with Codex and exp-b with Claude, both --no-parent. Track both cards on the Workspace Board from Todo through In review. Compare diffs in Source Control, promote the winner through PR and merge on the host, then Delete Workspace (or worktree rm) on the losers. Use Done and sleep filters so abandoned experiments do not clutter the active list while you finish checks.
Useful worktree CLI verbs:
- list / show / current: See worktrees and which one is active
- create: --name, optional --agent, --prompt, --no-parent, --json
- set: Update metadata such as --comment
- rm: Remove a worktree by id
- ps: Orchestration summary across worktrees
Projects hold the repos. Worktrees hold the isolation. The board holds the status. Merge on the host; clean up in Influxx. That loop is how multi-agent work stays safe and finishable.
Quick reference: Add a project from the left sidebar. Select the main worktree or create a feature workspace with New Workspace (⌘N). Let setup hooks run if the repo needs them. Launch or attach agents in that worktree only. Move the card across Todo → In progress → In review → Done. Review, commit, push, open PR/MR, wait on Checks. Merge on GitHub, GitLab, or your host. Delete Workspace when preflight is clean—or sleep the workspace until you are ready. For competing ideas, multiply worktrees, not agents on one dirty tree.
