Getting Started with Influxx: Install, First Launch, and Your First Project
Getting Started with Influxx: Install, First Launch, and Your First Project — this guide takes you from a cold install on macOS Apple Silicon to a working project where a plan note launches a real CLI agent in an isolated workspace. Influxx is the ETAPX desktop cockpit that keeps your notes, terminals, and agents under one roof so the plan and the work stop drifting apart. You will learn how to install the app, walk through first-launch onboarding, add a project, write a plan as a sidebar note, run that note as an agent, review and ship from Source Control, and use the in-app setup checklist to finish onboarding. Everything here reflects shipped product surfaces only — what you see in the app and in official product notes.
What Influxx Is Built For
Your plan often lives in one place, your terminal in another, and your coding agents somewhere else entirely. By the time you copy context between them, the plan and the work have already diverged. Influxx puts those pieces together: write the plan as a note, press Run, and an agent picks it up in its own isolated workspace while you watch, steer, and review without leaving the window. You bring the command-line agents you already trust — with your keys, on your machine — and Influxx hosts them in real terminals scoped to the project worktree you choose.
Influxx desktop currently ships for macOS Apple Silicon only (bundle id ai.etapx.influxx). The product is built by ETAPX Inc. and is designed as a single multi-tab cockpit rather than a separate notes app glued to a separate coding app. One left sidebar, one middle tab strip, and a right activity bar give you notes, projects, terminals, agents, browser, markdown, source control, and more without context-switching into three different tools. This getting-started path focuses on install, first launch, your first project, a quickstart from plan to agent, and the setup checklist that tracks real progress after onboarding.
Write the plan as a note. Press Run. An agent picks it up in its own isolated workspace and gets to work — while you watch, steer, and review without ever leaving the window.
System Requirements and Platform Scope
Before you download anything, confirm you are on a Mac with Apple Silicon. Influxx desktop is distributed as a notarized DMG named influxx-macos-arm64.dmg and as Homebrew casks for stable and release-candidate channels. Install the desktop app first; the optional Influxx CLI can be registered later from Settings when you are ready for command-line workflows. If you only need the graphical cockpit for notes, agents, and source control, you can complete this entire guide without installing the CLI.
- Platform: macOS Apple Silicon (arm64) — desktop ships for this target today
- Bundle identity: ai.etapx.influxx
- Primary installer: notarized DMG (influxx-macos-arm64.dmg) from GitHub Releases
- Package manager: Homebrew cask influxx (stable) or influxx@rc (release candidates)
- Optional CLI: register from Settings after install; launcher binary lives as bin/influxx inside the app bundle
- Remote work: point the cockpit at a remote machine via SSH Hosts so agents can run where the code is heavy
Install Influxx on macOS
You have two supported paths for a production install: download the DMG from GitHub Releases, or install with Homebrew. Both put the Influxx app on your Mac so you can complete first-launch onboarding and open projects. Prefer the stable channel for day-to-day work; use the RC cask only when you intentionally want release-candidate builds.
How to Install from GitHub Releases
Open the official Influxx releases page and download the latest influxx-macos-arm64.dmg for Apple Silicon. Open the DMG, drag Influxx into Applications (or follow the installer layout shown in the disk image), then launch Influxx from Applications or Spotlight. The first launch starts the onboarding flow described later in this guide. Tagged release assets follow the shape influxx-macos-arm64.dmg under each versioned release so you can pin a known build if your team standardizes on a specific version.
How to Install with Homebrew
If you use Homebrew, install the stable cask with brew install --cask influxx. For release candidates, use brew install --cask influxx@rc. After the cask finishes, open Influxx from Applications or by launching the app name from your usual launcher. Homebrew is convenient for updates and for environments where DMG drag-install is discouraged; the app experience after install is the same as the DMG path.
The CLI is optional at this stage. After the app is installed, you can open Settings, find the General / CLI section, and run Install CLI to register a launcher on your PATH. Verify later with influxx status (or the platform binary name documented for your build). You do not need the CLI to write notes, add a project, or run an agent from the sidebar; enable it when you want terminal orchestration, worktree commands, or agent-context tooling from outside the GUI.
- Stable cask: brew install --cask influxx
- Release candidate: brew install --cask influxx@rc
- Direct DMG: latest public build from GitHub Releases (influxx-macos-arm64.dmg)
- CLI after install: Settings → General / CLI → Install CLI, then verify with influxx status
First Launch and Onboarding
On first open, Influxx walks you through the essentials so you are not dropped into an empty cockpit with no defaults. The goal of onboarding is to choose a default agent, make the UI feel familiar, set notifications, optionally connect GitHub task flows, and land on a path to add your first project. You can refine every choice later in Settings; onboarding is a guided first pass, not a one-way commitment.
First-Launch Steps: What You Will See
Work through the onboarding sequence in order. First, pick your default agent — any CLI agent Influxx knows, including Claude Code, Codex, Grok, Cursor Agent, OpenCode, and many more catalog entries, plus shell binaries you configure. Next, make it feel like home with theme and appearance. On Windows-oriented builds the flow can include default terminal shell and right-click behavior; on the current macOS Apple Silicon desktop you still complete theme, notifications, and agent defaults. Then set up notifications so you know when an agent finishes or needs attention. Optionally set up GitHub tasks by installing the GitHub CLI for in-app pull requests and issues. Finally, add your first project from the notifications step footer, or skip and add it from the sidebar later.
- Default agent: the CLI Influxx launches by default for new agent tabs and sidebar Run (you can change this anytime in Settings → Agents)
- Theme and appearance: make the cockpit readable for long sessions
- Notifications: agent-complete and attention prompts so work does not finish silently
- GitHub tasks (optional): GitHub CLI for in-app PRs and issues when you use task-driven workspaces
- First project: open from the onboarding footer or from Add project in the left sidebar
- Privacy: anonymous usage sharing is opt-in under Settings → Privacy; you can hard-disable telemetry with DO_NOT_TRACK, INFLUXX_TELEMETRY_DISABLED, or CI as documented in product notes
Privacy during first launch matters for teams that treat telemetry as a policy decision. Influxx does not force usage sharing; the privacy surface is opt-in, and environment-level disables exist for automated or restricted environments. Complete onboarding with the defaults you need for productive local work, then open Settings → Privacy if you want to review or change sharing. Settings themselves open with ⌘, on macOS (Ctrl+, on other platforms where applicable).
The Cockpit Layout You Land In
After onboarding, Influxx presents one multi-tab cockpit. The left sidebar holds Notes, projects and worktrees, setup prompts, Add project, and the Setup guide entry. The center is a tab strip for terminals, agents, browser, markdown and editor surfaces, emulator, and PR or issue views. The right activity bar exposes Explorer, Agents (AI Vault), Source Control, Checks, Ports for SSH, and attached worktrees. The status bar shows usage meters, connection pills, and integration status. Toggle the left sidebar with ⌘B and the right sidebar with ⌘L; these shortcuts keep the layout flexible without leaving keyboard flow.
- Left sidebar: Notes, projects/worktrees, setup prompts, add project, setup guide
- Center tab strip: terminals, agents, browser, markdown/editor, emulator, PR/issue surfaces
- Right activity bar: Explorer, Agents (AI Vault), Source Control, Checks, Ports (SSH), Attached worktrees
- Status bar: usage meters, connection pills, integration status
- Settings: ⌘, — agents, CLI, privacy, floating workspace, notifications, and more
Add a Project: Your First Workspace
Projects in Influxx are git repositories or folder workspaces the app tracks. From the left sidebar, click Add project (or open the project dialog). You can open an existing folder, clone a remote URL, import nested multi-repos, or connect an SSH remote host path. Non-git folders can still become folder workspaces with attached worktrees. After import, pick or create a worktree (workspace) so you have a place to code, write notes, and launch agents. The main worktree is your primary checkout; feature worktrees are isolated branches for parallel work.
Remote machines expand the same model. Use SSH Hosts so agents run on a more powerful box while you keep the Influxx cockpit on your Mac — with full file editing, git, terminals, reconnect, and port forwards. Remote and local worktrees share the same relative product paths for notes and context (for example .influxx/notes under the worktree); filesystem operations for remote worktrees go through the remote connection. For a first project on a single Mac, start with an existing local folder or a simple clone, then explore SSH Hosts when you need remote compute.
- Open existing folder: point Influxx at a repo or workspace you already have on disk
- Clone remote URL: bring a remote git repository into a local path and track it as a project
- Import nested multi-repos: register related repositories when your work spans more than one git root
- SSH remote host path: connect a path on a configured SSH host so agents and edits run remotely
- Non-git folders: still usable as folder workspaces with attached worktrees
- After import: select or create a worktree before expecting notes Run or agent launches to succeed
You must have a workspace selected before Run or agent startup. Influxx needs a worktree so the agent has an isolated place to work and so plan notes resolve to a real project path.
Quickstart Tutorial: From Cold Install to Agent Working From Your Plan
The following sequence is the shortest path from an empty install to “agent working from your plan” in one session. It assumes Influxx is installed, onboarding is complete or skipped to the main window, and you have at least one project with a selected worktree. If any step fails, check that a workspace is selected in the left rail and that your default agent binary is installed and available on the machine (or remote host) where the agent will run.
Step 1 — Open a Project and Select a Worktree
Use the left sidebar Projects list. Click the project you added, then select the main worktree or a feature worktree. The main worktree is your primary checkout; feature worktrees are isolated branches for parallel experiments. Keyboard paths that help later: create a worktree with ⌘N (also ⌘⇧N), switch worktree or open the palette with ⌘J, and open Source Control with ⌘⇧G when you are ready to review. Until a worktree is active, sidebar notes will prompt you to select a workspace — notes open as tabs next to your agents once a workspace is selected.
Step 2 — Create a Plan Note
In the left sidebar, find the Notes section above the worktree list. Click + (or + First note when the list is empty). Influxx creates a real markdown file under .influxx/notes/ in the active worktree and opens it as a center editor tab. Write the goal, acceptance criteria, and constraints in plain markdown. The default body starts as an Untitled note with a short prompt to write freely and run an agent from the tab strip anytime — replace that with your actual plan. Sidebar notes are the canonical surface for “plan bound to a workspace, then Run → agent.”
Notes in Influxx are not a single generic blob. Sidebar notes live as .md files under the worktree’s .influxx/notes folder and are ideal for plans you will run. Markdown tabs can open any .md path for long-form docs and templates. Review notes attach to diffs in Source Control so you can send line-level feedback to an agent. Workspace comments are sticky one-liners on a worktree card. Floating notes live in an app-owned floating workspace directory for scratch work outside a repo. For this quickstart, stay on Sidebar Notes so Run is one hover away.
- Sidebar notes: left rail → Notes; stored as .influxx/notes/*.md; best for plans that Run as agents
- Markdown tabs: center tabs for any .md path; templates available via New Markdown
- Review notes: line comments on diffs to send back to an agent (not separate git commits)
- Workspace comment: short sticky label on a worktree card
- Floating notes: scratch outside a repo in the floating workspace panel
Step 3 — Run the Note as an Agent
Hover the note in the sidebar and click Run. Influxx opens the note tab, builds a context pack from the note and workspace, and launches a CLI agent tab with your note as the prompt. The default mapping for sidebar Run is the Claude TUI agent unless the binary is another known TUI agent; pick other agents from New Workspace, a new agent tab, or the CLI when you want a multi-CLI fleet. Watch the agent work in the terminal, or open agent tabs in chat-by-default from Settings if you prefer chat chrome over a raw TUI. The agent tab is a real shell session scoped to the selected worktree — not a simulated chat detached from your files.
An agent in Influxx is a terminal CLI running in a worktree-scoped session. The cockpit tracks status, usage, notifications, and history; it does not replace your CLI’s own tools or keys. Supported first-class catalog entries include Claude Code, Claude Agent Teams, Codex, Grok, Cursor Agent, GitHub Copilot, OpenCode, Gemini, and many more, plus any shell binary you configure. Set the default in onboarding or Settings → Agents, and override launch commands per agent when needed. You can also launch agents from the New Workspace composer, the tab strip (new terminal / new agent / Quick Commands), task sources such as GitHub, Linear, or Jira, the CLI, or automations — sidebar Run is simply the shortest path from a written plan.
Step 4 — Review and Ship
Open Source Control with ⌘⇧G (Ctrl+Shift+G on platforms where that binding applies). Read the diff, add line notes on the lines that matter if you want the agent to fix specifics, then send those notes to an agent. Commit, push, and create a pull request from the same panel so review and ship stay in the cockpit. This closes the loop: plan note → agent run → diff review → optional agent follow-up → commit and PR without copying context into another app.
Parallel Path: Competing Implementations
When you want multiple approaches to the same problem, create New Workspace (⌘N) with the same prompt across multiple worktrees. Each agent gets its own git worktree and terminal. Compare the results, keep the winner, and delete the rest. Isolation is the worktree — that is how Influxx runs a fleet rather than a single queue. Workspace board statuses such as Todo, In progress, In review, and Done help you track parallel streams; a second agent on the same checkout can also be a new terminal with a different CLI command when you do not need a full extra worktree.
- New Workspace: ⌘N — pick project, agent, prompt, and base branch; create worktree and launch
- Same prompt, many worktrees: compare diffs; merge the winner; remove the rest
- Second agent, same checkout: new terminal with a different CLI when full isolation is not required
- Board statuses: Todo · In progress · In review · Done for multi-stream work
Setup Checklist: Track Real Onboarding Progress
After onboarding, the in-app Getting started / Setup guide tracks real progress against product actions — not a decorative checklist. Open it anytime from the sidebar Setup guide entry or from Settings → Onboarding checklist. Completing items teaches the major surfaces of the cockpit and confirms that agents, notifications, CLI, integrations, and multi-repo workflows are actually wired for your machine.
- Multi-task: create at least one non-main worktree so parallel work is unlocked
- Use Influxx's browser: open a real page in the embedded browser
- Turn on notifications: enable agent-complete notifications
- Choose your default agent: set defaultTuiAgent in Settings so Run and new agent tabs launch the CLI you intend
- Enable Influxx CLI: install the CLI and the browser, computer, and orchestration skills surfaces that complete the checklist item
- Connect integrations: GitHub, Linear, or other task sources for issue-driven workspaces
- Automate workspace setup: per-repo setup hooks or scripts so new worktrees bootstrap consistently
- Start work in multiple repos: register two or more git projects when your day spans more than one repository
Treat the checklist as a guided tour of capabilities you will use weekly. Multi-task and multi-repo items matter as soon as you outgrow a single checkout. Notifications matter the first time an agent finishes while you are in another tab. The CLI and skills path matter when you script worktree creation, terminals, or orchestration outside the GUI. Integrations matter when “start workspace from an issue” is how your team begins work. Automate workspace setup when every new worktree needs the same install or environment steps.
Optional: Install the Influxx CLI After the GUI Works
When you are ready, open Settings → General / CLI and run Install CLI to register a launcher on PATH. Verify with influxx status. Common commands for later workflows include influxx open, influxx status, and influxx agent-context (often with --json for scripting). Worktree and terminal subcommands let you list, create, and manage worktrees and agent shells from the command line with the same product model as the UI. Examples in product docs use the influxx command name for branded installs; stick to the binary name your install registered.
Notes and Markdown Essentials for Day One
Sidebar create always makes a real .md file immediately. Display titles are derived from the filename; treat notes like normal project files for rename in the filesystem or explorer. Edit modes on a markdown tab include Source, Rich Editor, and Preview — save with ⌘S, with autosave available based on editor settings. New Markdown from the tab bar (⌘⇧M) can open a template picker: Blank Markdown or templates from .influxx/templates under the worktree. Sidebar + does not open the template picker; it uses the fixed Untitled note body so plan capture stays fast.
Because sidebar notes are real files inside the worktree, they appear in git unless you ignore .influxx/ in the repository. Many teams commit shared plans so the whole team sees the same acceptance criteria; others gitignore the folder for personal scratch plans. Choose intentionally on day one so you do not surprise teammates with unplanned commits. Context packs generated when you Run also export under .influxx/context for CLI workflows, keeping the same “plan as source of truth” model in and out of the GUI.
- Create from sidebar: immediate .md under .influxx/notes; open as center tab
- Create from tabs: New Markdown or Open Markdown; templates when using New Markdown
- Edit modes: Source · Rich Editor · Preview
- Save: ⌘S / Ctrl+S; autosave follows editor settings
- Git policy: decide whether .influxx/ notes are shared or ignored
- Run requirement: workspace selected; toast errors if no worktree or startup plan cannot be built
Everyday Keyboard Paths After Install
Once the first project is open, a small set of shortcuts covers most of the cockpit. Toggle sidebars with ⌘B and ⌘L. Open Settings with ⌘,. New terminal tab with ⌘T; new agent tab with the default agent via ⌘⌥T on macOS; new browser tab with ⌘⇧B; new markdown with ⌘⇧M. Go to File with ⌘P; worktree switch and palette with ⌘J; create worktree with ⌘N; Explorer with ⌘⇧E; Source Control with ⌘⇧G. From the tab strip +, open Quick Commands for additional launchers. These bindings keep install-day exploration fast without memorizing every menu.
- Toggle left sidebar: ⌘B
- Toggle right sidebar: ⌘L
- Settings: ⌘,
- New terminal: ⌘T
- New agent (default): ⌘⌥T (macOS)
- New browser: ⌘⇧B
- New markdown: ⌘⇧M
- Go to File: ⌘P
- Worktree / palette: ⌘J
- Create worktree: ⌘N
- Source Control: ⌘⇧G
Troubleshooting First-Day Friction
If Run does nothing useful, confirm a worktree is selected and that the note belongs to that workspace’s sidebar list. If the agent tab fails to start, confirm the default agent CLI is installed and on PATH for the machine where the session runs (local Mac or SSH host). If notifications never appear, re-enable agent-complete notifications from the setup checklist or Settings. If the project list is empty, use Add project and complete import before expecting Notes or Source Control to attach to a repo. If you expected templates on sidebar create, use New Markdown from the tab strip instead — sidebar + is intentionally the fast Untitled path. If git is noisy with note files, revisit whether .influxx/ should be ignored or committed as team plans.
Floating Workspace is available under Settings when you need terminals or markdown that are not tied to a repo worktree. Floating markdown is stored in Influxx’s app-owned floating-workspace directory, not in your home folder as loose files, and floating notes do not appear in the per-worktree Sidebar Notes list. For the getting-started path in this guide, prefer project-bound sidebar notes so Run, context packs, and source control stay aligned with a real worktree.
What “Done” Looks Like for Getting Started
You are finished with first-day setup when Influxx is installed on macOS Apple Silicon, first-launch defaults are set (agent, appearance, notifications), at least one project and worktree are active, a plan note exists under Sidebar Notes, you have successfully used Run to launch an agent from that note, and you know how to open Source Control to review diffs and optionally send review notes back. Bonus completion: one non-main worktree for multi-task, CLI installed if you want terminal orchestration, and the Setup guide items that match how you actually work.
- Installed: DMG or Homebrew cask on Apple Silicon
- Onboarded: default agent, theme, notifications; privacy reviewed if required by policy
- Project ready: folder, clone, multi-repo, or SSH path imported; worktree selected
- Plan written: sidebar note with goal, acceptance criteria, constraints
- Agent launched: Run from the note; session visible in the center tab strip
- Review path known: Source Control open; line notes and commit/PR flow understood
- Checklist in progress: Setup guide opened from sidebar or Settings → Onboarding checklist
Influxx is one cockpit for the plan and the work: notes that run as agents, isolated workspaces for parallel approaches, and review that ships from the same window — on your machine, with the CLIs you already trust.
Related Influxx help topics to explore next include deeper notes and markdown workflows, agent fleets and supported CLIs, worktrees and parallel agents, Source Control review notes, SSH Hosts and remote projects, task sources (GitHub, Linear, Jira), automations, and CLI install and command reference. Stay inside the Influxx category of the ETAPX help center for product-facing guides that match shipped surfaces. Download channels and release assets are published on the official Influxx GitHub Releases page and via the Homebrew casks described above; keep the app updated so onboarding checklist items and agent catalog entries stay current with your installed version.
Quick Recap: Install → Launch → Project → Plan → Run → Review
Install Influxx for macOS Apple Silicon from GitHub Releases or Homebrew. Complete first launch by choosing a default agent, appearance, and notifications, with optional GitHub task setup. Add a project from the sidebar — existing folder, clone, multi-repo, or SSH path — and select a worktree. Create a Sidebar note with a clear plan. Hover and Run to launch a CLI agent in that workspace. Open Source Control to review, send line notes, commit, and open a pull request. Return to the Setup guide until multi-task, browser, notifications, default agent, CLI, integrations, workspace automation, and multi-repo items match how you build. That is getting started with Influxx end to end.
