Influxx CLI Worktree and Terminal Commands for Agents
Influxx CLI worktree and terminal commands let you list, create, and orchestrate isolated checkouts and agent shells from the command line. This guide covers the shipped Influxx worktree and terminal command groups so you can spin parallel experiments, attach a second agent to the active tree, and script the same isolation model the cockpit uses in the UI—without inventing flags that are not in product notes.
Why Worktrees and Terminals Matter in the Influxx CLI
Influxx isolates agent work in git worktrees (workspaces) and runs coding CLIs inside worktree-scoped terminals. The CLI exposes that model to scripts and to agents that drive Influxx themselves. Creating a worktree with --agent and --prompt mirrors New Workspace in the UI: an isolated checkout plus an optional first agent. Creating a terminal with --worktree active attaches another session—often a second CLI—to a tree you already selected. Prefer --json whenever another process needs to parse the result.
The Influxx CLI talks to a running Influxx app (or a headless serve runtime). Register the launcher from Settings → General / CLI before these commands will resolve on PATH. Examples below use the brand name influxx; on Linux PATH installs the binary may be influxx-ide, and dev builds use influxx-dev—the command tree is the same. Influxx desktop currently ships for macOS Apple Silicon; use these CLI groups wherever your registered launcher can reach a running cockpit.
Worktree create scopes the checkout. Terminal create attaches another session to a worktree you choose. The same isolation rules apply in the CLI and in the UI.
Worktree Commands Reference
Product notes document a focused worktree group for list, show, current, create, set, remove, and an orchestration summary via ps. Use these when you need fleet-style parallel runs or when an outer agent should open isolated trees without clicking New Workspace.
- influxx worktree list: list worktrees the cockpit knows for your projects
- influxx worktree show: show details for a worktree context
- influxx worktree current: print the currently selected / active worktree
- influxx worktree create: create a named task worktree, optionally with agent and prompt
- influxx worktree set: update worktree metadata (optional --comment)
- influxx worktree rm: remove a worktree by id
- influxx worktree ps: orchestration summary across worktree-backed processes
Creating a Worktree with an Agent and Prompt
The create command is the scripted equivalent of opening an isolated workspace and optionally launching a coding agent into it. Product notes show:
influxx worktree create --name <task> [--agent <id>] [--prompt "..."] [--no-parent] [--json]
- --name: task-oriented name for the new worktree
- --agent: optional agent id so Influxx can launch that CLI in the new tree
- --prompt: optional prompt string the agent should start from
- --no-parent: create without tying the experiment to a parent workspace relationship when you want a clean parallel run
- --json: machine-readable output for scripts and outer agents
Recipe: Spin a Parallel Experiment
To compare two implementations of the same goal, create two isolated worktrees with different agents and the same prompt. Product notes recommend this pattern for parallel experiments:
- Experiment A: influxx worktree create --name exp-a --no-parent --agent codex --prompt "Refactor auth middleware" --json
- Experiment B: influxx worktree create --name exp-b --no-parent --agent claude --prompt "Refactor auth middleware" --json
- Inspect fleet: influxx worktree list and influxx worktree ps to see trees and orchestration summary
- Focus one tree: influxx worktree show / current as you review winners in the UI Source Control panel
Each create with --no-parent keeps experiments from sharing a dirty parent checkout. Agents run in their own isolated git worktrees—the same isolation model as parallel agents in the cockpit. When you are done, remove trees you no longer need with influxx worktree rm <id> after you have merged or discarded the branch work in Source Control as usual.
Terminal Commands Reference
Terminals are where coding CLIs actually run. The terminal group lets you list sessions, create a new terminal on a worktree with an explicit command, send input, read output, wait for TUI idle, split, switch, and close. Use terminal create when a worktree already exists and you want another agent or shell on that same checkout.
- influxx terminal list: list terminal sessions
- influxx terminal create: create a terminal on a worktree with --command
- influxx terminal send: send --input to a session
- influxx terminal read: read terminal output
- influxx terminal wait: wait --condition tui-idle for agent TUIs to settle
- influxx terminal split: split the terminal surface
- influxx terminal switch: switch focus between terminals
- influxx terminal close: close a terminal session
Create a Terminal on the Active Worktree
Product notes show a canonical create for a second agent on the tree you are already using:
influxx terminal create --worktree active --command "claude" --json
Substitute the command string for the CLI you want—for example "codex" when a second agent should collaborate on the same branch. This is intentional same-checkout multi-agent work, not a competing isolated experiment. Prefer worktree create with --no-parent when you need fully isolated competing implementations.
Second agent, same tree: terminal create --worktree active --command "codex" --json. Parallel experiment: two worktree create calls with --no-parent and different --agent values.
Driving an Existing Terminal Session
After a terminal exists, scripts can send input, read output, and wait until a TUI agent is idle before the next step. Product notes document:
- Send: influxx terminal send --input "..."
- Read: influxx terminal read
- Wait: influxx terminal wait --condition tui-idle
- Layout: terminal split and terminal switch for multi-pane focus
- Cleanup: terminal close when the session should end
Note-Driven Workflow Without a Notes Subcommand
There is no influxx notes list|open|new|run group today. Create plan files under .influxx/notes (or use Sidebar Notes in the UI), open them with the file group when needed, then launch an agent terminal on the active worktree. Product notes show a file-based recipe: mkdir -p .influxx/notes, write a markdown plan, influxx file open --path .influxx/notes/ship-auth.md, then either Run from the sidebar or influxx terminal create --worktree active --command "claude" --json.
Export context under .influxx/context when agents need packaged material from the worktree. Keep the plan as ordinary markdown so it stays reviewable in git and in the markdown editor tabs. The CLI bridge does not replace Sidebar Notes—it complements them for automation.
Practical Sequencing for Scripted Agent Work
A reliable order for outer agents and shell scripts: verify the bridge with influxx status --json; inspect or select context with worktree list / current; create an isolated tree with worktree create when you need isolation; attach extra CLIs with terminal create --worktree active; drive interactive TUIs with send, read, and wait --condition tui-idle; summarize with worktree ps; remove finished trees with worktree rm when cleanup is appropriate. Always keep claims aligned with influxx agent-context --json for the live schema on your build.
- Status first: confirm the CLI reaches the running Influxx app or serve runtime
- Isolate when competing: worktree create --no-parent for parallel experiments
- Collaborate on one branch: terminal create on --worktree active
- Prefer JSON: --json on create and status paths for scripting
- Discover live flags: influxx agent-context --json and influxx help
Related reading: install and binary names for PATH registration (influxx / influxx-ide / influxx-dev), and the browser and orchestration article for tab automation, gates, recipes, and agent-context schema groups beyond worktrees and terminals.
