Influxx Notes: Local Markdown, Sidebars, and Agent Context
Influxx Notes is the local-first writing surface inside the Influxx desktop cockpit—not a separate notes app and not a cloud notebook. Plans, docs, and scratch live as real markdown on your machine (or on a connected remote worktree). This guide covers every notes surface from the left sidebar through floating workspace files, how markdown tabs open next to code and agents, where files land on disk, how wiki links and templates work, and how Run turns a note into an agent context pack your CLI can use.
One left sidebar. One middle tab strip. Notes open like code and agents—local markdown on disk, readable by you and by any CLI agent working in that worktree.
What “local-first” means in Influxx Notes
Core Notes are worktree-local. Sidebar project notes are ordinary files under .influxx/notes/ inside the selected workspace. Context packs written for agents land under .influxx/context/. Templates live under .influxx/templates/. Nothing in this model requires uploading notes to an Influxx cloud, multiplayer collab service, or third-party notes host. You choose whether those files enter git with the rest of the repo, stay ignored, or stay outside any project entirely in the floating workspace. Agents that run in a worktree read the same paths you edit—so the plan you wrote is the plan the agent sees.
This guide stays on shipped product behavior: sidebar notes, markdown tabs, storage layout, Run as agent, the markdown editor (Source, Rich Editor, Preview), templates, wiki links, PDF export, and floating notes. Related surfaces such as review notes on diffs and sticky workspace comments appear only where they help you pick the right tool; deeper agent and source-control loops are covered in their own Influxx help topics.
Notes overview: several surfaces, different storage
Marketing copy may say “notes” for more than one UI. In the product they store data differently—use the right surface for the job.
- Sidebar notes: Left rail → Notes. Stored as .influxx/notes/*.md in the worktree. Best for plans bound to a workspace and for Run → agent.
- Markdown tabs: Center tabs for any .md path (worktree or floating). Best for long-form docs, templates, and wiki links.
- Review notes: Diffs and Source Control. Stored as worktree metadata (not git commits and not .md files). Best for line comments you send to an agent.
- Workspace comment: Worktree card meta via the worktree.comment field. Best for a sticky one-liner on a card.
- Floating notes: Floating panel under app userData floating-workspace. Best for scratch outside a repo.
Canonical product path: primary Notes UX is Sidebar Notes that open as middle editor tabs—the same chrome as code and agent terminals. Do not expect a second full-screen notes shell as the main experience. You stay in one multi-tab cockpit so a plan, a diff, and a running agent can sit side by side without switching apps.
Sidebar notes: plans next to your worktrees
The Notes block sits above the worktree and project list in the main left sidebar. Its job is simple and deliberate: list project-bound markdown, open it as a center tab, and offer Run so you can hand that plan to a CLI agent without leaving the cockpit.
- Header: The section is labeled Notes.
- No workspace selected: You see guidance that you must select a workspace—notes open as tabs next to your agents.
- Empty list: Use + First note to create the first file.
- + control: Tooltip reads New note (opens in center).
- Each row: Note title plus a hover action labeled Run.
Open or create a sidebar note
Select a workspace or worktree first. Click + to create a new note, or click a title to open an existing one. The note opens as a non-preview editor tab in the center strip—same tab bar as your code files and agent sessions. You can keep several notes open while an agent runs and while Source Control stays a click away.
The sidebar list supports create, open, and Run. There is no separate Notes-only menu for rename, delete, pin, or search. Treat note files like normal project files: rename or remove them through the filesystem or project explorer, and understand that the display title is derived from the filename (dashes and underscores become spaces). Keeping file operations honest avoids a parallel notes database that agents would not see.
Create and edit markdown
Create from the sidebar when you want a plan file under .influxx/notes/ immediately. Create from the tab bar when you want any markdown path, a template, or a floating file.
Create from the sidebar
Sidebar create writes a real .md file right away. The default body is a short starter heading and prompt so you can type goals and constraints without ceremony:
# Untitled note
Write freely. Run an agent from the tab strip anytime.
That fixed starter is intentional: Sidebar Notes always use this Untitled note body. They do not open the template picker. When you want templates, use New Markdown from the tabs instead.
Create from tabs (any markdown)
From the tab bar, use + → New Markdown or Open Markdown…. Keyboard shortcuts: ⌘⇧M / Ctrl+Shift+M for new markdown, and ⌘⇧O / Ctrl+Shift+O to open. New Markdown opens a template picker: Blank Markdown or templates discovered on disk under the worktree. Untitled files are real on-disk files; a blank, untouched untitled may be removed when you close the tab so empty stubs do not pile up.
- Source: Raw markdown editing for full control of fences, front matter, and hand-tuned markup.
- Rich Editor: Structured editing that round-trips back to markdown on disk—the same file agents and git see.
- Preview: Read-only render with table of contents, Mermaid diagrams, local images, and anchors.
- Save: ⌘S / Ctrl+S; autosave also applies based on your editor settings.
Switch Source · Rich Editor · Preview from the markdown tab header. Prefer Rich Editor for day-to-day writing, Preview when reviewing or exporting a clean layout, and Source when you need exact markdown or when a very large or unsupported document is forced into Source mode for safety.
Storage on disk: the agent-readable contract
Influxx does not hide note bodies in an opaque app-only database for the primary plan path. Canonical bodies are markdown files under the worktree so humans, git, and CLI agents share one source of truth.
- Sidebar project notes: <worktree>/.influxx/notes/<slug>-<id>.md
- CLI context packs: <worktree>/.influxx/context/<session>.md
- Markdown templates: <worktree>/.influxx/templates/**/* with .md, .mdx, or .markdown extensions
- Floating markdown: Under the app’s userData floating-workspace directory (not inside a repo checkout)
- Review notes: Worktree metadata in app data—not .md files and not git commits
Filename rule for sidebar notes: the title is slugified (maximum 48 characters) and combined with a base36 timestamp, for example untitled-note-m1abc2.md. The display title in the sidebar is derived from that filename, turning dashes and underscores into spaces. If you rename a file on disk to a clearer slug, the list title follows.
Git and remote worktrees
Sidebar notes are real files inside the worktree. They will appear in git status unless you ignore .influxx/ in the repository. Many teams commit shared plans so every clone and every agent session sees the same goals and acceptance criteria. Others gitignore the folder for private scratch. Pick intentionally—there is no silent cloud layer that keeps notes “out of git for you.”
SSH and remote worktrees use the same relative paths under .influxx/. File operations go through the remote connection, so the contract stays path-stable whether the worktree is local or on a host you opened through SSH Hosts.
Run as agent: from plan to CLI session
When a note is ready to execute, you do not copy-paste into a separate terminal product. Hover a note in Sidebar Notes and click Run. Influxx opens the note, reads the body, builds an Influxx context pack, and launches a CLI agent tab in the selected workspace.
- Prompt shape: Work from this note: plus the note title and body, then appended context markdown.
- Tab label: Quick-command style label Influxx · {note title}, truncated as needed.
- Context pack header: Markdown that starts with # Influxx context pack and includes session id, runtime (local-cli), worktree id, and linked note sections.
- Delivery: Context is delivered in the agent prompt; the product layer also exports under .influxx/context/ for CLI workflows that read files on disk.
- Default CLI: Sidebar Run maps to the Claude TUI agent unless the binary is another known TUI agent. Pick other agents from New Workspace, a new agent tab, or the Influxx CLI when you run multi-CLI fleets.
You must have a workspace selected before Run. If no worktree is active or a startup plan cannot be built, Influxx shows an error toast instead of launching a half-configured session. That guardrail keeps context packs bound to a real checkout where .influxx/ paths resolve.
What the context pack is for
A context pack is the on-disk bridge between your written plan and a local CLI agent. It is not a remote “memory” service. When you Run a note, Influxx assembles session metadata and linked note material so the agent starts with a clear brief. Export under .influxx/context/ means you can also open the pack in a tab, commit it if your team wants audit trails, or let CLI tooling read the same markdown offline. Related project-state and folders material can participate in the broader agent on-disk contract under .influxx/; the important product truth is that agents are expected to use worktree-local files rather than inventing a parallel notes layout.
Quickstart loop: note → agent → review
From a cold open: select a project and worktree, create a plan note in Sidebar Notes (+ or + First note), write goal, acceptance criteria, and constraints in plain markdown, then hover Run. Watch the agent in the terminal (or chat view if you open agent tabs in chat by default). After the agent works, open Source Control (⌘⇧G / Ctrl+Shift+G), optionally add line-level review notes on the diff, and send those notes back into an agent when you need targeted fixes. Parallel path: New Workspace (⌘N) with the same prompt across multiple worktrees so competing implementations stay isolated.
Markdown editor capabilities
The editor is built for real project documentation—not a toy notepad. Mode switch and features stay local to the file you opened.
- GFM basics: Headings, lists, task lists, blockquotes, code fences, links, and tables.
- Diagrams and math: Mermaid diagrams plus inline and block math.
- Images: Local images resolved through the app so previews work without uploading assets to a notes cloud.
- Structure: Collapsible details and toggle headings for long plans.
- Slash menu: Insert headings, blocks, tables, Mermaid, math, media, and emoji without leaving the keyboard flow.
- Wiki links: Obsidian-style [[wiki links]] with completions, including [[note#Heading]] for in-document targets.
- Editor ergonomics: Paste image, list continuation, and front matter show/hide.
- Markdown preview toggle: ⌘⇧V / Ctrl+Shift+V
- Find in editor: ⌘F / Ctrl+F
- Save: ⌘S / Ctrl+S
Very large or unsupported documents force Source mode for safety so you never lose control of the raw file. PDF export needs a rendered Rich Editor or Preview DOM; pure Source fallback cannot export a layout it has not rendered. If Export as PDF is unavailable, switch to Rich Editor or Preview first, then try again.
Templates under .influxx/templates/
When you use New Markdown (not Sidebar +), Influxx offers Blank Markdown plus any templates found under the worktree path .influxx/templates/. Supported extensions are .md, .mdx, and .markdown. Discovery walks up to depth 8, caps at 100 files, and skips .git, node_modules, and symlinks so template scans stay fast and predictable.
- {{title}}: Inserted title placeholder when the template is applied.
- {{filename}}: File name for the new document.
- {{date}}: Date stamp for logs and daily notes.
- {{time}}: Time stamp for time-boxed plans.
- {{datetime}}: Combined date and time when you want a single token.
Keep team templates in the repo under .influxx/templates/ so every worktree clone shares the same plan skeletons—RFCs, bug write-ups, migration checklists, and agent brief formats. Because templates are plain files, you review them in pull requests like any other project asset. Sidebar Notes still skip the picker; open New Markdown when you want a template-backed document, then move or save under .influxx/notes/ if you want it listed as a project plan.
Wiki links: the in-repo doc graph
In the rich markdown editor, type [[ to complete document links. Resolve headings with [[doc#Heading]]. This is the in-repo documentation graph for human navigation inside your worktree—not the same system as agent @-mentions in experimental product overlays. Wiki links help you build a local knowledge web across notes and markdown tabs without depending on an online wiki host.
Practical pattern: keep a short index note under .influxx/notes/ that wiki-links to design notes, ADRs, and runbooks elsewhere in the tree. When you Run a high-level plan, the body can still spell out acceptance criteria in plain text so the agent does not have to chase every link; use wiki links for human orientation and long-form architecture reading.
Export PDF and portable markdown
Open a markdown file in Rich Editor or Preview. Open More actions on the editor header. Choose Export as PDF. That path captures the rendered document. For portable handoff without PDF, remember plain markdown is already on disk—copy the .md file, commit it, or attach it outside Influxx. There is no bulk “import notes folder” wizard; drop .md files into .influxx/notes or open them via Open Markdown when you bring plans in from elsewhere.
Floating notes: scratch outside a repo
Use Floating Workspace when the note is not about a specific repo checkout—meeting scratch, personal checklists, and cross-project ideas. Enable or confirm Floating Workspace under Settings if needed, open the floating panel, then choose New Markdown Note or Open Markdown Note. Files live under the app userData floating-workspace area, not under a project’s .influxx/notes/, so they stay out of that repo’s git status by design.
Floating notes still use the same markdown editor modes and tab-friendly editing model; what changes is ownership and path. Promote important floating ideas into a worktree by saving or copying content into .influxx/notes/ when you are ready for Run-as-agent and team-visible plans. Keep ephemeral lists floating so project directories stay clean.
Choosing the right notes surface
If the writing is a plan the agent should execute in this checkout, use Sidebar Notes under .influxx/notes/ and Run. If the writing is long-form documentation, templates, or a wiki-linked architecture page, use markdown tabs on any path that belongs in the repo. If you are commenting on a diff for the agent to fix, use review notes in Source Control—not a freeform plan file. If you need a one-line reminder on a worktree card, use the workspace comment field. If the writing is not about this repo at all, use floating notes.
- Bound plan + Run: Sidebar Notes → .influxx/notes/*.md
- Long-form / templates / wiki: Markdown tabs on worktree paths
- Line feedback on diffs: Review notes (worktree metadata)
- Sticky card label: Workspace comment on the worktree
- Out-of-repo scratch: Floating Workspace markdown
Writing plans agents can execute
Strong notes for Run are specific: state the goal, list acceptance criteria as checkboxes or numbered outcomes, call out constraints (libraries, branches, files to avoid), and name definition of done. Because the prompt shape is “Work from this note” plus body plus context pack, fluff and unresolved TODOs become agent noise. Prefer one focused note per workstream rather than a single ever-growing dump. Split large initiatives into linked notes with wiki links for humans and short, self-contained Run notes for agents.
Context packs include session and worktree identifiers so the agent session is tied to the workspace you selected. They are not a substitute for keeping the note body accurate—if the plan is wrong, the pack faithfully carries that wrong plan into the CLI. Update the markdown, save, and Run again when the brief changes. Editing a note after send does not invent cloud revision history; you are simply changing local files.
Privacy, ownership, and intentional sharing
Local-first means you decide visibility. Files under a worktree can be private to your machine, shared via git with teammates, or mirrored only when you push. Floating notes stay in app userData unless you move them. Review notes stay in worktree metadata for the agent loop and are not GitHub pull request review comments unless you also use host review separately. Anonymous product telemetry is a separate Settings → Privacy choice and is not note sync. Do not confuse optional usage sharing with cloud note storage—Notes core does not require either.
On remote SSH worktrees, the same relative .influxx/ layout applies on the remote machine. Agents running on a beefy host still read plans next to the code. Your cockpit remains the single UI; the files remain first-class citizens of that checkout.
Cockpit UX law that Notes must not break
Influxx is one multi-tab cockpit—not a notes app glued to a coding app. UX law: one left sidebar, one middle tab strip. Notes open as tabs like code and agents. Prefer bring-your-own CLI agents that work against worktree-local .influxx/ files. Do not invent a parallel notes layout in your head or in automation scripts; list and edit the real markdown under the paths above so UI, git, and agents stay aligned.
Practical checklist for teams adopting Influxx Notes
Decide whether .influxx/ is committed, ignored, or mixed (for example commit templates and shared plans, ignore personal scratch). Seed .influxx/templates/ with a small set of plan formats. Standardize sidebar note titles so Run labels stay scannable. Teach the team that Run builds a context pack under .influxx/context/ and launches a CLI tab—not a separate web agent. Use floating notes for meetings that are not yet project-shaped. Use review notes on diffs for fix-it feedback after the first agent pass. Keep wiki links for human navigation; keep Run notes self-contained for agents.
- Commit strategy: Document whether .influxx/notes and .influxx/context are tracked.
- Templates: Store shared skeletons under .influxx/templates/.
- Run hygiene: One clear plan per Run; update the file before re-running.
- Surface pick: Sidebar vs floating vs review notes vs workspace comment.
- Editor mode: Rich for writing, Preview/PDF for sharing, Source for exact control.
- Import: Drop .md into .influxx/notes or Open Markdown—no bulk wizard.
Your plans are files. Your context packs are files. Your templates are files. Influxx Notes keeps that honesty so agents, git, and people never argue about which copy was real.
Related Influxx topics include adding projects and worktrees, launching agents from New Workspace or the tab strip, Source Control review notes, and Floating Workspace settings. For Notes specifically, remember the boundaries of this guide: local markdown, sidebars, tabs, templates, wiki links, PDF export, floating scratch, and agent context packs—without inventing cloud sync. When in doubt, open the file path under .influxx/ and trust what is on disk.
Summary
Influxx Notes puts project plans in the left sidebar, opens them as center tabs, stores them as markdown under .influxx/notes/, and turns them into local CLI sessions through Run and .influxx/context/ packs. Markdown tabs, templates, wiki links, and Preview/PDF cover long-form docs. Floating notes keep out-of-repo scratch in userData. Everything in the core loop is local-first: real paths, intentional git, no required notes cloud.
