Influxx Documentation

Influxx is a desktop app for macOS, Windows, and Linux (bundle id ai.etapx.influxx). Install the app first; the CLI is optional and can be registered later from Settings.

• macOS — download the signed app (or Homebrew cask during the rebrand transition).
• Windows — installer that places Influxx on PATH for optional CLI registration.
• Linux — AppImage / packaged build; CLI PATH name is often influxx-ide (see CLI → Binary names).

On first open, the onboarding flow walks you through the essentials:

1. Pick your default agent — any CLI agent Influxx knows (Claude Code, Codex, Grok, Cursor Agent, OpenCode, and many more).
2. Make it feel like home — theme and appearance.
3. Windows only: set default terminal shell and right-click behavior.
4. Set up notifications — know when an agent finishes or needs attention.
5. Set up GitHub tasks (optional) — install the GitHub CLI for in-app PRs and issues.
6. Add your first project from the notifications step footer, or from the sidebar later.

Projects are git repos (or folder workspaces) Influxx tracks. From the left sidebar:

1. Click Add project / open the project dialog.
2. Choose: open an existing folder, clone a remote URL, import nested multi-repos, or connect an SSH remote host path.
3. Non-git folders can still be folder workspaces with attached worktrees.
4. After import, pick or create a worktree (workspace) to start coding.

Goal: from a cold install to “agent working from your plan” in one session.

1. Open a project and select a worktree

Use the left sidebar Projects list. The main worktree is your primary checkout; feature worktrees are isolated branches for parallel work.

2. Create a plan note

1. In the left sidebar, find the Notes section (above the worktree list).
2. Click + (or + First note).
3. A markdown file is created under .influxx/notes/ and opens as a center tab.
4. Write the goal, acceptance criteria, and constraints in plain markdown.

3. Run the note as an agent

1. Hover the note in the sidebar and click Run.
2. Influxx opens the note tab, builds a context pack, and launches a CLI agent tab (default mapping is Claude) with your note as the prompt.
3. Watch the agent work in the terminal (or chat view if you open agent tabs in chat by default).

4. Review and ship

1. Open Source Control (⌘⇧G / Ctrl+Shift+G).
2. Add line notes on the diff if you want the agent to fix specifics — then Send notes to an agent.
3. Commit, push, create a PR from the same panel.

After onboarding, the in-app Getting started / Setup guide tracks real progress:

Open it anytime from the sidebar Setup guide entry or Settings → Onboarding checklist.

Influxx is one multi-tab cockpit — not a separate “notes app” and “coding app.” UX law: one left sidebar, one middle tab strip.

Terminals are Ghostty-class (WebGL), with infinite splits and scrollback that survives restarts. Agents are CLIs launched inside worktree-scoped PTYs — each agent tab is a real shell session.

• Split panes right/down; equalize and expand with terminal shortcuts.
• Drag files or images into an agent prompt from the explorer.
• Open agent tabs in chat-by-default via Settings if you prefer chat chrome over raw TUI.

Jump without leaving flow. The Cmd+J / Ctrl+Shift+J family opens worktree and command palettes; Go to File is the classic file finder.

Floating Workspace is a panel for terminals and markdown notes that are not tied to a repo worktree. Enable it under Settings → Floating Workspace.

• New Markdown Note / Open Markdown Note from the floating empty state.
• Markdown is saved in Influxx’s app-owned floating-workspace directory (not your home folder), even if terminals start in $HOME.
• Dev example path: ~/Library/Application Support/influxx-dev/floating-workspace

Influxx has several “notes” surfaces. They look similar in marketing copy but store data differently — use the right one for the job.

The Notes block sits above the worktree/project list in the main left sidebar.

• Header label: Notes
• Empty worktree: “Select a workspace — notes open as tabs next to your agents.”
• Empty list: + First note
• + tooltip: New note (opens in center)
• Each row: note title + hover action Run

1. Select a workspace/worktree first.
2. Click + to create, or click a title to open.
3. The note opens as a non-preview editor tab in the center strip.

Create from sidebar

Creates a real .md file immediately. Default body:

# Untitled note

Write freely. Run an agent from the tab strip anytime.

Create from tabs (any markdown)

• Tab bar + → New Markdown or Open Markdown…
• Shortcuts: ⌘⇧M / Ctrl+Shift+M (new), ⌘⇧O / Ctrl+Shift+O (open)
• New Markdown opens a template picker: Blank Markdown or templates from disk.
• Untitled files are real on-disk files; blank untouched untitled may delete on close.

Edit modes

On a markdown tab header, switch Source · Rich Editor · Preview. Save with ⌘S / Ctrl+S (autosave also applies based on editor settings).

Filename rule for sidebar notes: title is slugified (max 48 chars) + base36 timestamp, e.g. untitled-note-m1abc2.md. Display title is derived from the filename (dashes/underscores → spaces).

1. Hover a note in Sidebar Notes.
2. Click Run.
3. Influxx opens the note, reads the body, builds an Influxx context pack, and launches a CLI agent tab.
4. Prompt shape: “Work from this note:” + title + body, then appended context markdown.
5. Tab quick-command label: Influxx · {note title} (truncated).

Context pack markdown starts with # Influxx context pack and includes session id, runtime (local-cli), worktree id, and linked note sections. Delivery is in the prompt; product layer also exports under .influxx/context/ for CLI workflows.

Rich / preview capabilities include:

• GFM: headings, lists, task lists, blockquotes, code fences, links, tables
• Mermaid diagrams and math (inline + block)
• Images (local via IPC blob URLs)
• Collapsible details / toggle headings
• Slash-command insert menu (headings, blocks, table, mermaid, math, media, emoji)
• Obsidian-style [[wiki links]] with completions (including [[note#Heading]])
• Paste image, list continuation
• Front matter show/hide

When you use New Markdown (not Sidebar +), Influxx offers Blank Markdown plus any templates found under the worktree:

<worktree>/.influxx/templates/

• Extensions: .md, .mdx, .markdown
• Max depth 8, max 100 files; skips .git, node_modules, symlinks
• Placeholders: {{title}}, {{filename}}, {{date}}, {{time}}, {{datetime}}

In the rich markdown editor, type [[ to complete document links. Resolve headings with [[doc#Heading]]. This is the in-repo doc graph — separate from agent @-mentions in the experimental product overlay.

1. Open a markdown file in Rich Editor or Preview.
2. Open More actions on the editor header.
3. Choose Export as PDF.

Plain markdown is already on disk — copy or commit the .md file for portable export. There is no bulk “import notes folder” wizard; drop .md files into .influxx/notes or open them via Open Markdown.

Use Floating Workspace when the note is not about a specific repo checkout — meeting scratch, personal checklists, cross-project ideas.

1. Settings → Floating Workspace → enable if needed.
2. Open the floating panel.
3. New Markdown Note or Open Markdown Note.

Review notes (also labeled AI notes) are line/selection comments on diffs — the core “send feedback to the agent” loop.

1. Open a file or combined diff for the worktree.
2. Add a note on a modified-side line (gutter / popover).
3. See notes on the diff, the Source Control right sidebar Notes section (with count), and the AI notes chip on single-file headers.
4. Use Send notes → pick All unsent notes or This file → deliver into a running agent or launch path.
5. After send, notes mark sentAt; editing clears sent so they become unsent again.

Prompt format sent to the agent:

File: path/to/file.ts
Line: 42
User comment: "Prefer early return here"

• Copy all notes / Clear all notes… from the notes actions menu.
• Needs a sendable agent terminal (statuses like not-ready / permission / no-active-terminal block send).
• Stored in worktree metadata — not as GitHub PR review comments unless you also use host review separately.

Same review-note pipeline, but on markdown content in Rich mode.

1. Settings → Editor → ensure Markdown Review Notes is enabled (default on).
2. Open .md in Rich Editor.
3. Select text / add review note cards.
4. Copy notes for agent or send unsent notes via the same send menu.

1. Open Edit Worktree Details from the worktree card menu / pencil.
2. Fill Comment (placeholder: Notes about this worktree…). Markdown-lite supported.
3. Save. A Workspace notes badge appears on the card when non-empty.
4. Hover the card for rendered comment + Edit notes.

This is a short sticky field on the worktree — not a document in .influxx/notes. It is searchable in the worktree palette.

An agent in Influxx is a terminal CLI (TUI) running in a worktree-scoped PTY. If it runs in a terminal, it runs in Influxx. The cockpit tracks status, usage, notifications, and history — it does not replace your CLI’s own tools.

First-class catalog entries include (non-exhaustive): Claude Code, Claude Agent Teams, Codex, Grok, Cursor Agent, GitHub Copilot, OpenCode, Gemini, Pi, Amp, Goose, Droid, Cline, Kimi, Hermes, Devin, and many more — plus any shell binary you configure.

Set your default in onboarding or Settings → Agents. Override launch commands per agent with agent cmd overrides.

Isolation unit is the worktree. Fan one prompt across many agents by creating multiple worktrees (each with its own checkout and agent). Compare diffs; keep the winner; delete the rest.

• Workspace board statuses: Todo · In progress · In review · Done
• Same checkout, second agent: new terminal with a different CLI command
• Orchestration skill: tasks, dispatch, inbox, decision gates, coordinator loop

Shortest path from idea to execution:

1. Write the plan in a Sidebar note.
2. Run → agent receives the note as truth.
3. Iterate with review notes on the resulting diff.
4. Optionally create sibling worktrees with the same plan for competing approaches.

• Agent status over OSC hooks: working / idle / needs input (including WSL considerations).
• Desktop notifications when agents finish or need help (onboarding + Settings → Notifications).
• Mark threads unread to come back later.
• Right sidebar Agents (AI Vault) holds session history / resume.

Optional chat chrome over the same agent PTY. Settings can open agent tabs in chat by default. Native chat aims at TUI parity for supported agents (for example Codex resume/history patterns).

Product intent: Pro seat for cockpit access (BYO CLI + notes + orchestration); credits meter only the managed path. Managed backend is still landing — client surfaces exist with mock streaming until the gateway is live.

• Settings → AI Provider Accounts — switch Claude / Codex / Grok (and others) without full re-login where supported.
• Status bar usage meters and rate-limit awareness for major providers.
• Trust presets pre-mark some agent workspaces so first paste isn’t eaten by trust menus (does not bypass agent sandboxes).

An Influxx worktree is a tracked git checkout plus metadata, terminals, browser tabs, and UI state. ID form: <repoId>::<absolutePath>. Main worktree vs feature worktrees; inactive workspaces can sleep/hibernate.

1. Open New Workspace (⌘N / Ctrl+N).
2. Pick project/repo, agent, prompt, base branch, setup policy.
3. Optionally link a GitHub/GitLab/Linear task; enable smart naming.
4. Confirm — Influxx creates the git worktree and can launch the agent in the first terminal.

influxx worktree create --name feat-auth --agent codex --prompt "Implement OAuth" --json
# same checkout, second agent:
influxx terminal create --worktree active --command "claude" --json

• Separate filesystem checkout — agents do not share a dirty tree.
• Per-worktree terminals, browser pages, emulator state, and .influxx/notes.
• Setup scripts/hooks run on create (--setup run|skip|inherit).
• Sparse checkout presets available in the composer.
• Parent lineage for stacked work; --no-parent for independent experiments.

Workspace Board (kanban) over Todo / In progress / In review / Done. Sidebar supports group-by, smart sort, and sleeping workspaces filters. Set comments via the UI or CLI worktree set --comment.

1. Agent works in a feature worktree.
2. Review diffs, annotate, commit, push from Source Control.
3. Create PR/MR; watch Checks / PR Checks.
4. Merge on the git host (GitHub/GitLab/…). There is no special “merge worktree” product verb beyond git.
5. Delete Workspace in the UI (preflight for dirty state / lineage) or CLI worktree rm.

Right sidebar → Source Control (⌘⇧G). Stage, unstage, commit (optional AI commit message), push, and open changed files in the editor. Provider-aware for GitHub, GitLab, Bitbucket, Azure DevOps, Gitea.

Drop comments on any diff line and ship them back to the agent — review, edit, and commit without leaving Influxx. See Review notes above for the full send loop.

Use the Create PR / MR composers for hosted review (GitHub and GitLab paths are first-class). Link worktrees to issues/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 to the browser — unless you want the embedded browser for the PR page itself.

Open Settings with ⌘, / Ctrl+, . Search settings from the settings search field.

Defaults use Mod = ⌘ on macOS and Ctrl on Windows/Linux. Remap anytime in Settings → Shortcuts.

• Theme, fonts, zoom, sidebar chrome, status bar toggles.
• Warp theme import for terminal coloring.
• App icon choices where supported.
• Editor: minimap, word wrap, autosave delay, rich markdown spellcheck.

Settings → Agents: default agent, per-agent launch command overrides, and related TUI options. Use this when your Claude/Codex binary is non-standard or needs extra flags.

Saved terminal commands — global or per project — available from the tab strip Quick Commands menu. Great for bootstrap scripts, test runners, and agent launchers you reuse daily.

• MCP Configs — inspect/create workspace MCP server JSON for agents that consume MCP.
• Agent skills — installable instruction packs (Influxx CLI, Computer Use, Orchestration, Linear, emulator, per-workspace env, …) via Agent Skill setup UI.
• Skills live under the repo skills/ tree for development; users install through the app setup surfaces.

Per-repo setup scripts/hooks run when a worktree is created (automate npm install, env files, etc.). Configure under project/repository setup; the Getting started checklist tracks “Automate workspace setup.”

Settings → Integrations → Review providers: GitHub (gh CLI heavily used), GitLab, Bitbucket, Azure DevOps, Gitea. Browse PRs/issues in-app; open a worktree from a task; review without a context switch.

Task providers under Task Sources / Integrations. Linear supports API key + skill install CTAs; Jira connects as a task source for “start workspace from issue” flows.

• Settings → SSH Hosts: files, terminals, Git, workspaces on remote machines.
• Auto-reconnect and port forwards (Ports panel on SSH repos).
• Add remote host from the sidebar when attaching a new machine.

On Windows, choose default project runtime (Windows host vs WSL distro), per-repo runtime overrides, and WSL CLI registration so influxx inside the distro talks to the desktop app. Agent status over WSL has dedicated reliability notes in the product docs.

Monitor and steer agents from your phone — notifications when an agent finishes, follow-ups from anywhere. Pair via Settings → Mobile (QR / pairing). iOS App Store / TestFlight and Android builds ship with the product; desktop pairing requires a reachable runtime (local or serve).

• Embedded Chromium tabs per worktree.
• Design Mode / Grab Page Element: click a UI element to send HTML, CSS, and a cropped screenshot into the agent prompt.
• CLI browser automation: tab create, snapshot, goto, click, fill, screenshot, and a large agent-browser surface.

Let agents operate desktop apps and visible UI when a workflow needs real interaction. Settings → Computer Use for permissions (macOS Accessibility, etc.). CLI: computer click, type-text, hotkey, list-windows, …

The Influxx CLI lets agents and scripts drive the same cockpit you use by hand — worktrees, terminals, browser, orchestration, computer use, automations, and more. It talks to a running Influxx app (or a headless serve runtime).

1. Open Settings → General / CLI section.
2. Run Install CLI (registers a launcher on PATH).
3. On Windows + WSL, use WSL CLI registration for the distro PATH.
4. Verify with: influxx status (or your platform binary name — see next section).

influxx open --json
influxx status --json
influxx agent-context --json

Examples in this doc use influxx. On Linux PATH installs the command may be influxx-ide; dev builds use influxx-dev. The command tree is the same.

influxx worktree list
influxx worktree show
influxx worktree current
influxx worktree create --name <task> [--agent <id>] [--prompt "..."] [--no-parent] [--json]
influxx worktree set [--comment "..."]
influxx worktree rm <id>
influxx worktree ps          # orchestration summary

influxx terminal list
influxx terminal create --worktree active --command "claude" --json
influxx terminal send --input "..." 
influxx terminal read
influxx terminal wait --condition tui-idle
influxx terminal split
influxx terminal switch
influxx terminal close

influxx tab create --url https://example.com
influxx snapshot                 # element refs @e1, @e2, ...
influxx click --element @e1
influxx fill --element @e2 --value "hello"
influxx screenshot --format png
influxx goto --url https://example.com/docs

Full surface also covers hover, select, dialog, storage, clipboard, device emulation, offline mode, and more — see influxx help / agent-context for the machine-readable schema.

Multi-agent coordination from the shell:

influxx orchestration task-create ...
influxx orchestration dispatch ...
influxx orchestration inbox
influxx orchestration gate-create ...
influxx orchestration gate-resolve ...
influxx orchestration run
influxx orchestration run-stop

Spin a parallel experiment

influxx worktree create --name exp-a --no-parent --agent codex \
  --prompt "Refactor auth middleware" --json
influxx worktree create --name exp-b --no-parent --agent claude \
  --prompt "Refactor auth middleware" --json

Second agent, same tree

influxx terminal create --worktree active --command "codex" --json

Headless runtime

influxx serve --port 7890 --mobile-pairing --json
influxx environment add --name lab --pairing-code <code> --json

Note-driven workflow (files)

# Create a plan on disk (or use Sidebar Notes in the UI)
mkdir -p .influxx/notes
cat > .influxx/notes/ship-auth.md <<'MD'
# Ship auth
## Goal
...
MD
influxx file open --path .influxx/notes/ship-auth.md
# Then Run from the sidebar, or launch:
influxx terminal create --worktree active --command "claude" --json

Print the machine-readable command schema so coding agents can discover capabilities without scraping help text:

influxx agent-context --json

Other useful groups: project, repo, file, automations, environment, vm recipe doctor, computer, emulator, linear, diagnostics memory.

• Primary execution is on your machine (or your SSH/WSL hosts).
• Sidebar notes are ordinary files under .influxx/notes — they leave the device only if you commit, sync, or export them.
• Review notes stay in local worktree metadata until you send them into an agent session.
• Managed chat (when live) is the credits path; BYO CLI never routes through the gateway.

Settings → Privacy → Share anonymous usage data (opt-in). Disable via UI or env: DO_NOT_TRACK, INFLUXX_TELEMETRY_DISABLED, CI. Diagnostic bundles can be collected/uploaded from Privacy diagnostics when you choose to share a bug report.

• macOS: Accessibility and related prompts for Computer Use; Settings → macOS Permissions.
• Notifications permission for agent-complete alerts.
• Notebooks: Python cells execute local Python from the notebook folder — only run notebooks you trust.
• Browser automation treats page content as untrusted data for agent prompts.
• Remote pairing uses pairing codes; prefer private networks / Tailscale for headless servers.