Influxx FAQ, Troubleshooting, and Setup Checklist
This Influxx help article answers the high-intent questions people ask after install — how to get the app, what first launch does, how notes become agents, where files live, how parallel agents and the CLI work, and what stays local — then walks the in-app setup checklist and a practical troubleshooting map. Answers stay grounded in shipped product Notes: no invented features, and an honest reminder that the public desktop installer currently ships for macOS Apple Silicon first.
Use this page as a FAQ plus recovery guide. For deep dives, open the matching Influxx help topics on worktrees, notes, agents, Source Control, SSH remotes, Design Mode / Computer Use, settings, and the macOS install guide. Keep the Setup guide open in the sidebar until the checklist items that matter for your workflow are done.
From cold install to “agent working from your plan” in one session — then use the checklist so the rest of the cockpit sticks.
Platform and install FAQ
How do I install Influxx? Influxx desktop currently ships for macOS Apple Silicon only (bundle id ai.etapx.influxx). Install the app first; the CLI is optional and can be registered later from Settings. Download the notarized DMG (influxx-macos-arm64.dmg) from GitHub Releases or the download page, or use Homebrew:
brew install --cask influxx (stable) or brew install --cask influxx@rc (release candidates). Intel Macs and non-macOS desktops are not covered by this public installer track. Product Notes still mention Windows-only onboarding steps and WSL runtimes for when those surfaces apply — treat them as platform notes, not as a same-day Windows DMG claim.
Install quick facts:
- Architecture: Apple Silicon (arm64) only for the public desktop channel
- Channels: Direct DMG or Homebrew cask (stable / RC)
- CLI: Optional; Settings → General / CLI → Install CLI after the app is running
- Dev builds: Source builds use pnpm run dev; userData may live under influxx-dev
First launch and quickstart FAQ
What happens on first launch? Onboarding walks you through essentials: pick your default agent (Claude Code, Codex, Grok, Cursor Agent, OpenCode, and others Influxx knows), set theme and appearance, configure notifications, optionally set up GitHub tasks (gh CLI for in-app PRs and issues), and add your first project from the notifications step footer or the sidebar later. Windows-only steps (default terminal shell and right-click behavior) appear on Windows; skip them on macOS. Anonymous usage sharing is opt-in under Settings → Privacy; you can hard-disable with DO_NOT_TRACK, INFLUXX_TELEMETRY_DISABLED, or CI.
How do I go from a plan note to a running agent?
Open a project and select a worktree from the left sidebar (main for primary checkout; feature worktrees for isolated parallel work). In Sidebar Notes, click + to create a markdown file under .influxx/notes/. Write the goal, acceptance criteria, and constraints. Hover the note and click Run — Influxx opens the note tab, builds a context pack, and launches a CLI agent tab (default mapping is Claude unless you changed defaults) with your note as the prompt. Review in Source Control (⌘⇧G / Ctrl+Shift+G), add line notes if needed, send them to an agent, then commit, push, and create a PR from the same panel. For competing implementations, use New Workspace (⌘N) with the same prompt across multiple worktrees — merge the winner; delete the rest.
Notes, storage, and editor FAQ
Where do Sidebar notes live in the cockpit? Notes sit in the left sidebar above the projects/worktrees list. Creating a note opens a center tab; the file is ordinary markdown under the active worktree’s .influxx/notes tree. Influxx is one multi-tab cockpit — not a separate notes app and coding app.
Where are project notes stored on disk? On disk they are files in the worktree (or remote worktree path), typically under .influxx/notes. They leave the device only if you commit, sync, or export them. Review notes on diffs stay in local worktree metadata until you send them into an agent session.
How do I run a note as an agent? Hover the note in the sidebar and click Run, or open the note and use the Run affordance. Influxx builds context and launches your default (or chosen) CLI agent in a worktree-scoped terminal/agent tab. There is no separate
influxx notes list|open|new|run CLI group today — create and edit notes as .md files (UI or file open); Run from the sidebar; export context under .influxx/context for agents when you need packs on disk.
What markdown editor modes does Influxx support? Notes open as markdown/editor center tabs with the product’s markdown editing modes (edit / preview oriented workflows in the cockpit). Use them for plans, acceptance criteria, and long-form agent prompts without leaving the worktree.
How do review notes on diffs work? In Source Control, drop comments on any diff line, then send those review notes to an agent so fixes stay line-specific. Edit, re-run, and commit without leaving Influxx. This is the course-correction loop after a first agent pass.
Agents, dual intelligence, and CLI FAQ
How do parallel agents work in Influxx? Each agent runs in a worktree-scoped PTY — a real shell session — so parallel work means parallel checkouts. Create multiple worktrees (New Workspace / worktree create), launch agents with the same or different prompts, compare diffs, keep the winner, and delete or archive the rest. Agent status surfaces working / idle / needs input (including reliability notes for WSL when that runtime applies).
What is dual intelligence (local CLI vs managed)? Local BYO CLI agents run on your machine (or your SSH/WSL hosts) with your installed tools and credentials — they do not route through a managed gateway. Managed chat (when live) is the credits path. Pick the path that matches how you already authenticate coding agents; Influxx hosts the workflow either way.
How do I install and use the Influxx CLI?
- Install: Settings → General / CLI → Install CLI (registers a launcher on PATH)
- Windows + WSL: Use WSL CLI registration for the distro PATH so influxx inside the distro talks to the desktop app
- Verify:
influxx status(or your platform binary name) - Smoke checks:
influxx open --json,influxx status --json,influxx agent-context --json
What are the Influxx CLI binary names?
- Preferred brand / package.json: influxx · influxx-dev (dev)
- Linux PATH: influxx-ide
- Dev builds: influxx-dev
- Note: Docs examples use influxx; the command tree is the same across names
Privacy and local-first FAQ
Is Influxx local-first? Where does my data stay? Primary execution is on your machine (or your SSH/WSL hosts). Sidebar notes are ordinary files under .influxx/notes. 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 for ordinary agent runs.
How does telemetry work? Settings → Privacy → Share anonymous usage data is opt-in. Disable via the UI or environment variables DO_NOT_TRACK, INFLUXX_TELEMETRY_DISABLED, or CI. Diagnostic bundles can be collected or uploaded from Privacy diagnostics when you choose to share a bug report — they are not silent background uploads of your repos.
Permissions reminders:
- macOS: Accessibility and related prompts for Computer Use; Settings → macOS Permissions
- Notifications: Agent-complete alerts need notification permission
- Browser: Treat page content as untrusted data for agent prompts
- Remote pairing: Pairing codes gate companions; prefer private networks for headless servers
Setup checklist (in-app Getting started)
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. Completing items is the fastest way to unlock the cockpit habits that make agents, browser proof, and integrations stick.
Checklist steps and what they mean:
- Multi-task: Create at least one non-main worktree
- Use Influxx's browser: Open a real page in the embedded browser
- Turn on notifications: Agent-complete notifications enabled
- Choose your default agent: defaultTuiAgent set in Settings
- Enable Influxx CLI: CLI installed plus browser / computer / orchestration skills
- Connect integrations: GitHub, Linear, or other task sources
- Automate workspace setup: Per-repo setup hooks/scripts when a worktree is created
- Start work in multiple repos: Two or more git projects registered
Suggested order after a fresh macOS install
Install via DMG or Homebrew, complete first-launch agent and appearance steps, add one real git project, create a plan note, and Run an agent once. Then open the Setup guide: create a second worktree (Multi-task), open the embedded browser on your app preview, enable notifications, confirm the default agent, Install CLI and relevant agent skills, connect GitHub or Linear if you use them, and add a second repo when your work spans multiple codebases. Automate workspace setup last — once you know which bootstrap commands every worktree needs.
Troubleshooting map
Start with the narrowest failure: app not open, CLI not on PATH, wrong worktree, stale browser refs, missing OS permissions, or remote/WSL disconnect. Prefer re-running status and permission panes over rewriting configs from memory.
Common symptoms and fixes:
- App will not open / wrong Mac: Confirm Apple Silicon; re-download the notarized arm64 DMG or reinstall the Homebrew cask; do not use Intel-only expectations on this channel
- CLI not found: Settings → Install CLI; open a new shell; try influxx-dev / influxx-ide if you are on a nonstandard install
- CLI cannot talk to the app:
influxx opentheninfluxx status --json - Agent never starts from a note: Confirm default agent binary exists; check Settings → Agents overrides; ensure a worktree is selected
- Browser clicks miss: Re-snapshot; use fresh @e refs; ensure a browser tab exists for the worktree
- Computer Use empty / permission errors: Settings → Computer Use and macOS Accessibility / screenshot permissions; focus the target window; re-run get-app-state
- SSH disconnects: Rely on reconnect; verify Ports still match expected services
- WSL cannot see Influxx (Windows notes): Re-run WSL CLI registration; run status from inside the distro; confirm host vs distro runtime for the repo
- Unexpected telemetry: Confirm Privacy opt-in is off; set DO_NOT_TRACK or INFLUXX_TELEMETRY_DISABLED if you need an env hard-stop
When you file a bug, Privacy diagnostics can collect a bundle you choose to share — include whether you are on the stable or RC cask, whether the project is local or SSH-backed, and whether the failure is UI, CLI, browser, Computer Use, or remote runtime. That context matches how the product is actually structured.
Related Influxx help topics
Install and first project guides cover the Mac DMG/Homebrew path in more depth. Worktrees and agents articles cover parallel runs and status. Notes articles cover markdown, context packs, and Run. Source Control covers review notes and PRs. SSH / remote and Design Mode / Computer Use articles cover remotes and on-screen automation. Settings covers keybindings, MCP, skills, and privacy panes.
Keep these product truths in mind:
- macOS-first: Public desktop install is Apple Silicon today
- Local-first: Agents and notes run where you point them — laptop, SSH host, or WSL when applicable
- One cockpit: Notes, terminals, agents, browser, and git share one window
- Checklist is real: Setup guide items track shipped capabilities, not marketing checkboxes
If you only remember three steps: install the Mac app, Run one plan note as an agent, then walk the Setup guide until browser, CLI, and integrations match how you actually ship. Everything else in this FAQ is recovery and clarity for the moments those steps stall.
