Influxx Quickstart: From Plan Note to Running Agent
This quickstart is the shortest path from a written plan to a running coding agent inside Influxx: select a worktree, create a sidebar plan note, press Run, watch the agent work, then review and ship from Source Control. It expands the in-product Quickstart tutorial—plan note → Run agent—without repeating the full install and first-launch walkthrough. If the app is already open on a project, you can complete this loop in one session.
Goal of This Guide
Goal: from an open project to “agent working from your plan” without treating Influxx like a separate notes app glued to a chat window. You will open or select a worktree, write goal and acceptance criteria in a sidebar note under .influxx/notes/, hover Run to launch a CLI agent with a context pack, steer with review notes on the diff, and commit, push, and create a PR from the same cockpit. Parallel worktrees are the optional power move when you want competing implementations of the same plan.
Install, DMG versus Homebrew, and first-launch onboarding live in Getting Started with Influxx and the macOS install article. This page assumes you can already see Projects in the left sidebar and that a default agent is set (onboarding or Settings → Coding agents / Agents). Anonymous usage sharing remains opt-in under Privacy; it is not required for this loop.
Write the plan as a note. Press Run. The agent receives the note as truth in an isolated worktree—then you annotate, commit, and ship without leaving the window.
1. Open a Project and Select a Worktree
Use the left sidebar Projects list. Click a project and select the workspace you want the agent to touch. The main worktree is your primary checkout; feature worktrees are isolated branches for parallel work. Sidebar Notes are bound to the selected worktree—if you see “Select a workspace,” pick one before creating or running a note. Errors toast if no worktree is selected or a startup plan cannot be built when you try to Run.
- Main worktree: Primary checkout for the repo.
- Feature worktrees: Isolated git checkouts so agents do not share a dirty tree.
- Keyboard: Focus worktree list with Mod+0; select workspace 1–9 with Mod+1…Mod+9; create worktree with Mod+N.
- Palette: ⌘J on macOS (Ctrl+Shift+J elsewhere) switches worktrees and opens related actions.
Why Worktree Selection Comes First
An agent in Influxx is a terminal CLI running in a worktree-scoped PTY. Notes, terminals, browser tabs, and .influxx/notes all key off that checkout. Running a plan against the wrong tree is the most common quickstart mistake—especially when you already have parallel experiments. Confirm the active worktree card before you write the plan or click Run.
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/ and opens it as a center editor tab—same chrome as code and agents. Write the goal, acceptance criteria, and constraints in plain markdown. Keep it specific: files to touch, behaviors to preserve, and what “done” means. Vague plans produce vague agent runs.
Sidebar create uses a fixed Untitled note starter body (“Write freely. Run an agent from the tab strip anytime.”). It does not open the template picker—use New Markdown (⌘⇧M / Ctrl+Shift+M) when you want templates from .influxx/templates/. Filename display titles come from the slugified name on disk; treat notes like normal project files for rename and delete via the explorer or filesystem. Decide whether your team commits .influxx/notes or gitignores the folder—plans will show in Source Control unless ignored.
- Storage: <worktree>/.influxx/notes/<slug>-<id>.md
- Open: Click the note title; it opens as a non-preview center tab.
- Edit modes: Source · Rich Editor · Preview on the markdown tab header; save with ⌘S / Ctrl+S.
- Best content: Goal, acceptance criteria, constraints, out-of-scope notes, and links to relevant paths.
3. Run the Note as an Agent
Hover the note in the sidebar and click Run. Influxx opens the note tab, reads the body, builds an Influxx context pack, and launches a CLI agent tab with your note as the prompt. Prompt shape is “Work from this note:” plus title and body, then appended context markdown. The tab quick-command label looks like Influxx · {note title} (truncated). Watch the agent in the terminal—or in chat view if you open agent tabs in chat by default under Settings.
What Run Actually Builds
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; the product layer also exports under .influxx/context/ for CLI workflows. Sidebar Run currently maps to the Claude TUI agent unless the binary is another known TUI agent or you configured Notes / default agent mapping. Pick other agents from New Workspace, a new agent tab, or the CLI when you need multi-CLI fleets.
- Hover action: Run on the sidebar note row (no dedicated global shortcut solely for Run note today).
- Default CLI: Follows your default / Notes mapping; override via Settings → Coding agents and Notes panes.
- Requirements: Workspace selected; agent binary available; sendable session once you later use review-note Send.
- Status: Working / idle / needs input via OSC hooks; desktop notifications when enabled.
The note is the contract. Run packages it; the agent executes it; review notes correct it on the diff—not in a second copy-pasted essay.
4. Review and Ship
When the agent has written code (or while it works), open Source Control with ⌘⇧G / Ctrl+Shift+G. Walk the diffs for the active worktree. Add line notes on the modified side where you want fixes—then Send notes to a sendable agent (All unsent notes or This file). Stage, commit (optional AI commit message), push, and create a PR or MR from the same panel. Watch Checks / PR Checks until green, merge on the git host, and delete the workspace when you are done.
- Review notes: Line comments in worktree metadata; structured File / Line / User comment prompts to the agent.
- Send blockers: not-ready, permission, or no-active-terminal statuses must clear before Send.
- Commit / push: Worktree-scoped staging—never assume a sibling agent’s dirty tree.
- Create PR / MR: First-class for GitHub and GitLab; provider-aware for other hosts.
- Cleanup: Delete Workspace with dirty/lineage preflight, or CLI worktree rm.
Parallel Path: Same Plan, Competing Worktrees
For competing implementations, use New Workspace (⌘N / Ctrl+N) with the same prompt—or the same plan text—across multiple worktrees. Each agent gets its own git worktree. Compare diffs in Source Control, keep the winner, delete the rest. You can also Run the same sidebar note idea by duplicating the plan into sibling trees, or launch a second CLI in one tree with a new terminal when you want two agents on one checkout (they will share that dirty tree—prefer separate worktrees for true isolation).
Optional: Start From a Task Instead of a Blank Note
If the work already lives in GitHub, Linear, or Jira, open the Tasks page and start a workspace from the item, then drop a sidebar note only when you need local acceptance criteria the ticket lacks. New Workspace can optionally link a GitHub, GitLab, or Linear task and enable smart naming. The Run-from-note path still applies whenever the plan is clearer as markdown than as a one-line composer prompt.
Do not confuse note types mid-loop. Sidebar notes are runnable plans. Review notes are diff annotations. Workspace comments are sticky one-liners on the card. Floating notes are scratch outside the repo and do not appear in the per-worktree Sidebar Notes list. Using the wrong surface is why “Run” sometimes seems missing—Floating and review notes are not sidebar Run targets.
Cockpit Moves That Speed the Loop
Toggle the left sidebar with ⌘B / Ctrl+B and the right sidebar with ⌘L / Ctrl+L so Notes and Source Control stay reachable. New agent tab shortcuts (for example ⌘⌥T on macOS) launch your default agent when you need a second session without a note. Quick Commands on the tab strip run saved shell recipes after the agent finishes scaffolding. Go to File (⌘P / Ctrl+P) jumps into paths the plan mentioned. Keep Explorer, Agents (AI Vault), and Checks on the right activity bar for history and CI without leaving the worktree.
- Show Source Control: ⌘⇧G / Ctrl+Shift+G
- Show Explorer: ⌘⇧E / Ctrl+Shift+E
- New markdown (templates): ⌘⇧M / Ctrl+Shift+M
- Settings: ⌘, / Ctrl+, — default agent, Notes Run mapping, notifications, privacy
- Notifications: Enable agent-complete alerts so you are not glued to the TUI
One-Session Checklist
Select the correct worktree. Create a sidebar note with goal, acceptance criteria, and constraints. Save. Hover Run and launch the agent. Watch status; respond when the agent needs input. Open Source Control; annotate and Send notes until the diff matches the plan. Stage only what belongs in the commit; push; Create PR/MR. Watch Checks. Merge on the host. Delete the workspace. If you needed parallel bets, spawn sibling workspaces before you fall in love with the first approach.
Quickstart is a habit, not a tour: plan on disk, Run into a PTY, correct on the diff, ship from Source Control, retire the worktree.
Troubleshooting the Plan → Agent Path
If Run is missing, confirm you are on a Sidebar note row in a selected worktree—not a floating note or a plain markdown tab alone. If the wrong agent launches, check Settings → Coding agents default and the Notes pane mapping for Run. If the agent cannot see files, confirm it is running in the intended worktree path. If Send notes is blocked, wait until a sendable agent terminal is ready. If diffs look empty, you may be viewing a sibling worktree—parallel agents never share one dirty tree. If plans appear unwanted in git, ignore .influxx/ or move scratch to Floating Workspace.
Related Influxx Help topics to explore by name: Getting Started with Influxx (install and first project); Notes (local markdown and context packs); Running Coding Agents (CLI catalog and parallel runs); Projects, Worktrees, and Isolated Workspaces; Source Control, Diffs, Pull Requests, and Checks; Git providers, Linear, and Jira; Local-first privacy and telemetry; Terminals, Tabs, and Quick Open. Use this quickstart when you already have a project open and need the plan-to-agent muscle memory.
What Success Looks Like
Success is not “the agent printed a lot.” Success is a worktree whose diffs match the acceptance criteria in the note, review notes cleared or sent, a pushed branch with a PR or MR you would defend in review, and a board status that reflects reality. The note remains on disk as the audit trail of intent—commit it with the team or keep it local by policy. Either way, the loop stays inside one cockpit: one left sidebar, one middle tab strip, one right activity bar.
When you outgrow the single-note path, layer orchestration skills, automations, task-started workspaces, and SSH hosts—but keep returning to the same verbs: write the plan, Run the note, annotate the diff, ship the branch. That is the Influxx quickstart from plan to agent.
