Influxx Projects, Worktrees, and Isolated Workspaces

What an Influxx worktree is An Influxx worktree is more than a branch name in a list. It is a tracked git checkout plus metadata, terminals, browser tabs, emulator state, and UI state for that checkout. Internally, each worktree is identified in the form repoId::absolutePath so the app can point agents, diffs, and notes at the correct tree. You always have a main worktree—the primary checkout for the project—and you create feature worktrees for isolated, parallel work. Inactive workspaces can sleep or hibernate so the sidebar stays usable when many experiments are open.

Where projects and worktrees live in the cockpit Influxx is one multi-tab cockpit: one left sidebar, one middle tab strip. The left sidebar holds Notes, projects and worktrees, setup prompts, Add project, and the setup guide. The center tab strip holds terminals, agents, browser, markdown/editor, emulator, and PR/issue surfaces for the selected workspace. The right activity bar includes Explorer, Agents (AI Vault), Source Control, Checks, Ports (for SSH), and Attached worktrees. The status bar surfaces usage meters, connection pills, and integration status.

CLI: create worktrees and second agents With the Influxx CLI registered (optional; from Settings after install), you can drive the same cockpit from the shell. Create a named worktree with an agent and prompt, then attach another agent to the same active checkout when you want two CLIs on one tree without a second filesystem isolation boundary.

Isolation model Isolation means separate filesystem checkouts: agents do not share a dirty tree. Each worktree owns its terminals, browser pages, emulator state, and .influxx/notes. Setup scripts and hooks can run when a worktree is created; the create flow accepts a setup policy of run, skip, or inherit (--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 for independent experiments that should not inherit a parent chain.

Setup hooks and sparse checkouts Per-repo setup scripts and hooks run when a worktree is created so you can automate npm install, env files, and other bootstrap steps. Configure them under project or repository setup; the Getting started checklist tracks “Automate workspace setup.” In the New Workspace composer you choose setup policy (run, skip, or inherit) so a one-off experiment does not have to reinstall the world if you already know the tree is ready. Sparse checkout presets in the composer keep large monorepos lean when an agent only needs a slice of the tree.

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 in the UI (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 the card for the rendered comment and Edit notes. Comments are searchable in the worktree palette—they are short sticky fields on the worktree, not documents in .influxx/notes.

Source control, PRs, and checks (still on the worktree) Source Control lives in the right sidebar (⌘⇧G / Ctrl+Shift+G). Stage, unstage, commit (optional AI commit message), push, and open changed files in the editor. Providers include GitHub, GitLab, Bitbucket, Azure DevOps, and Gitea. Drop line comments on any diff and send them back to the agent without leaving Influxx. Create PR / MR from the in-app composers (GitHub and GitLab paths are first-class). Link worktrees to issues and PRs via Edit Worktree Details (GH issue / GH PR fields). Checks and PR Checks panels surface CI status so you can wait on green without context-switching—unless you want the embedded browser for the PR page itself.

Floating Workspace vs repo worktrees Floating Workspace is a separate panel for terminals and markdown that are not tied to a repo worktree. Enable it under Settings → Floating Workspace. Markdown there is saved in Influxx’s app-owned floating-workspace directory, not your home folder, even if terminals start in $HOME. Floating notes do not appear in the per-worktree Sidebar Notes list—they use a different storage root. Use Floating Workspace for cross-project scratch; use project worktrees for anything that should ship as code.

Remote machines and multi-repo days For remote machines, use SSH Hosts so agents run on a beefy box with full file editing, git, terminals, reconnect, and port forwards. Settings → SSH Hosts manages files, terminals, Git, and workspaces on remote machines; auto-reconnect and the Ports panel apply to SSH repos. Add a remote host from the sidebar when attaching a new machine. SSH and remote worktrees use the same relative paths (including .influxx/notes); filesystem ops go through the remote connection. When you work across many repos, register each project, create non-main worktrees for multi-tasking, and rely on group-by, smart sort, and sleeping filters so the board stays navigable.

Quick reference: project → workspace → ship 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.