# Why Nimbalyst? Nimbalyst is an open-source visual workspace for Claude Code and Codex. Learn what it does, who it is for, and how to start working with AI agents. [Nimbalyst](https://nimbalyst.com/) is **the open-source visual workspace for building with Codex, Claude Code, and more**. Get higher bandwidth with less context switching. Manage your agents, edit the work visually, and track tasks. Work across markdown, Calc Sheets, mockups, diagrams, diffs, code, and more without leaving the workflow or rebuilding context. Nimbalyst runs on your Mac or Windows machine on top of the coding agents you already have installed. [Download Nimbalyst](https://nimbalyst.com/download/) and open a project folder to get started. Nimbalyst stores your files and data locally in an open format. The full source is on GitHub at [github.com/nimbalyst](https://github.com/nimbalyst), where you can read the code, file issues, or contribute. ### One integrated, higher-bandwidth workflow Building with agents is a whole workflow. It moves through plans, source files, mockups, diagrams, data, tasks, sessions, reviews, commits, and pull requests. Nimbalyst keeps that work together so people and agents can move through it as one connected process. * **Integrated workflow:** Plan the work, run agents, edit the result, track status, review changes, and connect the commit without rebuilding context in another tool. * **Integrated file types:** Work in purpose-built visual editors for markdown, code, mockups, diagrams, spreadsheets, data models, and more while the same agents stay in context. * **Less context switching:** Stop bouncing among a terminal, editor, document app, diagram tool, and task tracker or copying the same context into each one. * **Higher bandwidth:** Visual interfaces expose more of the work at once, so people understand, direct, and review agent output faster than they can through a text-only workflow. ### Files Mode Work with Claude Code and Codex in interactive, WYSIWYG markdown docs, Calc Sheets, mermaid diagrams, excalidraw drawings, html mockups, data models, CSV files, in-app browser previews, mind maps, sessions, and code. Focus on one file: * Edit the file in the center panel. See red/green diffs from your coding agent and review, accept them. * Work with your agent in the right panel to edit this file or explore other files, research the web. * Navigate and manage your files in the left panel file manager
### Agent Mode * *Session Management:* organize, find, and continue your AI conversations. Track the files changed by a session and coordinate your stepping through and approving each one. * *Coding support:* All the power of Claude Code and Codex plus file tracking, diff visualization, code editing, and / command support with Github status tracking.
### Task Mode *Status & Item Tracking:* AI track and update status, bugs, to-dos, decisions, ideas directly in your markdown associated with the plan/work.
### Team Collaboration Every teammate runs the open-source Nimbalyst app on their own machine with the Codex, Claude Code, or other agents they use locally. After signing in to Nimbalyst Teams, they can promote local files into a shared team workspace and keep working with those agents. People and their agents can edit shared files together in real time or contribute asynchronously. Shared Trackers work the same way: teammates and their agents update one team board from their own Nimbalyst installations. Only files and Tracker items explicitly shared with the team enter this collaboration flow; everything else stays outside the team workspace. Shared team data flows through Nimbalyst's Cloudflare sync service. It is encrypted in transit and at rest and isolated per team. See [Nimbalyst for Teams](https://nimbalyst.com/teams/) for what the shared workspace covers. Start with the [Team Collaboration Overview](/team-collaboration/overview), then [Set Up Nimbalyst Teams and Organizations](/team-collaboration/setup-teams-and-orgs). ### Open Approach * Open source: the Nimbalyst app itself is open source at [github.com/nimbalyst](https://github.com/nimbalyst) * Open storage of content and status in markdown, code, html, * Future-proof - Your files will be readable in any text editor, forever * Portable - Move between different markdown tools without conversion * Version Control Friendly - Works perfectly with Git and other VCS * LLM-friendly - Work with Claude Code, Codex, and any AI * Open storage of workflow and config in coding agent / commands * Open storage of your files in your file tree or Github ### Ways to Use Nimbalyst 1. As an AI-integrated fast, local, WYSIWIG markdown editor 2. To mockup your UI in html, edit it with AI, provide this as context to your coding agent 3. As a planning tool to help you create and manage features, plans, to-dos, and ideas 4. To code with Claude Code or Codex 5. As a manager of your coding agent sessions integrating your plans with your agentic coding 6. To organize your work # Nimbalyst Tutorial and Demo Videos Three ways to learn Nimbalyst: watch a demo video, explore the sample tutorial workspace that ships with the app, or have an agent walk you through a 15-minute guided quickstart. [Download Nimbalyst](https://nimbalyst.com/download/) There are three ways to learn Nimbalyst, and they suit different moods. Watch a video to see what the app does. Open the tutorial workspace to click around in something already built. Run the guided quickstart when you want an agent to teach you by having you do real work. ## 1. Demo videos Start with the overview, then pick the walkthrough that matches your job. ### 1-minute overview The fastest look at what Nimbalyst is: agents, files, visual editors, and trackers in one workspace. {% embed url="" %} ### For product managers: idea to tracked work An onboarding revamp goes from an idea to an aligned team without anyone writing code. The agent researches the drop-off, drafts the PRD as a live document, and produces the user flow diagram and a clickable mockup beside it. One click turns the plan into tracked work on a shared board, and one more makes the document multiplayer so teammates comment in place. **1:26.** {% embed url="" %} More in the [product manager playlist](https://www.youtube.com/playlist?list=PLGm3n1OZjA5WN0-JX2Ia9b1d55vU63xKM). ### For developers: research, plan, diff, review A request for an API usage dashboard runs all the way to an approved pull request in one workspace. The first instruction is deliberately narrow, research and plan only, no code. The plan becomes an editable document with an architecture diagram and mockup inside it, every agent change shows as a diff you accept file by file, and the pull request gets reviewed in the same place. **1:13.** {% embed url="" %} More in the [developer playlist](https://www.youtube.com/playlist?list=PLGm3n1OZjA5XoEiKpcRp5f9M_HVySXDmg). The pull request review queue shown here needs Developer Mode turned on in settings. ### Longer walkthrough: product management use cases A 15-minute tour through product management workflows end to end. {% embed url="" %} ## 2. The tutorial workspace The first time you open Nimbalyst, the welcome screen asks which mode you want and offers **Start tutorial**.
The Welcome to Nimbalyst screen with Standard Mode and Developer Mode cards, role and referral questions, an optional email field, and Get started and Start tutorial buttons

Choose Standard or Developer Mode, then take the tutorial workspace or go straight to your own project.

* **Standard Mode** is a simplified interface focused on writing, editing, and AI assistance. * **Developer Mode** adds git worktrees, terminal access, and the rest of the development environment. See [Turn on/off Developer Mode](/developer-features/turn-on-off-developer-mode); you can switch later. * **Get started…** opens Nimbalyst against a folder you choose. **Start tutorial** creates the tutorial workspace instead. **Start tutorial** builds a small connected project called **Nimbalyst Tutorial** in your Documents folder. Nothing is set up or configured. Everything in it is a real file you can edit, break, and throw away.
The Nimbalyst Tutorial workspace, with a README listing things to try, a file tree of planning and design files, a live mockup embedded in the document, and an agent session open on the right

The tutorial workspace is a real project. The dashboard in the README is a live embed of a mockup file, not a picture of one.

The README lists things to try, and each one is a link into the workspace: * Type in the document, and try `/`, `#`, and `@`. * Ask the agent to add a summary at the top of the file, then review its red/green changes. * Shape an interface in the dashboard mockup, then ask the agent to change it. * Switch to Agents mode, look at past sessions, and click into the files they touched. * Explore a revenue spreadsheet, change assumptions in a metrics model, and follow the work into an architecture diagram. * Read a document with embedded project artifacts, turn a goal into steps with a launch checklist, and see a markdown document become a tracker item. If you skipped it during onboarding, you can start it later from **Help > Launch Tutorial**, or from **Try the interactive tutorial** on the workspace manager's welcome screen. Nimbalyst reuses the existing tutorial folder rather than making a second one, so the button reads **Open tutorial** once it exists. Delete the `Nimbalyst Tutorial` folder in your Documents folder whenever you are done with it. ## 3. The guided quickstart Learn Nimbalyst by doing your own real work in about 15 minutes, with an agent as the instructor. Product managers, founders, and designers finish with a working brief and an embedded mockup. Developers finish with a run-and-test guide, an embedded architecture diagram, and two agents running in parallel. Open a workspace in Nimbalyst, start a new chat, and paste this prompt: ``` Fetch https://raw.githubusercontent.com/nimbalyst/skills/main/skills/getting-started/quickstart.md, save it to nimbalyst-quickstart/quickstart.md in this workspace, then run it as the Nimbalyst quickstart. Wait for me at every exercise. ``` The agent saves the quickstart in your workspace, helps you choose the product or engineering track, and waits for you at each exercise. Everything it creates stays under `nimbalyst-quickstart/`, so you can remove the folder afterward if you do not want to keep the results. The [Nimbalyst quickstart on GitHub](https://github.com/nimbalyst/skills/blob/main/skills/getting-started/quickstart.md) is the source of truth. ## Setting up a team Working with other people is its own walkthrough. Sign in, create an organization and invite your team, then work together in shared trackers and shared documents while everyone's coding agents work in the same files. **2:46.** {% embed url="" %} The same seven steps in writing, with a screenshot for each: [Nimbalyst Teams: Step by Step](/team-collaboration/teams-tutorial). ## Use cases * [For Product Managers](https://nimbalyst.com/use-cases/product-managers/) * [For Developers](https://nimbalyst.com/use-cases/developers/) More workflows, from feature planning to bug analysis to design handoff, are on the [Nimbalyst use cases page](https://nimbalyst.com/use-cases/). # Quickstart Set up Nimbalyst in minutes. Open a project, connect a coding agent, and run your first AI session in a visual interface for Claude Code. Start by downloading the app from the [Nimbalyst download page](https://nimbalyst.com/download/). Mac and Windows builds are both there. ### **Open a Project**
* A project is a folder opened in Nimbalyst that maintains its history, context, window state. * If you have GitHub locally, you would choose various GitHub projects * If you don't, create a folder in your filesystem called Nimbalyst Projects * Open a folder into Nimbalyst and work there * You can have multiple Nimbalyst screens open working in different projects at the same time. A consistent color will help you tell them apart. * Project state is automatically saved and restored when you reopen the folder * (Return to this screen from Windows -> Project Manager or Command P to open another project) * You can only view and edit files that are in your Nimbalyst project, but you can have your coding agent read, use, manipulate files elsewhere on your computer if you give permission. ### **Coding Agents** Nimbalyst is the open-source visual workspace for building with Codex, Claude Code, and more. At least one coding agent must be installed. * If you already have a coding agent installed and running on your desktop, we will use it through its SDK. * If you do not have Claude Code CLI, or Codex CLI installed, you must do so yourself prior to using Nimbalyst. * You must either enter your API Key in the Settings in Nimbalyst or authenticate to OpenAI or Anthropic in their terminals. ### **Files Mode** Work with Claude Code and Codex in interactive, WYSIWYG markdown docs, mermaid diagrams, excalidraw drawings, html mockups, data models, CSV files, Calc Sheets, in-app browser previews, mind maps, sessions, and code. Focus on one file: * Edit the file in the center panel. See red/green diffs from your coding agent and review, accept them. * Work with your agent in the right panel to edit this file or explore other files, research the web. * Navigate and manage your files in the left panel file manager
#### Edit Markdown * Nimbalyst uses Markdown for everything (content, data, metadata) * Work in native markdown mode or in the WYSIWIG Editor with markdown commands * Open a markdown document from your folder, start editing it manually * Or create a New Document by clicking the icon or ... File > New (Cmd+N) creates a new document * Save with Cmd+S. Documents are saved as standard markdown files * Remember your documents are on disk in your file system and so they can be edited by other AIs or you in other applications * Cmd + Y will give you your file history and let you use it #### Calc Sheets * Create a `.calc.md` file when you want spreadsheet-style results in a markdown document * Calc Sheets are useful for pricing, estimates, budgets, unit conversions, and planning notes with formulas * You keep the source as plain text while Nimbalyst renders evaluated values beside it * See [Calc Sheets](/visual-editors-powered-by-ai/calc-sheets) #### Browser * Open `.html` files or live URLs in a real Chromium view inside Nimbalyst * Use the Browser to preview generated pages, inspect mockups, and verify frontend changes without switching apps * Ask your agent to navigate, click, type, scroll, evaluate, or screenshot the page * See [Browser](/visual-editors-powered-by-ai/browser) #### Mind Map * Create a `.mindmap` file when a roadmap, plan, or research topic is easier to understand spatially * Mind maps give you an infinite canvas with branches, notes, tags, colors, and AI-assisted expansion * The file stays readable and versionable, so agents can edit it like other project files * See [Mind Map](/visual-editors-powered-by-ai/mind-map) #### AI Chat Panel * Leverage the AI Chat panel to edit your documents or do research / chats * Select a provider from the dropdown (See [AI Provider Setup and Notifications](/setup-nimbalyst/ai-provider-setup-and-notifications) to set up Claude Code, Codex, and other providers) * The first time you try to use a coding agent, if you are not authenticated, the Agent chat will step you through authenticating. * The AI Agent can see and operate on your current document and your whole project * Type `@` to attach a file or folder to the conversation. In markdown documents, putting a supported custom-editor file reference on its own line turns it into an inline embed. * Use the **Actions** dropdown to insert reusable prompts like reviewing changed files, planning an implementation, drafting release notes, or inspecting the current editor * AI Edits show up as Red/Green Diffs for your approval * Each AI conversation is a session which can be saved and resumed #### **Edit Mockups**
* Create a mockup by typing /mockup in the agent panel . Click to open it in the editor. * Edit via modifying the html source or by annotating it (draw on it) or by selecting a div and then ask the agent to make changes * Embed the mockup into your document by typing / ### **Agent Mode** * *Session Management:* organize, find, and continue your AI conversations. Track the files changed by a session and coordinate your stepping through and approving each one. * *Coding support:* All the power of Claude Code and Codex plus file tracking, diff visualization, code editing, and / command support with Github status tracking.
* You conversation with the agent is in the central panel. Focus on this interaction * The left panel contains the list of your sessions. Group sessions together into workstreams * The right panel contains the files that the agent touched in that session or group of sessions. Click on a file to open it in the center. Right click to open it in files mode. If you already have a history of sessions in the Claude Code CLI, bring them into Nimbalyst with **File → Import Claude Code Sessions...**. See [Import Claude Code Sessions](/session-management/import-claude-code-sessions). ### Team and Collaboration Setup To collaborate with other people in this project: 1. Sign in under **Settings > Account > Accounts**. 2. Make sure the project has a git remote named `origin`. 3. Open **Settings > Project > Sharing** and create a team, join an invitation, or add the repository to an organization you already administer. 4. Invite teammates from the organization's member settings. 5. Open **Collaboration** mode to create shared documents, or right-click a supported local file and choose **Share to Team**. 6. Open **Trackers** to work on shared tracker types or promote hybrid items into the team tracker.
A shared planning document with teammate presence avatars and a live labeled cursor

Once the team is connected, people and their agents can work together in the same shared documents and trackers.

See [Set Up Nimbalyst Teams and Organizations](/team-collaboration/setup-teams-and-orgs) for the complete settings flow and [Team Collaboration Overview](/team-collaboration/overview) for how local and shared work fit together. ### Mobile App Manage your AI coding agents on the go with the Nimbalyst Mobile App. * **Session Dashboard** — see all active, completed, and paused sessions at a glance * **Diff Review** — swipe through file changes with red/green diffs optimized for mobile * **Resume & Reassign** — resume stalled sessions with a voice note or typed instruction from your phone * **Push Notifications** — get notified when sessions complete, hit errors, or need approval * **Desktop Sync** — changes approved on mobile appear instantly on desktop * **All Agents** — manage Claude Code and Codex sessions from one app See the full [mobile-app.md](/mobile/mobile-app) docs for details. ### Shortcuts * Click Help -> Shortcuts or enter Command / to see a list of shortcuts for Nimbalyst * **Cmd+O** — Open Unified Quick Open in the Files tab, then switch tabs for content search, sessions, prompts, projects, and trackers * **Cmd+K** — Agent Mode * **Cmd+E** — Files Mode * **Cmd+N** — New File/Session * **Cmd+Shift+N** — New AI session from any mode * **Cmd+Shift+K** — Session Kanban board * **Cmd+\[** / **Cmd+]** — Jump between tabs * **Cmd+Shift+V** — Force-paste as plain text ### 15-minute guided quickstart Learn Nimbalyst by doing real work in about 15 minutes. Product managers, founders, and designers finish with a working brief and an embedded mockup. Developers finish with a run-and-test guide, an embedded architecture diagram, and two agents running in parallel. Open a workspace in Nimbalyst, start a new chat, and paste this prompt: ``` Fetch https://raw.githubusercontent.com/nimbalyst/skills/main/skills/getting-started/quickstart.md, save it to nimbalyst-quickstart/quickstart.md in this workspace, then run it as the Nimbalyst quickstart. Wait for me at every exercise. ``` The agent will save the quickstart in your workspace, help you choose the product or engineering track, and wait for you at each exercise. Everything it creates stays under `nimbalyst-quickstart/`, so you can remove the folder afterward if you do not want to keep the results. The [Nimbalyst quickstart on GitHub](https://github.com/nimbalyst/skills/blob/main/skills/getting-started/quickstart.md) is the source of truth. ### Nimbalyst Teams, step by step To go further than the setup checklist above, [Nimbalyst Teams: Step by Step](/team-collaboration/teams-tutorial) walks the whole thing in seven steps, with a screenshot for each: signing in, creating an organization and inviting people, what your teammate receives, shared trackers, shared documents, and working alongside teammates who are in the browser rather than the desktop app. # Major Bugs, Outages, Feedback, Discord, Support, Releases Where to report Nimbalyst bugs, check current outage status, join the Discord community, reach the support team, and follow new releases. ### Major Bugs and Outages: * All Clear ### Discord * Join our [Discord Server ](https://discord.gg/FgD9S2MCYB)to find community, hear updates, discuss use cases, ### Support * Email ### In App Feedback * Click the feedback icon * ```
``` * Use the embedded skills to report a bug or request a feature
### GitHub Nimbalyst is open source. Browse the code, star the repos, or contribute at . * Submit your feature requests and bug reports here: * Pull requests welcome — see the contributing guide in the main repo ### X and LinkedIn * If you are loving Nimbalyst, please tweet about it and mention @nimbalyst. Follow us there too. * X: * LinkedIn: * YouTube: ### Release Notes? Please find our Release Notes [here](https://github.com/Nimbalyst/nimbalyst/releases) Every shipped release is listed on the [Nimbalyst changelog](https://nimbalyst.com/changelog/). # Markdown (WYSIWYG) Nimbalyst is a WYSIWYG AI markdown editor. Write visually while plain .md files stay on disk, with agent editing built into the same document.
### Why Nimbalyst as a Markdown Editor? * **Fast** - Blazing performance for distraction-free writing * **Clean UI** - Minimal interface focused on your content * **Focused** - Dedicated to markdown writing and editing * **Native Markdown** - True markdown support without compromises * **WYSIWYG** - See formatted output as you type * **Delightful** - Smooth, intuitive user experience * **Unified Content** - Work seamlessly with text, tables, code, lists, and images. * **AI-Integrated -** Leverage AI and Agents that see your documents to research, write, edit, code The [markdown editor feature page](https://nimbalyst.com/features/markdown-editor/) has a fuller walkthrough of WYSIWYG editing with agents. ### Important Commands * **Reference a file in another document or in chat:** @ — supported custom-editor files (mockups, Excalidraw, data models, CSV, etc.) embed as live frames when the link is on its own line. See "Embedding Custom-Editor Files" below. * **Open the mega-menu of insertion options:** / * **Create a tagged bug, idea, plan:** # * **Text selection toolbar** appears when you select text, providing quick formatting options. * **Markdown formatting and commands are supported**
### File and Editor View Work with your markdown files, edit the documents in WYSIWIG
### WYSIWIG Markdown Toggle between Markdown and WYSIWIG using the 3 dots at the upper right of the document
### Text Some basic markdown commands * **Headings:** # followed by space for H1, ## followed by space for H2 * **Lists:** - or \* followed by space, Tab to indent * **Numbered Lists:** 1 followed by space * **Links:** Select text and select link icon in toolbar * **Quotes:** Type > followed by space. Nest by typing >> * **Code Blocks:** Type / and insert * **Horizontal Rule:** Type --- * **Markdown Text Formatting:** Supported ### Tables ![](/files/j3UPp2QcjiArxVozXV9B) **Create a table by typing /**
Format Table by clicking on down arrow
### Embedding Custom-Editor Files A markdown document can render other workspace files inline as live frames. Drop a link to a file like `.mockup.html`, `.excalidraw`, `.datamodel`, `.csv`, or any other custom-editor file on its own line and Nimbalyst upgrades it into an embedded editor in WYSIWYG view.
A markdown spec with a mockup and an Excalidraw diagram embedded inline below their @-references

A markdown spec with a mockup and an Excalidraw diagram embedded inline.

How it works: * Type `@` to pick a file. If the file is a supported custom-editor type and the link ends up alone in its own paragraph, it auto-upgrades to an inline embed. * You can also paste a normal markdown link like `[my mockup](./docs/api.mockup.html)` on its own line. * The embedded frame is the real editor for that file. Edit it in place and the change saves back to the file on disk. * Multiple users see embedded edits stream in live when the document is shared. Switch to raw Markdown view (the three dots at the top right) to see the underlying link. The link round-trips: write a link in raw view, switch to WYSIWYG, and it becomes a live frame. ### AI Editing in Shared Collaborative Documents When you are editing a shared document in collaboration mode, the right-pane chat sees and edits the active document the same way it does in Files mode. Edits route through Yjs, so other connected users see them stream in live. The familiar accept/reject bar appears for pending AI edits, just like in single-user editing. You don't need to do anything special to turn this on — open a shared document, ask the agent to edit it, and the changes flow into the document for everyone in the session. ### Anchor Links to Headings Clicking a Markdown anchor link like `[Section](#section)` in a Lexical document scrolls the document to the matching heading. ### Export to PDF Markdown documents export to PDF with the document title and an outline generated from your headings. Exported files are bookmarked at each heading and the title shows up in PDF readers. ### Undo/Redo Stack Nimbalyst enables you to undo and redo your edits * Cmd+Z to Undo * Cmd+Option+Z to Redo # Find & Replace and ToC Use Cmd+F find and replace plus the auto-generated table of contents to move around long markdown documents in Nimbalyst without scrolling. ### Find & Replace Type Cmd-F to Find or Find and Replace ![](/files/JBtcWkBZSqfLkvTCgUqZ) ### Table of Contents Auto-Generated TOC based on document headings Click a heading to jump to that section.
More editor features are on the [markdown editor page](https://nimbalyst.com/features/markdown-editor/). # AI Editing, Red/Green Diff, Approval How AI editing works in Nimbalyst documents. The agent proposes changes as a red and green diff, and nothing is written until you approve it.
### AI-Powered Editing Reviewing agent changes visually rather than in a terminal is covered on the [agent integration page](https://nimbalyst.com/features/agent-integration/). #### Agent Panel Runs on the right rail in your document/file view
* Open the AI panel by clicking the AI icon or Cmd+Shift+A toggles panel * Select an AI provider from the dropdown and type your message * Click on New message to change context. This starts a new Session. * Paste attachments or images into the chat #### **Chat** * You can Chat in the Agent panel without editing your document * Use this to research, explore, learn #### **Requesting Edits** * You can ask AI to modify your document * "Add a section about X" * "Rewrite this paragraph" #### **Streaming Edits:** * Changes appear as they are ready * Visual diff shows additions/deletions * Toolbar appears for review #### Plan Mode and Agent Mode * Plan mode limits the Agent to editing markdown and create markdown files * Agent mode gives the full power of the agent * Click on the Plan or Agent icon to toggle modes
### Red/Green Diff
* Shows changes made by the AI to the document * Enables Keep/Undo of all changes or one by one * Clicking on change or arrow selects that change and takes you to it ### Agent Context & Conversations #### **The Agent is passed and understands the following context:** * Document context: Current file content * Workspace context: File tree, related files * Session context: Conversation history #### When conversing with the Agent * AI automatically includes the open document * You can reference other files by name by typing @ * You can include images and code snippets in messages #### **Best Practices:** * Be specific about context needs * "Looking at the function in file.ts..." * Include relevant code/text in message #### Context Window The 18k/200K Tokens indicats how many words/tokens can fit in this chat session. When you get close to 100%, make sure to hit +New and create a new session.
### AI Tool Calls AI can invoke tools to perform actions beyond text generation. #### **Available Tools:** * File operations (read, write, search) * Code analysis and execution * Web search and research * Data processing \ Tool results shown in chat with special formatting. #### Show Tool Calls in Chat By default, every tool call the agent makes appears as a row in the transcript. To hide them entirely (not just collapse them), turn off **Show Tool Calls in Chat** under **Settings > Application > Agent Features**. Interactive prompts — permission requests, plan-mode exits, commit proposals, AskUserQuestion, PromptForUserInput — still appear so you can always respond.
# Mermaid Diagrams and Images Insert and edit Mermaid diagrams and images inside Nimbalyst markdown documents, by hand or by asking your AI agent to generate the syntax. ### Mermaid Diagrams
Manually: Insert the Mermaid Diagram in WYSIWIG mode and click edit to manually edit the mermaid syntax With AI: Ask AI to create a Mermaid Diagram. Then Edit it manually or iterate on it with AI. See the [diagrams feature page](https://nimbalyst.com/features/diagrams/) for how teams use Mermaid and Excalidraw together, and [architecture diagrams](https://nimbalyst.com/use-cases/architecture-diagrams/) for a worked example. **Diagram Types Include** * Flowchart * Sequence diagram * Gantt chart * Class diagram * State diagram * Entity relationship ### Images
Nimbalyst enable support for images by storing the image in an assets folder in the same directory as the markdown file with a link to the image's location in the markdown file. You can paste or insert an image and resize it\
# Mockups Build HTML mockups in Nimbalyst using your docs, code, and sessions as context, then hand the same mockups to your agent to implement. Use all your context (docs, sessions, code) to build your mockups with your coding agent. Use your mockups and docs to build your code. No copy/paste needed. See the [mockups feature page](https://nimbalyst.com/features/mockups/) for how mockups feed back into implementation, and [UI mockups](https://nimbalyst.com/use-cases/ui-mockups/) for a full example.
### Create a Mockup Create the Mockup * Select New -> New Mockup * or type /mockup in the chat Describe the Mockup you want created * In the Agent chat, describe the mockup you want created * Reference documents with the @ command * Include images or screenshots into the agent chat ### Edit the Mockup Open the mockup in the mockup editor (by clicking on it)
**Edit it in 3 ways** * Directly in the html * By selecting a div and asking the AI to modify it * By annotating the mockup by drawing on it and then asking AI to modify it ### Multi-Screen Projects Group multiple mockup screens together to design full flows — checkout, onboarding, settings, whatever spans more than one screen.
**Create a project** * Select New -> New Mockup Project * or type /mockup in the chat and describe a multi-screen flow **On the canvas** * Drag screens around to arrange them spatially * Draw connections between screens to show navigation flow, and label the connections (click, hover, navigate) * Click Add Screen to create a new mockup, or drag an existing .mockup.html in from the file tree * Click Auto Layout to snap screens into a grid * Double-click a screen to open it in the mockup editor **File type and storage** Projects are stored as .mockupproject files (JSON that references individual .mockup.html files). By default they live in Nimbalyst-Local/Mockups alongside your mockups. ### Insert a Mockup into a Markdown Document
Select / and then insert a mockup Click on the mockup to edit it ### Mockup File Type and Storage Mockups are of file type .mockup.html By default, they are stored in a Mockups Folder in Nimbalyst-Local, but you can change this. ## Working with the AI ### Tips for Better Results * **Be specific about layout** -- "Two-column layout with 30% sidebar" is better than "add a sidebar" * **Reference real products** -- "Style it like the Stripe dashboard" gives the AI a clear design reference * **Describe interactions** -- "When hovering over a row, show a blue highlight and a delete icon on the right" * **Iterate in small steps** -- Make one change at a time so you can evaluate each iteration ### What the AI Sees When you ask the AI to edit a mockup, it: 1. Captures a screenshot of the current rendered mockup 2. Reads the HTML source code 3. Sees any annotations you've drawn 4. Understands which element you've selected (if any) This multi-modal context means you can give instructions like "make the thing I circled bigger" and the AI understands what you're referring to. ### Design-to-Code Workflow Mockups are real HTML and CSS, which makes them a useful bridge between design and implementation: 1. **Design in mockups** -- Iterate on the visual design with AI assistance 2. **Review with stakeholders** -- Share the rendered mockup for feedback 3. **Extract patterns** -- Use the mockup's HTML/CSS as a reference when implementing the real UI 4. **Maintain alongside code** -- Keep mockups updated as the product evolves for documentation ## File Format Mockups use standard HTML with inline CSS. No special build tools or frameworks required. ```html

Settings

``` Using `var(--nim-*)` CSS variables ensures your mockup adapts to light and dark themes automatically. # Data Models Design database schemas visually in Nimbalyst. Build a Prisma-based data model with AI from your existing code and markdown documentation.
Humans and AI work better with all the context united, integrated. Now in Nimbalyst, build your data model with AI based on your code and markdown docs. Then, use that data model and your docs to write better code. More on the visual schema editor is on the [data modeling feature page](https://nimbalyst.com/features/data-modeling/) and the [DataModelLM extension page](https://nimbalyst.com/extensions/datamodellm/). * **Ask AI to create a Data Model:** Use the /datamodel command and specify what you want * **Edit the Data Model:** We've built a visual editor where you can edit the data model yourself or ask for edits from Claude in the chat panel. Click on the data model file to auto-open the editor. * **Embed the Data Model:** Use / in the doc to embed a live screenshot of the data model in your markdown * **Store and Export the Data Model:** We stored the data model as a .prisma file in your filesystem /git. Export the data model as a SQL DDL, JSON Schema, DBML, or JSON (DataModelLM) format
# CSV Open CSV and TSV files in the built-in Nimbalyst spreadsheet editor, edit rows and columns visually, and let your AI agent work the same data. Nimbalyst includes a built-in spreadsheet editor for CSV and TSV files. Open any `.csv` or `.tsv` file and it automatically displays in a familiar spreadsheet interface. See the [spreadsheets feature page](https://nimbalyst.com/features/spreadsheets/) for how agents work with tabular data in a project. If you want a calculation-first document instead of a row-and-column data grid, use a [Calc Sheet](/visual-editors-powered-by-ai/calc-sheets) with the `.calc.md` extension.
### CSV Spreadsheet Editor The editor works like Excel or Google Sheets. You can:
* Edit cells, rows, and columns manually * Cut, copy, and paste Click **View Source** in the toolbar to toggle between the spreadsheet view and raw CSV text. ### Using Coding Agents with CSV Files Your coding agent can read and modify your CSV files directly. This is powerful for data tasks that would be tedious to do manually. **Data Cleaning** * "Remove all duplicate rows from data.csv" * "Fix the date format in the 'created\_at' column to YYYY-MM-DD" * "Trim whitespace from all cells in customers.csv" **Data Transformation** * "Add a new column that calculates the total from price and quantity" * "Split the 'full\_name' column into 'first\_name' and 'last\_name'" * "Convert all country codes to full country names" **Analysis & Filtering** * "Remove all rows where status is 'cancelled'" * "Sort by revenue descending and keep only the top 100" * "Find and flag any rows with missing email addresses" **Bulk Operations** * "Add 'USD' prefix to all values in the currency column" * "Replace all instances of 'N/A' with empty cells" * "Normalize phone numbers to +1-XXX-XXX-XXXX format" **Generating Data** * "Create a CSV with 50 sample customer records for testing" * "Add a header row with appropriate column names" #### How It Works When you ask your coding agent to modify a CSV file, it reads the file, makes the changes programmatically, and writes the updated content back. The spreadsheet editor will automatically refresh to show your changes. #### AI Changes as Red / Green Diff * Additions will be shown in green * Deletions will be shown in red # Browser Preview HTML files and live URLs in the built-in Chromium browser, right next to your project files and your AI coding agent conversation. Nimbalyst includes an in-app Browser editor for previewing HTML files and live URLs without leaving your workspace. It opens pages in a real Chromium view, next to your files and agent conversation. Use it when you want to see a generated page, review an HTML mockup, or check a live URL while Claude Code, Codex, or another agent keeps working in the same project. The [browser extension page](https://nimbalyst.com/extensions/browser/) covers what an agent can do inside the in-app browser.
In-app Browser editor showing a rendered page with URL controls, file tree, and agent sidebar
## What the Browser Is Good For * Previewing `.html` and `.htm` files directly from the file tree * Opening a live URL beside the code, notes, and agent transcript * Reviewing frontend changes without switching to a separate browser window * Checking generated mockups and landing pages as rendered pages * Letting an agent inspect, click, type, scroll, evaluate, and screenshot a page ## Built-In Capabilities * Real Chromium rendering, not an iframe * Back, forward, reload, and URL bar controls * Source toggle when you want to move between rendered preview and file source * Workspace-scoped local preview URLs for files * Fileless browser tabs for live pages * Agent tools for navigation, page inspection, clicks, typing, scrolling, screenshots, and JavaScript evaluation ## Browser vs Code Editor Use the **Browser** when you need to inspect the rendered result of an HTML file or URL. Use the **Code Editor** when you need to edit the source of the HTML, CSS, JavaScript, or TypeScript file. In practice, you often use both: edit source in one tab, open the Browser in another tab, and ask your agent to revise the page while you review the rendered result. ## Working with AI Your coding agent can use the Browser to verify UI work in place. Good prompts include: * "Open this HTML file in the Browser and check whether the CTA button is visible." * "Change the hero copy, then preview the page in the Browser." * "Click through the form and tell me what breaks." * "Take a screenshot of the current page state." * "Inspect the page and summarize the visible headings and links." # Calc Sheets Calc Sheets are markdown spreadsheets (.calc.md) that keep assumptions, formulas, and outputs in one versionable file your AI agent can edit. Calc Sheets are markdown documents that end in `.calc.md`. They combine spreadsheet-style calculated results with plain-text editing, so you can keep assumptions, formulas, notes, and outputs together in one versionable file. Unlike a CSV grid, a Calc Sheet reads like a working document. You write inputs and formulas as text on the left, and Nimbalyst renders the evaluated results alongside them. The [Calc Sheets extension page](https://nimbalyst.com/extensions/calc-sheets/) covers the formula syntax and unit handling in more depth.
Calc Sheet editor showing assumptions, formulas, units, and live results beside the source
## What Calc Sheets Are Good For * Quick estimates, budgets, and pricing models * Unit-aware calculations inside planning docs * Financial notes where currency formatting matters * AI-assisted calculation files that should still stay readable in plain text * Scenario analysis where the assumptions matter as much as the final result ## Example ```md # Inputs price = 100 USD quantity = 1 # Results total = price * quantity -> currency(USD, 2) ``` In Nimbalyst, the source stays editable as markdown while the computed values appear beside it in a spreadsheet-like results column. ## Built-In Capabilities * Text-first calculations in plain `.calc.md` files * Units and currency-aware formatting * Live result gutter beside the source * Assertions so a sheet can catch invalid assumptions early * Natural fit with Git, diffs, and agent-driven edits * Source mode that stays readable in any text editor ## Calc Sheets vs CSV Use **Calc Sheets** when the file is mostly a human-readable calculation document with a few important formulas. Use **CSV** when the file is primarily tabular data with many rows and columns. See also [CSV](/visual-editors-powered-by-ai/csv). ## Working with AI Your coding agent can edit `.calc.md` files the same way it edits markdown or code. Good prompts include: * "Turn this pricing note into a calc sheet with subtotals and a final total." * "Add a margin assumption and recompute the quoted price." * "Convert these hard-coded numbers into named inputs." * "Add assertions so the total fails if quantity is negative." * "Adjust the payload assumption and explain which checks changed." # Mind Map Mind Map is a spatial editor for .mindmap files. Brainstorm on an infinite canvas while the file stays plain text your AI agent can also edit. Nimbalyst Mind Map is a spatial editor for `.mindmap` files. It lets you lay out ideas on an infinite canvas while keeping the underlying file readable, versionable, and editable by agents. Use it for brainstorming, project planning, research organization, decision trees, and any topic where a hierarchy is easier to understand visually than as a long outline. The [mind map extension page](https://nimbalyst.com/extensions/mindmap/) shows the file format and how agents edit maps.
Mind Map editor showing a color-coded roadmap on an infinite canvas with file tree and agent sidebar
## What Mind Maps Are Good For * Breaking a project into themes, branches, and follow-up work * Organizing research notes by concept or domain * Capturing meeting ideas spatially while preserving structure * Mapping product roadmaps, launch plans, and decision trees * Turning a topic prompt into a structured map your team can revise ## Built-In Capabilities * Infinite canvas with pan and zoom * Nodes, branches, notes, tags, status, and color coding * Keyboard-driven editing for adding children, siblings, and updates quickly * Auto layout for cleaning up a map * Outline view when a hierarchy is easier to edit as text * Search across nodes * AI-assisted creation and branch expansion ## Plain-Text Files Mind maps are stored as `.mindmap` files. That means they can live with the rest of your project, sync like other files, and be reviewed in Git. The visual editor gives you the canvas, but the file remains structured enough for Claude Code, Codex, and other agents to read and update. ## Working with AI Your coding agent can create, expand, and reorganize mind maps. Good prompts include: * "Create a mind map for this product launch plan." * "Expand the Discovery branch with customer research tasks." * "Reorganize this map into Design, Build, Launch, and Measure." * "Add notes to each high-risk branch." * "Turn this outline into a mind map." # Excalidraw Draw diagrams, flowcharts, and whiteboard sketches in the built-in Excalidraw editor, and let your AI agent build them from a description. ### Overview Nimbalyst includes a built-in Excalidraw editor for creating diagrams, flowcharts, and whiteboard sketches. Files open in a visual canvas where you can draw shapes, connect them with arrows, and let AI help build diagrams from descriptions. The [Excalidraw extension page](https://nimbalyst.com/extensions/excalidraw/) lists what the built-in canvas supports.
### AI-Assisted Diagramming Ask the AI to create or modify diagrams directly. The AI can: * Add shapes with labels and colors * Connect elements with arrows * Import Mermaid diagrams * Align and distribute elements * Group elements together * Create rows and columns of shapes ### Human Diagramming Right-click in the file tree and select **New File > Excalidraw Diagram**, or create any file with the `.excalidraw` extension. The toolbar provides standard Excalidraw tools: * **Selection**: Click and drag to select elements * **Rectangle**: Draw boxes (rounded by default) * **Diamond**: Draw decision shapes * **Ellipse**: Draw circles and ovals * **Arrow**: Connect elements with arrows * **Line**: Draw freeform lines * **Text**: Add text labels * **Frame**: Group related elements with a titled container #### Example AI Prompts * "Create a flowchart showing user login flow" * "Add a blue rectangle labeled 'Database'" * "Connect 'Frontend' to 'API' with an arrow" * "Import this mermaid diagram: graph TD; A-->B" * "Align all the boxes on the left" ### Mermaid Import Convert Mermaid syntax to visual diagrams: ``` graph TD A[Start] --> B{Decision} B -->|Yes| C[Action] B -->|No| D[End] ``` Ask the AI to import Mermaid, or use the `import_mermaid` tool directly. ### Working with Frames Frames are titled containers that group related elements. Use them to organize architecture diagrams into sections like "Browser", "Services", or "Database". Create frames manually or ask the AI: "Add a frame called 'Frontend' around the React components" ### Theme Support The editor adapts to your Nimbalyst theme. Light themes show a white canvas; dark themes show a dark canvas with adjusted colors. ### Tips * **Pan canvas**: Hold space and drag, or use two-finger scroll * **Zoom**: Cmd/Ctrl + scroll, or use the zoom controls * **Duplicate**: Alt + drag to duplicate elements * **Snap to grid**: Hold Cmd/Ctrl while dragging for alignment * **Lock elements**: Prevent accidental edits by locking shapes # PDF Viewer Open and read PDF documents in Nimbalyst tabs alongside your other project files, with smooth scrolling, zoom controls, and text selection. Nimbalyst includes a built-in PDF viewer that lets you open and view PDF documents directly in the editor. PDFs open in their own tabs alongside your other files, with support for smooth scrolling, zoom controls, and text selection. See the [PDF viewer extension page](https://nimbalyst.com/extensions/pdf-viewer/). ### Opening PDFs Click any `.pdf` file in your file tree to open it. The PDF loads in a dedicated viewer tab with a toolbar at the top. PDFs are read-only in Nimbalyst. To edit a PDF, use a dedicated PDF editor. ### Viewing Controls #### Toolbar The toolbar appears at the top of the PDF viewer and shows: * **Page count**: Total number of pages (e.g., "10 pages") * **Zoom controls**: Plus/minus buttons and current zoom percentage * **Fit button**: Toggle fit-to-width mode #### Scrolling Scroll through the PDF using: * Mouse wheel or trackpad * Scroll bars * Page Up / Page Down keys Pages flow continuously like a modern PDF reader. Large documents (100+ pages) remain smooth thanks to efficient rendering. ### Text Selection You can select and copy text from PDFs: 1. Click and drag to select text on any page 2. Selected text is highlighted 3. Press **Cmd/Ctrl + C** to copy Text selection works like any standard PDF reader. ### Theme Support The PDF viewer adapts to your Nimbalyst theme: * **Light theme**: Standard white pages with subtle shadows * **Dark theme**: White pages with enhanced shadows for contrast * Toolbar and controls match your theme colors # Code Editor Nimbalyst includes a Monaco code editor, the same engine VS Code uses, with syntax highlighting and AI edits next to your docs and diagrams. Nimbalyst includes a full-featured code editor powered by Monaco (the same editor used in VS Code). When you open a code file, it automatically opens in Monaco with syntax highlighting and standard editing features. Code editing sits next to the rest of the workspace rather than in a separate app. See the [developer tools page](https://nimbalyst.com/features/developer-tools/).
### Reviewing AI Changes When the AI edits a code file, you'll see an inline diff view: When the AI edits code or a a document, changes appear inline: * Green background: Added content * Red background: Removed content (with strikethrough) Navigation * Previous/Next buttons: Jump between changes in the file * Change counter: Shows how many changes are in the diff (e.g., "Change 2 of 5") Accept/Reject: * Accept All: Keeps all changes * Reject All: Reverts to original content Changes remain visible until you accept or reject them.
### Supported File Types The code editor supports a wide range of programming languages: #### Web Development * JavaScript: `.js`, `.jsx`, `.mjs`, `.cjs` * TypeScript: `.ts`, `.tsx`, `.d.ts` * HTML: `.html`, `.htm` * CSS: `.css`, `.scss`, `.sass`, `.less` #### Data Formats * JSON: `.json`, `.jsonc` * YAML: `.yaml`, `.yml` * XML: `.xml` * TOML: `.toml` #### Programming Languages * Python: `.py`, `.pyw`, `.pyi` * Go: `.go` * Rust: `.rs` * C/C++: `.c`, `.h`, `.cpp`, `.cc`, `.hpp` * Java: `.java` * C#: `.cs` * Swift: `.swift` * Kotlin: `.kt` * Ruby: `.rb` * PHP: `.php` * Dart: `.dart` #### Shell & Config * Shell scripts: `.sh`, `.bash`, `.zsh`, `.fish` * SQL: `.sql` * GraphQL: `.graphql` * Dockerfile #### Other * Markdown: `.md` (raw view mode) * Plain text: `.txt`, `.log` ### Editor Features #### Syntax Highlighting Each language gets appropriate color highlighting, making code easy to read and understand. #### Line Numbers Line numbers appear on the left side for easy navigation and referenc #### Minimap A code overview appears on the right side, letting you see the structure of longer files and quickly jump to different sections. #### Code Folding Click the arrows next to code blocks to collapse or expand them. Works with: * Functions and methods * Classes * Conditional blocks * Loops * JSON objects and arrays #### Bracket Matching Matching brackets, braces, and parentheses are highlighted in color, making it easy to see paired delimiters. ### Editing Code #### Autosave Changes save automatically after 2 seconds of inactivity. A dot in the tab title indicates unsaved changes. #### Manual Save Press **Cmd+S** (Mac) or **Ctrl+S** (Windows/Linux) to save immediately. All common editing shortcuts work: * **Cmd/Ctrl+C**: Copy * **Cmd/Ctrl+V**: Paste * **Cmd/Ctrl+Z**: Undo * **Cmd/Ctrl+Shift+Z**: Redo * **Cmd/Ctrl+F**: Find * **Cmd/Ctrl+H**: Find and replace #### Indentation The editor uses 2-space indentation by default and automatically detects the indentation style of existing files. ### File Watching The editor detects when files are changed by other programs: * If you have no unsaved changes, the file reloads automatically * If you have unsaved changes, you'll be prompted to keep your version or reload the external changes ### File History Code file edits are tracked in your file history: * Press **Cmd+Y** (Mac) or **Ctrl+Y** (Windows/Linux) to open file history * Restore any previous version of the file * See when changes were made ### Tips * **Hover for full path**: Hover over a tab to see the complete file path * **Multiple files**: Open code and markdown files side by side in tabs * **Theme support**: The editor automatically matches your Nimbalyst theme (light/dark) * **Focus indicator**: When you click elsewhere and return, your cursor position is preserved # File History and Restore Nimbalyst saves file snapshots automatically. Open history with Cmd+Y to compare versions and restore a document after an AI edit goes wrong. ### Files with Unsaved Changes Tabs show a dot (•) next to filenames with unsaved changes. The dot disappears after: * Manual save (Cmd+S) * Autosave (configurable interval) ### File History (Cmd+Y) Nimbalyst automatically saves snapshots of your documents, providing version control built into the editor. Snapshots saved periodically * Manual snapshot on Cmd+S * Compressed storage in database * No external tools needed
#### Viewing History
* Cmd+Y opens history panel * View > Document History * List of all snapshots * Timestamps for each version * Preview snapshot content * Restore history * Current version becomes new snapshot. History preserved. Can undo restoration if needed. #### Comparing snapshots Just clicking on a snapshot will compare it to the previous checkpoint Click on one snapshot and then command-click on the other to compare it to a different snapshot
* Study the differences then choose the snapshot you desire. #### **Deleting Snapshots:** * Select snapshot and then Click delete icon ### Restoring History * Select a snapshot and you can restore that version ### Where snapshots are stored Snapshots live in the `document_history` table of Nimbalyst's local database, inside the application data folder: | Platform | Application data folder | | -------- | ----------------------------------------- | | macOS | `~/Library/Application Support/Nimbalyst` | | Windows | `%APPDATA%\Nimbalyst` | | Linux | `~/.config/Nimbalyst` | Newer installs use SQLite (`sqlite-db/nimbalyst.sqlite`). Installs that predate the SQLite migration use PGLite (the `pglite-db/` folder) until they migrate. Development builds use a `@nimbalyst/electron` folder in the same location. That database is backed up automatically every 4 hours and on quit, so document history survives a corrupted database. See [Database Backups and Restore](/troubleshooting/database-backups-and-restore).
# File Search, File Tree, and Tabs Find files fast in Nimbalyst with Quick Open (Cmd+O), the project file tree, and tabs for working across several documents at the same time. ### Quick Open and Search
Click the magnifying glass or press **Cmd+O** to open the unified Quick Open launcher.
Quick Open now brings several pickers together in one tabbed surface: * **Files** - find files and folders by name, including dotfiles and images * **In Files** - search within file contents across the project * **Sessions** - jump to AI sessions and workstreams * **Prompts** - find prompts * **Projects** - switch between open projects * **Trackers** - jump directly to tracker items * **Memory** - search project knowledge across Docs, Trackers, and optionally Sessions when the Nimbalyst Memory extension is enabled The Files results can also include team shared documents. Opening one takes you to its collaborative editor. Use the tab bar to switch modes, and use the inline filters for narrower results. In the **Files** tab, selecting a folder reveals it in the file tree. Direct shortcuts for some tabs are shown inside the launcher itself. #### Search Shortcuts * **Cmd+O** — Quick Open for files, folders, shared documents, projects, and Tracker items * **Cmd+L** — Session Quick Open * **Cmd+Shift+L** — Prompt Quick Open * **Cmd+Shift+F** — file-content search * **Cmd+Shift+O** — Memory search * **Cmd+Shift+D** — team shared-document search Filename search, file-content search, and Memory search answer different questions: * Use **Files** when you know all or part of a file name. * Use **In Files** when you know the exact text inside a local file. * Use **Trackers** for exact issue-key lookup or structured Tracker search. * Use **Memory** for a concept or question that may be described differently across documents, Trackers, and sessions. Memory combines semantic and keyword matching.
### File Tree
The file tree shows all files in your project. Navigate them by: * Click folders to expand/collapse * Click files to open * Recent files appear at top of sidebar * Right Click on a file to rename, delete, open, copy path, open in new window * Move files by dragging (Hold Option/Alt to copy) * Deleted files, attachments, assets, and themes move to system trash instead of permanent deletion * Show dotfiles in the file tree by selecting the "All Files" filter * In a team project, right-click a collaboration-supported file and choose **Share to Team** to promote it into the shared document space. See [Collaborative Documents](/team-collaboration/documents). ### Tab Management
Tabs let you work with multiple documents (or sessions) in one window. * Dirty indicator (•) shows unsaved changes * Open tabs are saved when workspace closes and restored when workspace reopens * Pin a tab to the far left by right clicking and selecting Pin Tab * Shortcuts are available to move amongst tabs * Move amongst your tabs with the Tab dropdown ### Paste Options * **Cmd+Shift+V** — force-paste as plain text without attachment conversion ### Navigation Gutter * Right-click the navigation gutter and choose **Customize Gutter** to hide or show mode, extension-panel, and status icons. * Drag icons into a manual order inside their group. * Right-click an individual gutter icon to hide it directly. * Changes apply immediately to every open Nimbalyst window and persist across projects. * The account and Settings control remains available and cannot be hidden. # Share Link to a File Create a public share link for any markdown or AI file in Nimbalyst so people outside your workspace can read the document in a browser. Share any AI or markdown file with a public link.
**How to use:** 1. Right-click on a markdown file in the file tree 2. Select **Share Link** 3. A link is copied to your clipboard 4. Paste it anywhere -- Slack, email, X, a doc
**Important! Security and Safety.** * Anyone with the link can view the session or file. Do not share sessions containing sensitive information. * Shared content is hosted on Cloudflare R2. There is no password protection. * The content is encrypted on Cloudflare so Nimbalyst, Inc has no ability to read the content # File Edits Sidebar The File Edits Sidebar tracks every file your AI agent read or changed during a session, so you can review each modification before accepting. The File Edits Sidebar tracks every file that the AI interacts with during a session. It provides visibility into which files have been modified, referenced, or read and those that need review.
* Every file the AI edited appears in the sidebar list * Click a file to jump directly to the AI session that made the edit * See how many changes are in each file and navigate between them * **All Uncommitted Files** mode shows files with pending changes across your project ### Diff Peek Hover any row in the Files Edited list and a peek icon appears on the right. Click it to open a unified diff popover anchored to the row, so you can see exactly what the agent changed without leaving the session view or opening the file.
A pinned diff peek showing changes for a file in the All Session Edits sidebar

Review a file's changes from All Session Edits without leaving the agent session.

* Hover the row to reveal the peek icon * Click the icon to pin the diff popover * The popover is resizable, and the size you pick is remembered (it stays in sync with the diff peek in the Git extension and the commit proposal widget) * Click outside or press Esc to close # Agent Window & Session Management Manage AI coding sessions in the Nimbalyst Agent Window. Start, resume, group, rename, and search long-running Claude Code and Codex sessions. ### Agent Window In the File Window, you focus on editing your markdown files. In the Agent Window, you focus on your sessions with your Agent. These sessions could include long chat discussions, research sessions, complex multi-file tasks, and AI-assisted development.
The Agent Window consists of three main areas: * Left Sidebar showing your Sessions. You can Search sessions here and select them * Central transcript area to converse with agent with full conversation history, tool call visualization, streaming content display * Right panel, which you can switch between edited files, review, and a chat about the session The [session management feature page](https://nimbalyst.com/features/session-management/) shows how sessions, workstreams, and the kanban view fit together. #### Choose What the Right Panel Shows The right panel is a switcher. Use the dropdown in its header to change what it displays.
The agent window right panel dropdown, open on three options: Edited Files with a checkmark, Review, and Chat with Session

Switch the right panel between edited files, review, and a chat about the session.

* **Edited Files** -- The files the agent created and changed in this session, with uncommitted changes and commit controls. * **Review** -- The review queue for changes waiting on your approval. * **Chat with Session** -- A conversation about the session itself, kept separate from the main transcript. You can also open a tracker item as a tab in this window and work the item and the session together. See [Item Detail](/task-management/item-detail). ### Session Management Run multiple parallel sessions. Manage Sessions by: * Searching * Filtering * Resuming Relate Sessions to Documents and Documents to Sessions.
### Session Features
* **Turn summary stats** — each agent turn shows file count and line changes (e.g., "Finished in 6m 57s — 3 files +45 -12") * **Click-to-copy code blocks** — click or tap inline code blocks in transcripts to copy with visual feedback * **Maximize button** — in the chat sidebar, click the maximize button to open the current session in full agent mode * **Drag-drop to create Workstreams** — drag a session onto a standalone session to create a Workstream * **Start session from a document** — "Start a new agent session" from a document pre-populates with an @file reference to that document * **Rename a session** — right-click an existing session in the list and choose Rename. Sub-session renames live-update; workstream parent rows also support inline rename * **Preferred Agent Language** — under **Settings > Application > Agent Features**, set the language used to auto-generate session names (applies to Claude Code, Codex, and other providers) ### Start a Background Session from Anywhere Press **Cmd+Shift+N** from any Nimbalyst mode to open the session launcher over your current work.
The Launch New Session composer floating over an open Excalidraw document

Start a session without leaving the document, Tracker, pull request, or shared file you are viewing.

The launcher includes the same controls as the normal chat composer: * Choose the agent and model. * Set effort and supported thinking controls. * Insert an Action or slash command. * Mention files and Tracker items. * Attach images and other supported context. Drag the launcher by its title bar when it covers something you need to read. Sending the prompt starts the session in the background, closes and resets the launcher, and keeps you in the current mode. Open Agent mode or the attention list whenever you want to follow the new session. Starting a session from a document or Tracker item can prefill the relevant reference so the agent receives the context you launched from. ### Change Models and Thinking from Chat Press **Cmd/Ctrl+Shift+M** while the chat input is focused to open the model picker without reaching for the mouse. Type to search by the model's display name or model ID, then use the arrow keys and Enter to select it. The model selection belongs to the session. Changing it affects later turns without changing the model used by other sessions. Supported Claude Agent models also show **Extended: On** or **Extended: Off**: * **Extended: On** keeps the model's extended thinking behavior. * **Extended: Off** can reduce latency and token use when the task does not need as much reasoning. The control appears only for models and providers that support it. Extended thinking stays on by default. ### Review the Context Sent with a Prompt When you select content in an editor, the chat composer shows that selection as a removable chip before you send the prompt. Selection chips can represent: * Selected text in documents and code files * Spreadsheet cells * A selected mockup screen * One or more Excalidraw shapes * Selection types contributed by other editors Remove a chip when you do not want that selection sent to the model. Removing it changes only the pending prompt; it does not change or deselect the content in the editor. ### Contextual Tips Empty sessions and other core surfaces can show contextual tips instead of a blank state. These cards point you toward features that fit what you are doing right now. Common examples include: * Opening **Tracker Mode** when your work is spreading across many sessions * Discovering worktree-specific flows and search shortcuts * Learning keyboard shortcuts and launchers without leaving the current screen * Finding shared docs, theme controls, feedback entry points, and mobile pairing Tips often include a direct action like **Open Tracker**, plus **Next** and **All tips** controls so you can browse more guidance without interrupting your current work. ### Session Kanban Board Open the Session Kanban with **Cmd+Shift+K** to see all sessions in the workspace grouped by phase (Backlog, Planning, Implementing, Validating, Complete). #### Live peek transcripts Hover any session card and the transcript opens in a peek popover. If the session is running, the transcript streams in live as the agent works, so you can keep an eye on what it is doing without opening the session itself. The peek shows the recent context of long turns, not just the trailing tokens. * Hover to open, move away to dismiss * Streaming sessions update token by token in the peek * Works for sessions, workstreams, and child sessions inside a workstream ### Self-Pacing Session Wakeups Agents can schedule themselves to wake up later and continue working — useful for long-running tasks where the agent needs to check back on something after a delay rather than running continuously. * The agent picks the wakeup time itself (anywhere from 60 seconds to 7 days out) * Wakeups persist across app restarts, but only fire while Nimbalyst is running * When a wakeup fires, you get an OS notification — clicking it focuses the workspace and opens the session * A wakeup banner appears in the session header with **Cancel** and **Fire now** controls; sessions with a pending wakeup show a clock icon in the session list If the workspace window is closed when the wakeup is due, the wakeup waits and re-fires the next time you open that workspace. ### Agent Attention List The Agent navigation icon shows a badge when sessions are running, unread, or waiting for you.
Agent navigation badge and attention list showing sessions awaiting input

The attention list groups sessions by what they need, so a blocked agent does not disappear into session history.

Open the icon to see sessions grouped as: * **Awaiting input** — the agent is blocked on a question, approval, or permission. * **Running** — the agent is actively working. * **Unread** — the session has new activity you have not opened. Select a session to open it. **Mark all read** clears unread state, but it does not approve requests or answer sessions that are awaiting input. Agents can also send a local system notification when a workflow needs your attention and you have stepped away. Clicking the notification returns you to the relevant workspace and session. Notification availability follows your operating-system and Nimbalyst notification settings. ### System Tray Icon The system tray menu shows session status at a glance: * See which sessions are running, completed, or need attention * Click any session to navigate directly to it * The dock and Agent navigation badges show a count for sessions that need your attention ### Window State Persistence The Agentic Coding Window remembers: * Window size and position * Active tab in sidebar * Session ID * Developer tools state (if open) * Transcript scroll position State is saved per workspace. # AI Usage Report See which models and tools your AI sessions use, compare activity across projects over time, and find Nimbalyst tools you have not tried yet. The AI Usage Report shows how you use models and tools across Nimbalyst. Use it to understand activity over time, compare projects, and discover tools that are available but not yet part of your workflow. Open it from **Window > AI Usage Report**. If you are deciding between API keys and a Claude or Codex subscription, see [Claude Code and Codex subscriptions](https://nimbalyst.com/claude-code-codex-subscriptions/). ## Overview The **Overview** tab combines: * Session and token totals * An activity heatmap * Historical usage over time * Per-project activity Use the project filter when you want to separate one workspace from your all-project totals. ## Tool Usage Open the **Tools** tab to see calls made to: * Built-in agent tools, such as reading files, searching, editing, and running commands * MCP tools * Tools contributed by Nimbalyst extensions The report includes: * Your most-used tools * Successful and failed call counts * Built-in versus MCP and extension usage * Calls over time * Usage by provider * Usage by project Tool counts describe calls, not time spent or tokens consumed by a tool. ## Backfill Earlier Sessions New tool calls are recorded automatically. Click **Backfill history** to populate the report from compatible Claude Agent and Codex sessions created before tool tracking was enabled. Backfill reads your stored Nimbalyst session history. It does not rerun the sessions or call the tools again. ## Where the Data Lives The report is generated from usage data stored locally by Nimbalyst. Tool tracking records the tool identity, project, provider, count, and error count; it does not turn tool inputs or outputs into a public activity feed. The AI Usage Report is separate from provider billing dashboards. For authoritative subscription limits, API charges, or provider-specific usage windows, use the dashboard provided by the model provider. # View Files in Agent Mode View and edit project files directly inside an AI session in Nimbalyst, without switching back to Files mode to check what the agent did. ### Interacting with Files in Agents Mode View and edit files directly within your AI session without switching to Files mode.
**How to use:** * When a session, workstream, or worktree edits a file, it appears on the right panel * Open multiple files in tabs, resize or hide the files panel as needed. * Edit files directly while collaborating with your coding agent. * Right-click any file to open it in Files mode if you prefer the full editor experience
Seeing agent output as rendered files rather than terminal text is the core idea behind the [visual editor for Claude Code](https://nimbalyst.com/visual-editor-for-claude-code/). **Benefits:** * Stay focused in your AI workflow without context switching * Make quick edits alongside AI suggestions * Full editing capabilities without leaving Agent Mode ### Collapsing Sections Click any section header (Edited, Referenced, Read) to collapse or expand it. This helps focus on what matters when there are many files. ### Tips * **Long filenames** are truncated. Hover to see the full relative path from your workspace. * **Multiple edits** to the same file are aggregated - you'll see the total lines added/removed across all changes. * **Git status updates** automatically when you switch back to Nimbalyst from another app. * **Empty state**: If no files have been touched yet, you'll see "No file interactions yet." # Workstreams Workstreams group related AI sessions that touch the same files or topic, so you can branch an approach without losing the earlier thread. Workstreams help you organize related AI sessions that work on the same set of files and/or are about the same topic. ### **How to use:** Start any AI session as usual. When you need to branch your work or try a different approach, click the **+** button to add a new session tab.
Your single session automatically converts into a workstream containing multiple sessions.
The right panel shows all files modified across all sessions in your workstream, giving you a unified view of changes. Running several agents against the same project at once is covered on the [agent orchestration page](https://nimbalyst.com/features/agent-orchestration/) and in [parallel Claude Code sessions](https://nimbalyst.com/parallel-claude-code-sessions/).
Clicking on that file, you can open the files editor in the Agents mode
Right clicking on the file, you can still open it in Files mode
### **Benefits:** * Keep related work organized without losing context * Easily compare different approaches to the same problem * Track all file changes across multiple sessions in one place ### Spawning sibling sessions with `/launch-new-session` You can ask the agent to spin off another session for a side task without leaving the current one. Run `/launch-new-session` in any session and describe the side task. The agent calls the `spawn_session` MCP tool and a new session is created. By default the new session is a **sibling**: it joins the caller's workstream, so files-edited, open tabs, and the workstream overview are shared. The original session stays focused on its own thread while the sibling runs in parallel. If you want the side task fully separated, ask for an isolated session ("isolated bug fix", "fix and commit separately"). The agent passes `isolated: true` to `spawn_session` and the new session is top-level instead of joining the workstream. * **Sibling (default)**: shares workstream context with the caller. Good for parallel exploration of related work. * **Isolated**: independent top-level session with no parent. Good for unrelated fixes the agent should commit on its own. * **Worktree**: combine either mode with a worktree to put the new session on its own git branch. Sibling and worktree are independent options. You can also launch sibling sessions from the composer's Actions dropdown by configuring an Action with `launch: new-session`. See [AI Actions](/session-management/ai-actions) for the config keys. # Import Claude Code Sessions Import sessions from the Claude Code CLI into Nimbalyst so you can browse, search, resume, and continue past terminal conversations visually. Bring sessions you ran in the Claude Code CLI into Nimbalyst so you can browse, search, resume, and continue them in the Agent Window. Nimbalyst runs on top of the Claude Code you already have installed, so imported CLI sessions keep working the same way. See the [Claude Code GUI page](https://nimbalyst.com/claude-code-gui/). ### How to use 1. Open **File → Import Claude Code Sessions...**
2. The Import dialog scans your Claude Code session storage for sessions tied to the current workspace and shows totals at the top: * **Total** sessions found * **New** sessions not yet imported * **Updates** to sessions you've already imported (Claude Code added more turns since last import) * **In Sync** sessions that already match what's in Nimbalyst
3. Search by title, expand the project group, and check the sessions you want to import. 4. Click **Import n Sessions**. Imported sessions show up in the Agent Window session list and the kanban board. You can resume them, link them to tracker items, or open them in a worktree just like any other Nimbalyst session. ### What gets imported * Full conversation history including subagent turns * Extended-thinking blocks * Long tool results (inlined so they show up in the transcript) * Follow-up prompts within a turn ### Workspace matching Nimbalyst matches Claude Code's on-disk session directories to your current workspace. Workspaces with spaces, apostrophes, or accented characters in their path are handled correctly. If the workspace-filtered scan finds nothing, the dialog falls back to showing all available Claude Code sessions and tells you the scope was broadened, so you can still import sessions that Claude Code stored under a different resolved path or sibling worktree. ### Tips * Import is idempotent. Running it again on a session that already matches Nimbalyst's copy is a no-op (it shows up under **In Sync**). * "Has Updates" means Claude Code added more turns to a session since you last imported it. Re-checking and re-importing brings the new turns over. * Import works with sessions from Claude Code 2.1.x and later. # / Commands and Skills Use Claude Code and Codex slash commands, custom commands, and skills in Nimbalyst, and learn how actions, commands, and skills differ. Nimbalyst supports Claude Code and Codex out-of-the-box slash commands, custom commands, and skills. ### Actions vs Commands vs Skills **Actions** are reusable prompt presets defined in a single `nimbalyst-local/ai-actions.md` file and surfaced as a dropdown in the composer. Pick one and the prompt drops into your draft. Best for "I copy-paste this prompt all the time." Typical examples include reviewing changed files, planning an implementation, drafting release notes, and inspecting the current editor. See [AI Actions](/session-management/ai-actions). **Commands** are simple markdown files that provide a prompt template. They live in `.claude/commands/` as markdown files. When you type `/command-name`, the contents of that file are sent as a prompt to the agent. **Skills** are richer integrations that can include instructions, workflows, and tool usage patterns. Nimbalyst ships with built-in skills (like `/commit`), plugins can provide skills, and you can create your own. Skills can define how the agent should behave for specific workflows — for example, a skill that tells the agent how to manage your tracker state when working on blog posts. ### Using Slash Commands and Skills Type `/` in the AI chat to see all available commands and skills. The typeahead shows all skills — user-created, plugin, and extension skills — so you can quickly find what you need. Plugin skills are namespaced consistently with commands so the inserted command matches what the agent SDK routes. For example: * `/excalidraw:excalidraw` * `/planning:design` * `/feedback:bug-report` Skills and commands written for one agent run in the other — workflow discovery is unified across Claude Code and Codex. Ready-made skills you can drop into a project are listed on the [Nimbalyst skills page](https://nimbalyst.com/skills/), and the [commands and skills feature page](https://nimbalyst.com/features/commands-and-skills/) covers how they surface in the composer. ### @ Mentions Type `@` in the AI chat to reference files and folders. The picker opens immediately, with suggestions sorted by **recency** so the files you've most recently opened or edited are at the top. Keep typing to filter, or scroll to find older files. You can mention individual files or entire directories (shown with a folder icon). Mentioning a file gives the agent direct context about which files you want it to work with, instead of relying on the agent to search for them. In markdown documents, `@` is also the fastest way to embed supported custom-editor files. If the inserted file link sits by itself on its own line, Nimbalyst upgrades it into a live inline embed in WYSIWYG view. This is useful for mockups, Excalidraw files, data models, CSV files, and other custom-editor content you want to keep inside a spec or plan. ### @@ Session Mentions Type `@@` in the AI chat to reference another session. The picker shows your sessions in recency order so the conversation you were just in is one keystroke away. Mentioning a session pulls its context into your current conversation. It's useful when you want the agent to build on prior work, reuse research from an earlier session, or understand decisions made elsewhere — without having to re-explain everything. ### Built-in Example **`/commit`** - Creates a git commit: 1. Runs `git status` and `git diff` 2. Reviews recent commits for style 3. Drafts a commit message with type prefix (`feat:`, `fix:`, etc.) 4. Stages and commits **`/session-cleanup`** - Tidies your Sessions board: 1. Audits your sessions by phase and tags 2. Suggests phase corrections (for example, moving committed work out of planning) 3. Flags old completed sessions as archive candidates 4. Asks for your approval before changing anything ### Create Your Own Commands Custom commands live in `.claude/commands/` as markdown files. Go to the `.claude` directory in your project, then the `commands` folder. Edit or add your own commands there. You can also go to Settings (click the Gear on the bottom left), then Project Settings to add commands. ### Create Your Own Skills Skills are a powerful way to teach the agent how to handle recurring workflows. For example, you can create a skill that integrates with the tracker system — telling the agent to update tracker state whenever you're working on certain types of tasks. See [project-wide-plan-task-management.md](broken://pages/SR3dgfjEnZdIBTuLRmdE) for an example. # AI Actions AI Actions are reusable prompt presets that show up in the Nimbalyst composer. Define them in one workspace file so they version and share. AI Actions are reusable prompt presets that show up as a dropdown in the AI composer. Pick one and the prompt drops into your draft, ready to send or edit. They live in a single file in your workspace, so they're easy to version, share, and edit.
The Actions dropdown open in the AI composer, listing seed entries like Review changed files, Plan implementation, and Draft release notes

The Actions dropdown open in the composer.

### When to use Actions Actions are the lightest-weight way to reuse a prompt: * **Action**: a prompt you reuse often, defined in one file, picked from a dropdown. * **Command** (`/`): a slash command in `.claude/commands/.md`. Runs in either Claude Code or Codex. * **Skill**: a richer integration with workflow logic and tool usage patterns. If you're copy-pasting the same prompt more than twice, turn it into an Action. See the [commands and skills feature page](https://nimbalyst.com/features/commands-and-skills/) for how Actions, Commands, and Skills differ in practice. Starter Actions often include patterns like: * **Review Changed Files** * **Plan Implementation** * **Draft Release Notes** * **Inspect Current Editor** ### Where Actions live Actions are defined in `nimbalyst-local/ai-actions.md` in your workspace. The first time you open the Actions dropdown in a workspace without that file, you'll see a "Create ai-actions.md with examples" button that seeds it with a few starter entries. ### File format Each `## Heading` is one action. Everything between that heading and the next `##` is the prompt body that gets inserted into the composer. ```markdown # AI Action Prompts ## Review changed files /review changed files in this session and call out regression risk in the affected modules. ## Plan implementation Look at the active issue and the open editor. Produce a structured plan that: - breaks the work into 3-5 phases - identifies the files I'll need to touch - flags any cross-cutting concerns When you're done, ask me which phase to start with. ## Inspect current editor Read the file that's currently open and tell me what you'd change. Be specific: - 3 concrete improvements - 1 thing that's already good and shouldn't change ``` ### Launching a new sibling session from an Action By default an Action drops its prompt into the current composer. You can also configure an Action to spin up a brand-new sibling session and submit the prompt there, so the current session stays focused on what it was already doing. See [Workstreams](/session-management/workstreams) for how sibling sessions appear in the sidebar. Add a fenced YAML config block right under the heading: ````markdown ## Investigate in a new session ```yaml launch: new-session model: opus foreground: false autoSubmit: true ``` Spin up a sibling investigation. Read the open file and the linked tracker item. Produce a one-page summary of what the change should do, what it must not break, and three risks to watch for. Reply in the sibling session when done. ```` Supported config keys: | Key | Values | What it does | | ------------ | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `launch` | `same-session` (default), `new-session` | Whether the Action drops its prompt into the current composer or starts a sibling session. | | `model` | a model id (e.g. `opus`, `sonnet`, `haiku`, a specific provider model) | Model to use when `launch: new-session`. Defaults to the current session's model. | | `foreground` | `true` (default), `false` | When `false`, the sibling session opens in the background so you stay focused on the current one. | | `autoSubmit` | `true` (default), `false` | When `false`, the prompt is dropped into the sibling's composer but not sent. Useful when you want to tweak it before submitting. | Actions with `launch: new-session` show a small "open in new" icon in the dropdown so you can tell at a glance which ones will spin up a sibling. ### Editing your Actions Click **Edit actions…** at the bottom of the Actions dropdown to jump straight to `nimbalyst-local/ai-actions.md`. Save the file and the dropdown updates the next time you open it. No restart needed. ### Sharing Actions with a team `nimbalyst-local/` is part of your workspace, so committing `ai-actions.md` to git ships the whole team's Action set with the repo. Pair this with `.claude/commands/` and your skills/CLAUDE.md to make a one-clone-and-go agent environment. # Interactive Prompts (PromptForUserInput) PromptForUserInput is a built-in Nimbalyst MCP tool that lets your agent collect several answers at once through one structured widget. `PromptForUserInput` is a built-in Nimbalyst MCP tool that lets your agent collect several inputs from you at once through a single structured widget in the transcript. Instead of asking three narrow questions back-to-back, the agent surfaces one prompt with multiple fields and waits for you to submit. Use it any time you want to drive a decision visually: ranking, picking from a list, confirming, or editing a draft. ### When to use it Ask for an interactive prompt when you want to: * Prioritize a list by dragging items into order (e.g. "help me prioritize my blogs") * Approve or reject recommended changes in bulk (e.g. "review these recommended changes to my tracker, keep some, drop others") * Edit a short draft inline before the agent acts on it (e.g. tweak a tweet, commit message, or summary) * Confirm a destructive or important action * Collect a few related answers in one shot instead of a chat back-and-forth More on how Nimbalyst passes structured input back to your agent is on the [agent integration page](https://nimbalyst.com/features/agent-integration/). ### How to trigger it from chat You usually do not need to name the tool. Just describe the interaction you want: * "Show me a prioritization widget for these blog posts so I can drag them into the order I want to publish." * "Give me a checklist of the changes you recommend to my tracker so I can approve the ones I like." * "Draft a tweet thread for this release and let me edit it before posting." * "Ask me to confirm before you run the migration." If your agent ignores the hint or falls back to plain chat, you can be explicit: "Use the `PromptForUserInput` tool." ### Field types A single prompt can mix any of these five fields: * **multiSelect** — pick any subset from a list of options. Good for "approve these, skip these". * **singleSelect** — pick exactly one option. Good for choosing a branch, mode, or template. * **reorder** — drag items into the order you want. Supports per-item removal with a configurable `minItems` floor. Good for prioritization. * **editText** — inline rich-text editor for short drafts. Reuses the same Lexical editor Nimbalyst uses elsewhere in the transcript and on iOS. * **confirm** — yes/no confirmation with custom labels. ### Examples #### Prioritize blog posts (reorder) > **You:** I have five blog drafts in `/blog/drafts/`. Show me a prioritization widget so I can drag them into the order I want to publish, and let me drop any I want to kill. The agent returns a single prompt with a `reorder` field listing the five drafts. You drag them into order, click the trash icon on the ones you want to drop, and submit. The agent then continues with the ordered, filtered list. #### Approve tracker changes (multiSelect) > **You:** Look at my open tracker items and recommend changes. Ask me which ones to apply. The agent surveys your tracker, then surfaces a `multiSelect` prompt with each recommended change as an option ("Close issue #142 as duplicate", "Re-label #156 as bug", and so on). You check the ones you want, leave the others, and submit. The agent applies only the approved changes. #### Draft and edit a tweet (editText + confirm) > **You:** Draft a tweet announcing the 0.60.1 release and let me edit it before you post anything. The agent surfaces one prompt with two fields: an `editText` field pre-filled with the draft, and a `confirm` field asking whether to post it. You polish the wording in place, flip confirm to yes, and submit. ### Voice mode behavior In Voice Mode, the agent decides per-prompt whether voice can handle the interaction or whether to defer to the on-screen widget. Long drafts and reorders with more than six items default to the screen, since reading them aloud is not useful. Short single-select and confirm prompts stay in voice. ### For extension and agent developers `PromptForUserInput` is exposed as a standard MCP tool. Any agent that speaks MCP (Claude Code, Codex, OpenCode, GitHub Copilot, your own extension) can call it. The schema is a flat type-discriminator object, not `oneOf`. Each field carries a `type` ("multiSelect", "singleSelect", "reorder", "editText", or "confirm") plus the options or initial value for that type. The response comes back as a JSON object keyed by field id. A minimal call looks like this: ```json { "title": "Prioritize blog drafts", "fields": [ { "id": "order", "type": "reorder", "label": "Drag into publish order", "items": [ { "id": "a", "label": "Why we built Workstreams" }, { "id": "b", "label": "Voice Mode tour" }, { "id": "c", "label": "0.60.1 release notes" } ], "minItems": 1 }, { "id": "confirm", "type": "confirm", "label": "Lock in this order?" } ] } ``` Notes worth knowing if you are integrating: * The wire name is `PromptForUserInput`, not `RequestUserInput`. This avoids collision with the Codex CLI's built-in `request_user_input` tool, which is gated to Plan mode. * Responses persist as a synthetic `nimbalyst_tool_result` on settle, so the canonical `tool_call` event still picks up the answer even if the SDK subprocess exits before flushing its own `tool_result` block. * iOS round-trips the response through the existing transcript bridge, so the same prompt works on desktop and mobile without separate code paths. * iOS reorder uses a 200ms long-press to start a drag, with the selection callout suppressed, so the gesture does not get hijacked into text selection. ### Related * [MCP](/setup-nimbalyst/mcp) — overview of Nimbalyst's built-in MCP tools, including `AskUserQuestion` for simpler multiple-choice prompts. * [Agent Window & Session Management](/session-management/agent-window-and-session-management) — where these prompts appear in the transcript. # Automations Schedule recurring AI tasks in Nimbalyst. Automations run on a timer from a markdown file to produce standups, weekly reports, and reviews. Automations let you schedule recurring AI-powered tasks that run on a timer inside Nimbalyst. Use them to generate daily standups, weekly reports, periodic code reviews, or any repeating task you'd otherwise do manually. Each automation is a markdown file in `nimbalyst-local/automations/`. The frontmatter defines the schedule and output settings, and the markdown body is the prompt that runs on each execution. The [automations feature page](https://nimbalyst.com/features/automations/) covers scheduling patterns teams use, such as standups and recurring reviews.
## Creating an Automation ### Quick: Use `/automation` Type `/automation` followed by a description: ``` /automation summarize my git commits every weekday morning ``` Nimbalyst creates the automation file with the right schedule and prompt, sets it to disabled so you can review it first, then tells you to open the file and enable it. ### Manual: Create the File Create a `.md` file in `nimbalyst-local/automations/` with this format: ```markdown --- automationStatus: id: standup-summary title: Daily Standup Summary enabled: false schedule: type: weekly days: [mon, tue, wed, thu, fri] time: "09:25" output: mode: new-file location: nimbalyst-local/automations/standup-summary/ fileNameTemplate: "{{date}}-standup.md" runCount: 0 --- # Daily Standup Summary Review the git log and recent file changes in this workspace since the previous business day. Summarize: 1. **What was accomplished** - List completed work based on commits and file changes 2. **What's in progress** - Identify files with uncommitted changes or recent branches 3. **Any blockers** - Note any error logs, failing tests, or stale branches Format as a concise standup update suitable for sharing with the team. ``` ## Document Header Controls When you open an automation file, a header bar appears at the top of the editor with: * **Enable/Disable toggle** -- turn the automation on or off * **Schedule display** -- shows the schedule in plain language (e.g., "Weekdays at 9:25 AM") * **Last run info** -- when it last ran and whether it succeeded * **Run Now button** -- trigger the automation immediately without waiting for the next scheduled time ## Schedule Types ### Daily Runs once per day at the specified time. ```yaml schedule: type: daily time: "09:00" ``` ### Weekly Runs on specific days of the week at the specified time. Valid days: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`. ```yaml schedule: type: weekly days: [mon, wed, fri] time: "14:00" ``` ### Interval Runs every N minutes while Nimbalyst is open. ```yaml schedule: type: interval intervalMinutes: 60 ``` ## Output Modes Each run's output is written to files. You control how with the `output` block: | Mode | Behavior | | ------------ | ----------------------------------------------------------------------------------------------- | | **new-file** | Creates a new file per run. Use `fileNameTemplate` with `{{date}}` and `{{time}}` placeholders. | | **append** | Appends each run's output to a single `output.md` file with date headers. | | **replace** | Overwrites a single `output.md` file each run -- only the latest result is kept. | **Example output config:** ```yaml output: mode: new-file location: nimbalyst-local/automations/standup-summary/ fileNameTemplate: "{{date}}-output.md" ``` ## AI Provider By default, automations run using Claude Code. You can optionally specify a different provider or model: ```yaml provider: claude-code # "claude-code", "claude", or "openai" model: claude-code:sonnet # optional: specific model ID ``` ## Execution History Each automation tracks its run history in a `history.json` file inside the output directory. This includes timestamps, duration, success/error status, and links to the AI session that produced the output. You can also ask the agent to check history: ``` What's the run history for my standup-summary automation? ``` The agent uses the `automations.history` tool to retrieve this. ## Frontmatter Fields Reference | Field | Required | Description | | -------------------------- | ---------------- | ---------------------------------------------------- | | `id` | Yes | Unique kebab-case identifier | | `title` | Yes | Human-readable name | | `enabled` | Yes | `true` or `false` | | `schedule.type` | Yes | `daily`, `weekly`, or `interval` | | `schedule.time` | For daily/weekly | Time in 24h format (`"HH:MM"`) | | `schedule.days` | For weekly | Array of day abbreviations | | `schedule.intervalMinutes` | For interval | Number of minutes between runs | | `output.mode` | Yes | `new-file`, `append`, or `replace` | | `output.location` | Yes | Path for output files (relative to workspace) | | `output.fileNameTemplate` | For new-file | Filename with `{{date}}` and `{{time}}` placeholders | | `provider` | No | AI provider to use | | `model` | No | Specific model ID | | `runCount` | Auto | Incremented on each run | | `lastRun` | Auto | ISO timestamp of last execution | | `lastRunStatus` | Auto | `success` or `error` | | `nextRun` | Auto | ISO timestamp of next scheduled run | ## Example: Weekly Project Status Report ```markdown --- automationStatus: id: weekly-status title: Weekly Project Status enabled: true schedule: type: weekly days: [fri] time: "16:00" output: mode: new-file location: nimbalyst-local/automations/weekly-status/ fileNameTemplate: "{{date}}-status.md" runCount: 0 --- # Weekly Project Status Generate a weekly status report for this project: 1. **Summary** - One paragraph overview of the week's progress 2. **Completed** - List all merged PRs and completed features this week (check git log) 3. **In Progress** - List open branches and their status 4. **Metrics** - Count commits, files changed, and lines added/removed 5. **Next Week** - Based on open branches and TODOs, suggest priorities Format as a clean markdown report. ``` ##
## Tips * **Start disabled**: New automations default to `enabled: false`. Review the prompt and schedule before enabling. * **Edit anytime**: Just edit the markdown file. The extension picks up changes within 30 seconds. * **Run Now to test**: Use the "Run Now" button in the document header to test your automation before relying on the schedule. * **Check output**: Outputs appear in the `location` directory. Open them from the file tree. * **Automations only run while Nimbalyst is open**: If Nimbalyst is closed at the scheduled time, the automation won't fire retroactively. # Share Link to a Session Create a public share link for any AI session so teammates can read the whole transcript in a browser without installing Nimbalyst first. Share any AI or markdown file with a public link.
**How to use:** 1. Right-click on a session in the session list 2. Select **Share Link** 3. A link is copied to your clipboard 4. Paste it anywhere -- Slack, email, X, a doc
**Important! Security and Safety.** * Anyone with the link can view the session or file. Do not share sessions containing sensitive information. * Shared content is hosted on Cloudflare R2. There is no password protection. * The content is encrypted on Cloudflare so Nimbalyst, Inc has no ability to read the content Shared links are read-only. For real collaboration on the same session context, see [Nimbalyst for Teams](https://nimbalyst.com/teams/). # Tracker Overview Nimbalyst has a built-in issue tracker that keeps bugs, features, tasks, and plans in your project files, next to your docs and AI sessions. Nimbalyst's tracker is a schema-driven system for managing work items directly alongside your AI sessions and project files. It supports multiple item types out of the box, each with its own status workflow, fields, and icon -- and you can define custom types to fit your project's needs. The [task management feature page](https://nimbalyst.com/features/task-management/) shows the tracker in context alongside docs and sessions, and [kanban for Claude Code](https://nimbalyst.com/kanban-for-claude-code/) covers the board view for agent work. Tracker types can be local, hybrid, or shared with a team. Shared items support real-time field and rich-body editing, team comments and activity, and the same kanban, list, tag, relationship, agent, and session-linking workflows. See [Collaborative Trackers](/team-collaboration/trackers).
## Why work in trackers instead of folders Task trackers and document tools are usually separate, which forces a choice. Either a task is a one-line ticket and the actual thinking lives in a document somewhere else, or you write the document and nothing tracks its state. Nimbalyst removes the split. **Every tracker item contains a full document**, so the work and the record of the work are the same object.
A tracker item open beside the item list, its Content section holding a full document with headings, prose, an embedded mockup, and a comment thread

The item's Content section is a complete document, not a description field. Headings, embeds, and comments all live inside the item.

That Content section is the same editor you get in any markdown file. Write the spec, the repro steps, the rollout plan. Embed a mockup, an Excalidraw diagram, a data model, a spreadsheet. Add checklists, tables, and code blocks. Reference other tracker items as live chips and other files as live embeds. Leave anchored comments on a specific passage. ### Your file tree stays clean This is the practical payoff. Without it, every piece of work sheds files: a spec, a scratch note, a diagram, a follow-up list, each needing a folder and a name and a decision about where it belongs. Six months later nobody remembers whether the auth rework notes are under `docs/`, `planning/`, or `archive/2026/`. When the writing lives inside the item, none of that reaches your file tree. The project keeps the files that are genuinely project artifacts, and the thinking around each piece of work stays attached to that piece of work. ### Let the flow carry the work, then archive it The intended rhythm is to work through the tracker rather than to file things: 1. Create the item when the work appears, from a chat, a `/track` command, or the **+New** button. 2. Write and think inside it as the work develops, embedding whatever the work needs. 3. Move it across statuses as it progresses, and link the sessions, files, and pull requests it touches. 4. When it is done, mark it done. When it is no longer live, archive it. Archiving is not deleting. An archived item keeps its body, its comments, its activity log, and every link it had to sessions, files, and other items. It does get out of your way. Archived items are hidden from the board, from lists, from quick-open search, and from the tracker reference picker. To see them, add an **Archived** filter in the tracker filter box, or use a saved view that includes them. `nim tracker unarchive NIM-123` brings one back to active. So finished work leaves your board without leaving your project. It is out of sight by default and retrievable on purpose, which is the thing folder-based organizing never quite manages. ### Folders still work, and trackers point at them None of this replaces your file tree. Code, real documentation, and anything that belongs in the repository should stay a file under version control. The two systems connect in both directions. A tracker item can link files for reference and can embed them live in its body. A markdown file can carry `trackerStatus` frontmatter and become an item itself, or contain inline `#type[...]` tags and tracker reference chips that show live status beside the prose. So a tracker item can point at the spec in `docs/`, and that spec can point back. The rule of thumb: if it is a durable artifact of the project, make it a file. If it is the work itself, and it has a beginning, a middle, and an end, make it a tracker item and write inside it. ### Expand an item to full width When the body grows past a comfortable size for the side panel, open **Expanded tracker content** for a full-width editing surface, with the item list still on the left and a chat about the item on the right.
Expanded tracker content view, showing a full-width item body with a checklist, a slash-command insert menu, and an embedded Excalidraw diagram, with the item list on the left and a Chat about this item panel on the right

Expanded view gives the item body the full window, with the item list on the left and a chat scoped to this item on the right.

Everything behaves as it does in the panel, with more room: slash commands for diagrams, tables, checklists, code blocks, collapsible sections, and column layouts. **Back to tracker** returns you to the board. ### What You Can Track Nimbalyst includes six built-in item types: * **Bug** -- Defects and issues to fix * **Task** -- General work items and to-dos * **Feature** -- New capabilities and enhancements * **Idea** -- Early-stage ideas before they become work * **Decision** -- Architectural and product decisions with context * **Plan** -- Larger initiatives with progress tracking Each type has its own statuses, fields, and color-coded icon. You can also define custom tracker types using YAML configuration files. ### How Items Get Created Items can come from multiple sources: * Ask the AI agent during a chat session * Use the `/track` command for quick creation * Write inline `#type[...]` tags in any markdown file * Add `trackerStatus` YAML frontmatter to a markdown document * Click the **+New** button in the tracker panel ### Where are Items Stored Items are stored in one of three places: * In the Database as a tracked item * In a markdown file if you created the tracked item using # inline * As a markdown file if that trackerstatus is added to a markdown file Items in hybrid or shared tracker types can also sync through the team's tracker space. Sharing is explicit for hybrid items; a shared tracker type shares all of its items by design. ### Learn More * [Item Types and Fields](/task-management/item-types-and-fields) -- Built-in types, statuses, and field definitions * [Kanban and List Views](/task-management/kanban-and-list) -- Board mechanics, filtering, and drag-and-drop * [Item Detail](/task-management/item-detail) -- Editing fields, comments, and activity logs * [Creating Items](/task-management/creating-items) -- All four creation paths with examples * [AI Integration](/task-management/ai-integration) -- How agents create, update, and query items * [Commits and Sessions](/task-management/commits-and-sessions) -- Linking items to git history and conversations * [Custom Tracker Types](/task-management/custom-tracker-types) -- Define your own types with YAML * [Local Config](/task-management/local-config) -- Project-level settings and file organization # Item Types and Fields Nimbalyst ships six built-in tracker item types, each with its own status workflow, fields, and icon. Learn what each type is meant to track. Nimbalyst includes six built-in tracker types. Each has its own status workflow, fields, and color-coded icon. The type determines which columns appear on the kanban board and which fields are available in the detail view. ### Bug For tracking defects and issues. * **Icon:** Bug report (red) * **Statuses:** To Do, In Progress, In Review, Done * **Fields:** Title, Status, Priority, Owner, Description ### Task For general work items and to-dos. * **Icon:** Task (blue) * **Statuses:** To Do, In Progress, In Review, Done * **Fields:** Title, Status, Priority, Owner, Description ### Feature For new capabilities and enhancements. * **Icon:** Rocket (green) * **Statuses:** To Do, In Progress, In Review, Done * **Fields:** Title, Status, Priority, Owner, Description, Release Version, Release Notes ### Idea For capturing ideas before they become work items. * **Icon:** Lightbulb (yellow) * **Statuses:** New, Considering, Accepted, Rejected * **Fields:** Title, Status ### Decision For recording architectural and product decisions with context. * **Icon:** Gavel (purple) * **Statuses:** To Do, In Progress, Decided, Implemented * **Fields:** Title, Status, Chosen (the decision made), Priority, Owner, Stakeholders, Tags ### Plan Nimbalyst supports two approaches to planning: * **Quick plans (via /plan for Claude Code):** Uses Claude Code's default planning model — a temporary plan is created, given a name, used for implementation, and then discarded. These plans are not integrated with the tracker system. * **Long-lived plans:** Write a thoughtful plan in markdown that outlines goals, strategy, and features. Update it with your architecture and implementation overview. Keep this as a long-lived document. To work this way, create a custom `/` command or skill (e.g., `/spec`) and have it integrate with the tracker system. This approach keeps your plans visible, versioned, and connected to your task tracking. For larger initiatives with progress tracking. * **Icon:** Flag (blue) * **Statuses:** Draft, Ready for Development, In Development, In Review, Completed, Rejected, Blocked * **Fields:** Title, Status, Plan Type, Priority, Progress (0-100%), Owner, Stakeholders, Tags, Start Date * **Plan Types:** System Design, Feature, Bug Fix, Refactor, Documentation, Research ### Priority Levels All item types that support priority use the same four-level scale: | Priority | Use For | | -------- | --------------------------------------------- | | Critical | Blocking issues that need immediate attention | | High | Important work that should be done soon | | Medium | Standard priority (default) | | Low | Nice-to-have or can wait | # Views: Kanban, List, and Tag Board Switch between kanban board, list, and tag board views in the Nimbalyst tracker, then save any filter and grouping as a named view to reuse. The tracker gives you several ways to look at your items: a kanban board for visual status management, a list view for dense sortable data, and a tag board for organizing by tag. Save any arrangement of filters and grouping as a named view to return to later. See [kanban for Claude Code](https://nimbalyst.com/kanban-for-claude-code/) for how teams run agent work off a board. ### Kanban Board The kanban board organizes items into columns by status. Each item type has its own status workflow, so the columns change depending on which type you are viewing. For custom types, the columns follow the order of the status options you defined in the type's schema.
### Moving Items * **Drag between columns** to change an item's status. Dragging a task from "To Do" to "In Progress" updates the item immediately. * **Drag within a column** to reorder items. Manual ordering lets you prioritize work visually without changing status. ### Card Display Each card on the board shows: * Type icon (color-coded by item type) * Item title * Priority badge (if set) * Owner avatar (if assigned) * Type tag label
### Detailed View * Click any card to open its detail view.
### Selection * **Click** a card to select it and open the detail panel. * **Shift-click** to select a range of cards. * **Click a column header** to select all cards in that column. * **Right-click a column header** to open a context menu with bulk actions. ### Filtering Filter chips and controls sit in the Tracker sidebar: * **"Mine"** -- Show only items assigned to you. * **"Unassigned"** -- Show only items with no owner. * **High Priority** -- Show items with High or Critical priority. * **Favorites** -- Show items you have starred. * **Recently Viewed** -- Return to items you opened recently, ordered by your most recent view. * **Edited by Others** -- Show the latest items whose most recent known editor is someone other than you. * **Recent** -- Show the 50 most recently updated items. * **Archived** -- Switch from active items to archived items. * **Type filter** -- Select which item type to display (Bug, Task, Feature, etc.). * **Text search** -- Search across titles, descriptions, and item IDs.
Tracker sidebar showing Favorites, Recently Viewed, Edited by Others, Recent, and Archived filters

Combine personal filters, type folders, saved views, search, and board controls to focus on the work that matters now.

Click the star on a Tracker row or card to add or remove it from Favorites. Favorites and recently viewed state belong to you; starring an item does not change it for teammates. The three recency filters are mutually exclusive because each uses a different ordering. Other filters can be combined and saved as a named view. ### List View Switch to the list view for a table-based layout. The list view shows one row per item with sortable columns.
* **Click a column header** to sort by that field (title, status, priority, owner, etc.). * **Resize columns** by dragging the column border. * **Configure visible columns** to show or hide fields that matter to you. * Turn on the optional **Shared** column to see which items are shared with your team (off by default). See [Sharing Plans and Trackers](/task-management/sharing-plans-and-trackers). * The same filtering and search controls from the kanban view apply here. The list view works well when you have many items and need to scan or sort quickly, while the kanban view is better for visualizing workflow stages. ### Tag Board The tag board (alpha) arranges items into one column per tag, with an "Untagged" column for the rest. An item with several tags appears in each matching column, so you can see everything touching a given area at once. Switch to it from the view buttons at the top of the tracker. The tag board is for organizing and scanning; open an item to make changes.
Tracker tag board showing plans grouped into #playwright and #search columns

The tag board groups items into a column per tag. Use the search bar to filter by tag with #.

### Saved Views Any combination of type filter, filter chips, grouping, and view mode can be saved as a named view. Set the tracker up the way you want it, then in the **Saved Views** section of the sidebar click **+**, name the view, and press Enter. Saved views appear in the sidebar; click one to reapply all of its settings at once. Remove a view by hovering it and clicking the **×**. # Item Detail, Comments, Activity Open a tracker item to edit fields in place, write the body, add comments, and follow the full activity history of a piece of work. Click any item in the kanban board or list view to open the detail panel. The detail view shows all fields for an item and lets you edit them in place.
### Editable Fields * **Title** -- Click the title text to edit it inline. * **Status** -- Dropdown with all valid statuses for the item's type. * **Priority** -- Dropdown (Critical, High, Medium, Low). * **Owner** -- User picker to assign responsibility. * **Description** -- Text area for detailed notes and context. * **Tags** -- Add or remove categorization tags. * **Due Date** -- Date picker for deadlines. * **Progress** -- Percentage slider, available on Plan items only. Fields vary by item type. For example, Feature items include Release Version and Release Notes, while Idea items have only Title and Status. ### Comments Add comments to discuss an item without changing its fields. Each comment shows the author and timestamp.
Comments are useful for team discussions, leaving notes for your future self, or recording context that doesn't fit in the description. AI agents can also add comments to items during sessions. You can edit or delete your own comments. Hover a comment you wrote and use the pencil to edit it inline (press Enter to save, Escape to cancel), or the trash icon to delete it. Edited comments are marked as edited. ### Activity Log Every change to an item is recorded in the activity log: * **Who** made the change (you or an AI agent) * **When** it happened * **What** changed (field name, before value, after value)
The activity log provides a complete audit trail. When an AI agent updates an item during a session -- marking a bug as done or changing a plan's progress -- that change is recorded with the same detail as manual edits. ### Linked Sessions Linked sessions appear at the top of the detail panel, above the item's fields, with a count. Each one shows the provider, the session title, and when it was last active. Click one to jump back to that conversation. Use **Launch Session** to start a fresh session for the item, or **Link Existing** to connect a session you already have.
Tracker item detail with the Sessions section at the top, above Status and Priority

The Sessions section sits at the top of the item detail, with Link Existing and Launch Session controls.

Linking is deliberate: creating or updating an item does not attach your current session unless you ask for it. See [AI Integration](/task-management/ai-integration) for how agents link sessions. ### Open an Item in Agent Mode A tracker item opens as a tab in Agent mode, exactly like a file. You get the item's full body above and the agent session below, so you can write in the item and direct the agent against it without switching modes or losing your place.
Agent mode with a tracker item open as a tab above the session, showing the item body with its fields and content on top, the agent conversation underneath, and the session edits panel on the right

The item opens as a tab above the session. Edit its body on top, work with the agent underneath.

This is the natural place to work an item end to end. The agent reads and updates the same item you are editing, its file changes appear in the right panel as it goes, and the item stays linked to the session so the connection survives after you move on. Use the **Files**, split, and **Agent** controls at the top right to change how much room the item and the conversation each get. ### Choose What the Right Panel Shows The panel on the right of the agent window is a switcher, not a fixed sidebar. Use the dropdown in its header to change what it displays.
The agent window right panel dropdown, open on three options: Edited Files with a checkmark, Review, and Chat with Session

Switch the right panel between edited files, review, and a chat about the session.

* **Edited Files** -- The files the agent created and changed in this session, with uncommitted changes and commit controls. * **Review** -- The review queue for changes waiting on your approval. * **Chat with Session** -- A conversation about the session itself, separate from the main transcript. When you have a tracker item open, the same panel can also scope a chat to that item. See [Agent Window & Session Management](/session-management/agent-window-and-session-management). ### Launch an Isolated Worktree When Git worktrees are available, choose **Launch Worktree** in the Sessions section to start an isolated worktree and AI session for the item. Nimbalyst proposes a branch and worktree name from the Tracker key and title, inserts a live Tracker reference into the session draft, and links the resulting session back to the item. Review the worktree details before creating it. Use **Launch Session** for work that can happen in the current project checkout. Use **Launch Worktree** when the task needs its own branch and filesystem state. See [Worktrees](/developer-features/worktrees). ### Linked Files Items backed by markdown files show their source file path. You can also explicitly link additional files to an item for reference -- design docs, specs, or related source code. # Creating Items Four ways to create tracker items in Nimbalyst, from asking your AI agent during a session to writing a structured YAML definition by hand. There are four ways to create tracker items in Nimbalyst, from conversational AI to structured YAML. ### From Chat Ask the AI agent to create items during any session: > "Create a bug for the login page crash on Safari" "Track this as a feature request: dark mode for the dashboard" "Log a decision: we're using PostgreSQL instead of MongoDB" The AI determines the appropriate type, sets the status and fields based on your description, and creates the item. Ask the agent to link the item to the current session when that relationship should be recorded. Turning a conversation into tracked work is one of the workflows in [project planning](https://nimbalyst.com/use-cases/project-planning/).
### From the /track Command Use `/track` in the chat input for quick inline creation: ``` /track Login page crashes on Safari when clicking forgot password ``` The AI analyzes your description, determines the item type (bug, task, feature, etc.), and creates it in your project's tracker files. This is the fastest path when you know what you want to track. ### Inline in Markdown Track items directly within any markdown document using `#type[...]` syntax: ```markdown ## Sprint Items - Fix Safari crash #bug[status:to-do priority:critical] - Add dark mode toggle #feature[status:in-progress priority:high owner:karl] - Consider Redis for caching #idea[status:new] - Use WebSockets over polling #decision[status:decided] - Migrate to PostgreSQL #task[status:to-do priority:medium] ```
Inline items appear in the tracker alongside full-document items. Edit their properties in the markdown text or through the tracker UI -- changes sync both ways. ### From YAML Frontmatter Add `trackerStatus` frontmatter to any markdown file to make it a tracked item: ```yaml --- trackerStatus: type: plan title: Database Migration Strategy status: draft priority: high owner: karl@example.com tags: [backend, database] --- ## Overview This plan covers migrating from SQLite to PostgreSQL... ``` The tracker system automatically picks up files with `trackerStatus` frontmatter and displays them in the kanban board. Changes to the file update the tracker item, and changes made through the tracker UI update the file. This approach works well for plans, decisions, and features that deserve their own dedicated document. ### From the Tracker Panel You can also click the **+New** button in the tracker panel to create an item directly. Select the type, fill in the fields, and the item is created as a markdown file in your tracker directory. # Referencing Tracker Items Drop a live reference to any tracker item into a document or AI chat. The chip shows the current status and title and stays up to date. You can drop a live reference to any tracker item into a document or an AI chat. The reference renders as a chip that shows the item's current status and title, and it stays current as the item changes. ### Insert a reference with In a document, type `#` and start typing to search your items by key, title, or description. Pick one from the list to insert it as a chip. Typing `##` or `###` still creates a heading, so your markdown headings are unaffected. * Narrow the search to one type by including its name, for example type `#bug` to list only bugs, then keep typing to filter. * Archived items are left out of the picker.
The tracker reference picker filtered to bug items after typing #bug

Type # to search your items. Add a type name, like #bug, to narrow the list.

The same reference works in the AI chat, so you can point the agent at a specific item as you talk to it. ### What the chip shows A reference chip can show the item's type, issue key, live title, workflow state, and owner. Because it resolves the item live, those values update on their own as the item changes. Completed items keep their reference but cross out the title, making finished work visible without making the link disappear. Click a chip to open a preview with the item's status, type, priority, and owner, plus a **Go to item** button that takes you straight to it. If the underlying item can't be found (it was deleted, or has not synced to this machine yet), the chip shows the identifier in muted text and marks it as not resolved.
An inserted tracker reference chip and its preview card with a Go to item button

A reference chip, and the preview that opens when you click it, with status, type, priority, and a Go to item button.

In raw markdown, a reference is stored as a link using the `nimbalyst://` scheme, so it survives round-tripping through plain text. ### References from the AI When an agent mentions a Tracker item in chat, it links the item as the same clickable chip instead of plain text. You get the live workflow state at a glance and can click through to the item without hunting for it. References to other AI sessions in the transcript are clickable too, so you can move directly to the related conversation. # Linking Tracker Items Link tracker items to each other with parent, blocks, and duplicate relationships. Links are two-way, so setting one side updates the other. Tracker items can link to one another, not just to sessions and commits. A module can be the parent of its features, a plan can block another plan, a bug can duplicate another. Links are two-way: set one side and the reverse shows up on the other item on its own. ### Relationship fields live on the tracker type Item-to-item links are not switched on for every type by default, which is why they can be hard to find at first. A type gets them when its schema includes one or more **relationship fields**. Each relationship field sets: * the **relationship** it represents (parent of, child of, depends on, blocks, relates to, duplicates, or supersedes), * the **target types** it is allowed to link to, and * whether it holds a **single** item or **many**. The example below is a custom "Feature Module" type whose schema defines three relationship fields: **Parent Module** (child of), **Submodules** (parent of), and **Features** (parent of, pointing at feature items).
A Feature Module item showing Parent Module, Submodules, and Features relationship fields

Relationship fields defined on a type: Parent Module (child of), Submodules (parent of), and Features (parent of).

### Set up the fields (ask your agent) The quickest way to add relationship fields is to ask the AI agent in Nimbalyst to edit the type's schema. For a parent/child hierarchy, tell it something like: > "For this tracker type, update the schema to support linked trackers. Make this tracker the parent of this tracker, and that one the child (a parent can have multiple children)." Once it updates the schema, tell it which items to link to which, or let it work the links out from context. You can also edit the schema by hand under **Settings > Project > Trackers** (relationship is one of the field types). See [Custom Tracker Types](/task-management/custom-tracker-types). ### Link items With relationship fields on the type, open an item's detail panel. Each relationship field lists the items already linked as pills. Click the **+** on the field, type in the box to find an item by key or title, and choose it. Remove a link with the **×** on its pill. A field can be restricted to certain target types, so if an item you expect is missing, it may not be an allowed type for that field. ### Two-way "Linked from" backlinks When a relationship field is paired with an inverse field on the other type, the link stays in sync on both ends. In the Feature Module example, adding an item to **Submodules** automatically fills that item's **Parent Module** field, and removing either side clears the other. This is the automatic "Linked from" backlink from the release notes. A field backlinks only when its schema names an inverse field; a one-way field records just the side you set. ### Relationship types These are the relationship keys a field can use, with their natural inverse: | Relationship | Inverse | | ------------ | -------------------------------------- | | Parent of | Child of | | Depends on | Blocks | | Relates to | Relates to (symmetric) | | Duplicates | reference (set an inverse to backlink) | | Supersedes | reference (set an inverse to backlink) | # Sharing Plans and Trackers How to share Nimbalyst plans and tracker boards with teammates, and how local, hybrid, and shared tracker types differ in practice. For the complete team workflow, including shared boards, collaborative item bodies, comments, history, agent access, links, and local/hybrid/shared tracker types, see [Collaborative Trackers](/team-collaboration/trackers). Shared boards and the rest of the team layer are described on the [Teams trackers page](https://nimbalyst.com/teams/trackers/). Plans and other full-document tracker items start out local to your machine. You can share an individual item with your team so everyone works from the same copy, and edits sync both ways, including changes made offline. ### Share an item Open the item's detail panel and click **Share**. The button switches to **Shared** and the item becomes visible to your team. Click **Shared** again to make it local-only. Sharing is available when: * Your workspace has a team configured, and * The item is a native tracker item or one backed by a markdown file (frontmatter or imported). Inline tracker items, the ones written as markers inside a document, are always local. Promote one to a full item first if you want to share it. Some tracker types are shared with the whole team by design; those are always shared and have no per-item toggle. ### What stays in sync Once an item is shared, its status, lifecycle, and body stay in sync across the team. Edits from teammates flow back to you, and edits you make offline sync the next time you reconnect. Session links are personal, so they are cleared when an item becomes shared. ### Seeing what is shared Each item carries a small sync indicator: local, pending (waiting to sync), or synced. To scan sharing across many items at once, turn on the optional **Shared** column in the table view (see [Views: Kanban, List, and Tag Board](/task-management/kanban-and-list)). It is off by default. # AI Integration AI agents in Nimbalyst can create, update, and query tracker items during a session. Link the ones that matter, or turn agent access off. By default, AI agents in Nimbalyst can use the tracker system. They can create, update, and query items during a session, and you can link the ones that matter back to the session for traceability. You can turn this access off per project. Letting agents keep the board current is one of the workflows on the [task management feature page](https://nimbalyst.com/features/task-management/). ### Creating Items During a coding or planning session, the AI can create tracker items on the fly when it identifies work to track: > "I found a potential memory leak in the WebSocket handler. I've created a bug item to track it." You can also ask the agent directly: > "Create a task for updating the API documentation" "Log an idea: real-time collaboration for the editor" "Track a decision: we chose Tailwind over styled-components" The agent selects the appropriate type, sets fields based on your description, and creates the item. ### Updating Items Ask the agent to modify existing items: > "Mark the login bug as done" "Set the database migration plan to in-progress and assign it to me" "Add a comment to bug #123 saying the fix is in PR #456" "Change the priority of the caching task to critical" The agent can update any field: status, priority, owner, description, tags, and progress. The agent can also **reclassify an item to a different type** — for example, turning a task into a bug — without losing its comments, attachments, or session links. Just ask: > "Convert task #42 to a bug" "This idea is actually a feature, reclassify it" ### Querying Items Ask about your project's current state: > "What bugs are currently open?" "Show me all high-priority tasks assigned to me" "List decisions made this month" "How many items are in the In Review column?" "Find all items tagged with 'backend'" The agent can filter by type, status, priority, owner, tags, and perform full-text search across titles and descriptions. ### Session Linking When an agent creates or updates a tracker item with an explicit link (via `linkSession: true` on `tracker_create`, or by calling `tracker_link_session`), the item is connected to that session. This means: * From any item, you can see which sessions touched it * From any session, you can see which items were created or modified * You can trace the full history of an item back to the conversations that shaped it Neither creating nor updating an item auto-links the current session. The agent has to opt in (for example with `linkSession: true`), which keeps sessions from accumulating unrelated items when the agent is just logging work in passing. ### AI Agent Access You control whether AI agents can use your trackers, per project. In **Settings > Project > Trackers**, the **AI Agent Access** toggle turns the tracker tools on or off for that project. It is on by default. Turn it off and the tracker tools are removed from the agent entirely, so it can neither read nor change your items. The change takes effect for new agent sessions. ### Transcript Widgets Tracker operations performed by the agent appear as structured widgets in the chat transcript, not just plain text. Each widget shows the item type, title, status, and other key fields. Click the widget to navigate directly to the item in the tracker. This makes it easy to review what the agent created or changed without scrolling through conversation text. # Commits and Session Linking Reference a tracker item ID in a git commit message and Nimbalyst links that commit to the item, giving traceability from idea to shipped code. Tracker items connect to both your git history and your AI sessions, giving you traceability from idea to implementation. ### Commit Linking When a git commit message references a tracker item ID, the commit is linked to that item in the detail view. This lets you see exactly which commits relate to a bug fix, feature, or task. For example, a commit message like: ``` Fix Safari login crash (NIM-42) ``` automatically associates the commit with tracker item NIM-42. The item's detail view shows the linked commit with its hash, message, and timestamp. Tracing a change from item to commit to pull request is covered in [coding progress](https://nimbalyst.com/use-cases/coding-progress/). ### Opt-in Automation Commit-tracker linking can be configured in your project settings. When enabled, Nimbalyst scans commit messages for item ID references and creates the links automatically. This is opt-in -- you control whether the automation is active for each project. # Linking Sessions and Tracked Items Link AI sessions to tracker items so the conversation behind a bug fix or a design decision stays attached to the work item it produced. ### Session Linking Session linking is deliberate. Creating or updating an item does not automatically attach every active session. Link the session when the conversation is part of the item's implementation or decision history: * Ask the agent to create an item and link it to the current session * Tell the agent to link an existing item while it updates the item's status or fields * Open the item and choose **Link Existing** to select a session yourself * Choose **Launch Session** to start a new session from the item ### Navigating Between Items and Sessions The connection is bidirectional: * **From an item:** The detail view shows all linked sessions. Click any session to jump back to that conversation. * **From a session:** The agent sidebar panel shows tracker items linked to the current session. Click any item to open its detail view. ### Linked Tracker Items Sidebar
In agent mode, a dedicated sidebar panel shows all tracker items linked to the current session. This panel updates when the agent or a person adds a link, giving you a live view of the work associated with the conversation. ### Why This Matters Session and commit linking close the loop between planning and execution. You can start with an idea, track it through a decision, assign it as a task, link it to the AI session that implemented it, and see the commits that shipped it -- all from the item's detail view. # Custom Tracker Types Define your own tracker types in Nimbalyst with YAML config files. Custom types get the same kanban board, detail view, and AI integration. Beyond the six built-in types, you can define custom tracker types using YAML configuration files. Custom types get the same kanban board, detail view, and AI integration as built-in types. ### Where to Define Custom Types Create YAML files in your project's `.nimbalyst/trackers/` directory. Each file defines one custom tracker type. Nimbalyst loads these definitions when the workspace opens.
### Example: Customer Feedback ```yaml # .nimbalyst/trackers/customer-feedback.yaml type: customer-feedback displayName: Customer Feedback displayNamePlural: Customer Feedback icon: feedback color: "#f59e0b" modes: inline: true fullDocument: false idPrefix: fb idFormat: ulid fields: - name: title type: string required: true - name: status type: select default: new options: - value: new label: New icon: fiber_new - value: reviewing label: Reviewing icon: psychology - value: planned label: Planned icon: event - value: shipped label: Shipped icon: rocket_launch - value: wont-fix label: Won't Fix icon: block - name: source type: select options: - value: support label: Support Ticket - value: interview label: User Interview - value: survey label: Survey - value: social label: Social Media - name: customerName type: string - name: priority type: select options: - value: low label: Low - value: medium label: Medium - value: high label: High - value: critical label: Critical roles: title: title workflowStatus: status priority: priority ``` ### Field Types Reference | Type | Description | Options | | -------------- | --------------------------- | --------------------------------------------------------------------------- | | `string` | Single-line text | `minLength`, `maxLength` | | `text` | Multi-line text | -- | | `number` | Numeric value | `min`, `max` | | `select` | Single choice from options | `options` array with `value`, `label`, `icon`, `color` | | `multiselect` | Multiple choices | Same as `select` | | `date` | Calendar date | -- | | `datetime` | Date and time | -- | | `boolean` | True/false toggle | -- | | `user` | Person reference | -- | | `array` | List of values | `itemType` | | `relationship` | Link to other tracker items | `relationshipTypeKey`, `targetTrackerTypes`, `multiValue`, `inverseFieldId` | ### Field Properties | Property | Description | | --------------- | ------------------------------------------- | | `name` | Field identifier (used in code and YAML) | | `type` | One of the types listed above | | `required` | Must have a value when creating | | `default` | Initial value for new items | | `displayInline` | Show in compact inline view (default: true) | | `readOnly` | Cannot be edited by users | ### Roles Roles map your custom fields to standard tracker behaviors: | Role | Purpose | | ---------------- | ---------------------------------------- | | `title` | Which field is the item's display title | | `workflowStatus` | Which field drives kanban columns | | `priority` | Which field is the priority level | | `assignee` | Which field is the item owner | | `tags` | Which field contains categorization tags | | `progress` | Which field tracks completion percentage | | `dueDate` | Which field is the deadline | | `startDate` | Which field is the start date | ### Schema Properties | Property | Description | Default | | -------------------- | ---------------------------------------------- | -------- | | `type` | Unique identifier for this type | Required | | `displayName` | Singular display name | Required | | `displayNamePlural` | Plural display name | Required | | `icon` | Material Design icon name | Required | | `color` | Hex color for the icon | Required | | `modes.inline` | Show as inline markers in markdown | `true` | | `modes.fullDocument` | Can be a full markdown document | `false` | | `idPrefix` | 2-3 character prefix for IDs | Required | | `idFormat` | ID generation: `ulid`, `uuid`, or `sequential` | `ulid` | | `creatable` | Can users create items of this type | `true` | ### Editing a Type from Settings You do not have to hand-write YAML. Open **Settings > Project > Trackers**, select a type, and choose **Customize**. For a built-in or custom type, you can: * Change the singular and plural labels, icon, and color. * Add, rename, reorder, or remove workflow statuses. * Give each status its own label, icon, and color. * Add fields and configure their type, default value, and other properties. * Assign field roles such as title, workflow status, priority, owner, tags, progress, and dates. The preview shows how the type and its workflow will appear before you save. Changing a built-in type creates a project-level override; it does not modify Nimbalyst's built-in default for other projects. Built-in types you have changed show **Reset to default**. Resetting removes the project's override and restores the current Nimbalyst definition, including its original fields and statuses. ### When Files and Settings Drift Nimbalyst keeps a local copy of each type's schema in step with the YAML files in `.nimbalyst/trackers`. If the two diverge, for example after pulling a teammate's changes in git, a **Schema files are out of sync** warning appears and names the types that differ. Click **Resync from files** to bring the app back in line with the YAML on disk. ### Organize Tracker Types into Folders Tracker type folders keep a long list of workflows manageable without changing the type itself.
Tracker type navigation organized into PM and Engineering, Marketing, and Customers folders

Group related Tracker types into folders and keep the most important workflows in a deliberate order.

Create folders from the Tracker type navigation, move types into or out of a folder, and drag folders or types into a manual order. Choose **All** to view items across every folder. Folders organize the navigation only. Moving a type does not change its fields, workflow, issue keys, or existing items. In a Nimbalyst Team project, the folder structure and manual order synchronize so teammates see the same organization. # The nim CLI nim is a command-line tool for Nimbalyst trackers. List, create, update, comment, archive, and import items from your shell, and pipe JSON out. `nim` is a companion command-line tool for working with your trackers from the terminal. List, create, update, comment on, archive, and import items without leaving your shell, and pipe results as JSON into other tools. ### Install and run `nim` ships as an npm package. Install it globally: ```bash npm install -g @nimbalyst/cli ``` Then run commands as `nim `, for example `nim tracker list`. You can also run it without installing, with `npx nim tracker list`. The tracker the CLI talks to is described on the [task management feature page](https://nimbalyst.com/features/task-management/). ### How it connects `nim` finds your workspace and tracker data on its own: * When Nimbalyst is running, `nim` talks to the app (live mode), so writes go through the same path as the UI. * When the app is closed, `nim` reads your local tracker database directly. Reads work either way. A few commands depend on the running app: importing from external sources, linking a live session, and defining or deleting a type. Open Nimbalyst before using those. If you work with more than one project, point `nim` at one with `--workspace `. ### Reading items ```bash nim tracker list --type bug --status open --priority high nim tracker list --where severity=critical --since 1d --json nim tracker get NIM-123 nim tracker show NIM-123 # renders the body nim tracker types # list types; add "show " for one schema ``` Common list filters: `--type`, `--status` (or the shortcuts `open` and `closed`), `--priority`, `--owner me`, `--search`, `--since` and `--until`, `--tag`, and `--where field=value` for anything else. Add `--json` for machine output, `--csv --columns key,status,title` for a table, or `--quiet` for just the IDs. ### Creating, updating, and commenting ```bash nim tracker create bug "Login times out" --priority high --tag auth --body-file repro.md nim tracker update NIM-123 --status in-review --owner me nim tracker update NIM-123 --unset owner nim tracker comment NIM-123 "Repro confirmed on main" nim tracker archive NIM-123 nim tracker unarchive NIM-123 ``` `create` takes the type and a title, plus optional `--status`, `--priority`, `--owner`, `--tag` (repeatable), `--label`, `--field key=value`, `--due`, `--progress`, and `--body` or `--body-file`. `update` takes the same flags to change fields, plus `--unset ` to clear one. ### Importing from external sources With the app open, `nim` can pull items in from installed importers, such as GitHub issues: ```bash nim tracker importers # what is installed nim tracker import search github-issues --repo owner/repo --state open nim tracker import github-issues "owner/repo#42" --type bug ``` ### Output and scripting Every read command supports `--json`, so you can pipe `nim` into other tools. `nim status` reports how it is connecting and which workspace it resolved. Set `NIM_OWNER` so `--owner me` resolves to you, or `NIM_WORKSPACE` to fix a default project. Run any command with `--help` for its full set of flags. # Local Config Where Nimbalyst keeps tracker configuration: type definitions, project settings, and issue key prefixes, all as plain version-controlled files. Tracker behavior is configured through project-level directories and settings. Everything is stored as plain files, version-controlled, and portable between machines. ### Tracker Type Definitions Custom tracker types live in the `.nimbalyst/trackers/` directory at your project root. Each YAML file in this directory defines one tracker type. Nimbalyst loads all type definitions when the workspace opens. ``` your-project/ .nimbalyst/ trackers/ customer-feedback.yaml release-note.yaml interview-question.yaml ``` See [Custom Tracker Types](/task-management/custom-tracker-types) for the full YAML schema. ### Tracker Files Inline tracker markdown files are stored in the `nimbalyst-local/tracker/` directory within your project. You can organize files by type, topic, sprint, or any structure that works for you: ``` your-project/ nimbalyst-local/ tracker/ bugs.md sprint-12-tasks.md api-decisions.md q2-features.md ``` These are standard markdown files with inline `#type[...]` tags or `trackerStatus` YAML frontmatter. The tracker system scans this directory and surfaces all items in the kanban board and list view. ### Issue Key Prefix Each project can have a configurable issue key prefix (e.g., `NIM-`) that appears on all item IDs. This makes it easy to reference items in commit messages, comments, and conversations. Configure the prefix in your project settings. ### Commit-Tracker Linking Automatic commit-tracker linking is an opt-in toggle in project settings. When enabled, Nimbalyst scans git commit messages for item ID references (e.g., `NIM-42`) and links the commit to the corresponding tracker item. ### What Gets Version-Controlled Tracker files are plain markdown, so they work with any version control system: * `.nimbalyst/trackers/*.yaml` -- Type definitions travel with the repo. Anyone who clones the project gets the same custom types. * `nimbalyst-local/tracker/*.md` -- Item files are local by default. Add them to `.gitignore` if you want project-specific items that don't sync, or commit them if you want shared visibility. * Changes to tracker items via the UI or AI update the underlying markdown files, which show up in your normal git diff and commit workflow. # Coding with Coding Agents & Nimbalyst How to code with Claude Code and Codex inside Nimbalyst, a visual interface for coding agents with your files, diffs, and sessions side by side. *** Nimbalyst integrates a UI for coding agents like Claude Code and Codex directly into your markdown workspace. Nimbalyst runs on top of Claude Code and Codex rather than replacing them. See the [Claude Code GUI page](https://nimbalyst.com/claude-code-gui/) and the [Codex GUI page](https://nimbalyst.com/codex-gui/) for what the desktop workspace adds on top.
### Nimbalyst's Two Modes **Chat Mode**: AI sidebar for quick questions and targeted edits. Good for: * Explaining code * Small edits to the current document * Quick lookups **Agent Mode**: Full-screen autonomous coding. Good for: * Multi-file refactors * Implementing features from a plan * Running tests and fixing failures iteratively * Running multiple sessions in parallel ### Code Editor with Diff Visualization
When the AI edits code or a a document, changes appear inline: * **Green background**: Added content * **Red background**: Removed content (with strikethrough) **Accept/Reject**: * Accept All: Keeps all changes * Reject All: Reverts to original content Changes remain visible until you accept or reject them. ### Inline edit cards in the transcript Both Claude Code's `Edit` tool and Codex's `file_change` tool render as red/green edit cards directly in the session transcript, so you can see exactly what the agent did to each file as the turn unfolds. Edit cards work for: * New files (rendered as a single-color "added" card) * Existing files (red lines for removals, green for additions) * Gitignored or never-snapshotted files * Renamed and deleted files *** # Basics on Code/Git for Non-Devs A plain-language introduction to code and git for product managers and designers who want to use a coding agent without a dev background. ### Working with Code * Coding agents like Claude Code and Codex can read your code and write code if you have it locally, say in GitHub client, on your machine. * If you are a Product Manager who wants to use a coding agent to better understand your code, its status, etc, download GitHub Client and ask your dev team for read-only access to your codebase If you are a PM working alongside engineers, [Claude Code for product managers](https://nimbalyst.com/claude-code-for-product-managers/) covers the same ground without a terminal. ### Moving plans or other documents into Git If you want a a plan or other document to be synched with Git, simply move the document into another folder that is not git-ignored. * For example, your organization might have a folder for Specification or Shared Plans. When a plan you are working on is at the right state to be in this folder for all to see and reference, move it. # Turn on/off Developer Mode Turn Developer Mode on or off in Nimbalyst to show or hide the terminal, git worktrees, and the other git features you may not need. Nimbalyst has two modes: Standard Mode and Developer Mode. ### Developer Mode The following features are only available in Developer Mode * Terminal * Worktrees * Many Git features NOTE: The Git related features will only be available if your Project is Git-integrated. Everything gated behind Developer Mode is described on the [developer tools page](https://nimbalyst.com/features/developer-tools/). ### Turning on Developer Mode You can select your mode under Settings, Advanced
# Terminal Window Run a Ghostty-powered terminal inside Nimbalyst. Create multiple terminal sessions in your workspace directory that survive app restarts. ### Terminal in Nimbalyst Nimbalyst enables you to run a Ghostty-powered terminal directly within Nimbalyst. You can create multiple terminal sessions, each running independently in your workspace directory. Terminal sessions persist across app restarts, so your command output is preserved.
The terminal sits alongside the visual editors rather than replacing them. See the [developer tools page](https://nimbalyst.com/features/developer-tools/).
### Opening and Closing the Terminal Open and close the terminal from the terminal icon on the left nav or with the command key You can have multiple terminals by clicking the + and making a new terminal tab
### Using the Terminal Type commands and press Enter to run them. The terminal works like any standard shell: * Run commands: `ls`, `git status`, `npm install`, etc. * Navigate directories: `cd folder` * Use tab completion (depends on your shell) * Access command history with up/down arrow keys #### Shell Detection Nimbalyst automatically detects and uses your system shell: | Platform | Default Shell | | -------- | ------------------- | | macOS | zsh (or bash) | | Linux | bash (or zsh, fish) | | Windows | PowerShell (or cmd) | #### Scrollback Buffer Your terminal output is preserved (up to 500KB). When you reopen a terminal session: * Previous output is restored * You can scroll back through command history * A new shell process starts in the same directory #### Command History * Each terminal maintains its own command history file. Your shell's history (accessed via up/down arrows) persists across sessions. * **Note**: Fish shell and Windows cmd have limited history persistence. #### Process Management * **Running process**: Commands run until complete or until you stop them with Ctrl+C * **Process exit**: If the shell exits, press Enter to restart it * **App quit**: When you close Nimbalyst, all terminal processes are stopped and scrollback is saved ### Worktrees * Each worktree has a dedicated terminal button for quick access and separated work * Each terminal session persists with its own storage ### Tips * **Working directory**: Each terminal starts in your workspace folder * **Copy/paste**: Use your normal system shortcuts (Cmd+C/Cmd+V on Mac, Ctrl+C/Ctrl+V on Windows/Linux) * **Clear screen**: Use `clear` or Ctrl+L to clear the terminal * Environment variables set during a session don't persist to new sessions # Worktrees Use git worktrees in Nimbalyst to run AI coding agents on several branches at once, each with its own directory, session, and diff to review. Git worktrees let you work on multiple branches simultaneously, each with its own working directory. For background on why worktrees matter when several agents are running at once, see the [git worktrees guide](https://nimbalyst.com/blog/git-worktrees-for-ai-coding-agents-complete-guide/).
**How to use:** * Create a worktree from the Agent Mode UI to start an isolated AI session on a new branch. * From a Tracker item, choose the worktree action to launch an isolated session with that item linked as its context. * From Pull Request mode, choose **Open in Worktree** to check out the pull request branch and start a session inside it. * Each worktree has its own file system state, so changes don't interfere with your main branch. * Rebase worktrees even with uncommitted changes - auto-stashing handles it for you. * Use the worktree terminal button to access a terminal scoped to that specific worktree.
**Benefits:** * Work on multiple features in parallel without stashing or switching branches * AI sessions stay isolated - experiments don't affect your main codebase * Safe rebasing with automatic stash management For the full pull request workflow, see [Pull Request Reviews](/developer-features/pull-request-reviews). # Working with Git Commit, check status, and manage branches in Nimbalyst with AI-generated commit proposals and git file status colors in the file tree. Streamlined git workflow with visual commit proposals and real-time status updates. Git Integration * **Interactive Claude-generated git commit proposals** * **Manual git commits** - Commit files edited in an AI Session * **Git file status colors for AI Sessions** - Visual indicators for added/modified/deleted files * **Detect more Claude changes** - Including rm, mv, echo >>, etc * **Uncommitted files count on sessions** - See at a glance which sessions have pending changes The [git feature page](https://nimbalyst.com/features/git/) covers commit proposals, status colors, and branch handling.
**How to use:** * When committing, use the interactive file picker to select exactly which files to include. * View full commit details in the expanded git widget. * File status colors (green for added, yellow for modified, red for deleted) help you understand changes at a glance. * Pending file reviews are auto-approved when you commit, streamlining your workflow. **Benefits:** * No more polling for git status - updates appear instantly * Visual clarity on what's changed * Faster commit workflow with fewer clicks ### Files Sidebar in Agents Mode * A compact file list at the top showing referenced files * A pending review banner at the bottom when files need review
### File Categories Files are organized into three collapsible sections: #### Edited Files the AI has modified. These show: * **Operation icon**: What the AI did to the file * Green `+` = Created new file * Blue pencil = Edited existing file * Red trash = Deleted file * Orange rename = Renamed file * **Git status badge**: Current version control state * **Line counts**: `+5` (lines added) `-3` (lines removed) * **Pending review indicator**: Yellow highlight with review icon if awaiting your approval #### Referenced Files you mentioned in your prompts using `@filename` syntax. These are files you brought to the AI's attention but weren't necessarily modified. #### Read Files the AI read to understand your codebase. These provide context for the AI but weren't modified. ### Git Status Badges For edited files, small colored badges show the git status: | Badge | Meaning | | -------------- | -------------------------------- | | **M** (yellow) | Modified - Changes not staged | | **S** (green) | Staged - Changes ready to commit | | **?** (gray) | Untracked - New file not in git | | **D** (red) | Deleted | Hover over a badge to see "Git status: modified" (or staged, etc.) ### Pending Review Files When the AI makes changes, those files may show as "pending review": * **Yellow background**: The file has AI changes you haven't reviewed yet * **Review icon**: A small review icon appears next to the filename * **Banner**: Shows count like "3 files pending review" with a "Keep All" button #### Accepting Changes * Click **Keep All** to accept all pending AI changes at once * Or review files individually by clicking on them ### File Activity Tracking and Git Status in Files Mode
The sidebar tracks all files the AI interacts with during a session: **Git Status** - Shown with a Git label (M for modified, ? for untracked file) **Uncommitted Changes** - Shows only files/folders with uncommitted changes **Files Read** - Files the AI examined to understand context in the session **Files Written** - Files written to by AI during the session ### Diff Peek in the Commit Proposal Each file in a commit proposal has a diff peek popover so you can see exactly what changed without leaving the widget. It uses the same diff view as the Git extension's changes panel, and the popover is resizable — the size you pick is remembered globally, so the proposal widget and the Git extension stay in sync. The peek shows a combined HEAD-vs-working diff that includes staged, unstaged, and untracked changes uniformly. ### Diff Peek in the Git Log In the Git extension, when you select a commit in the log, the commit detail panel lists every file touched by that commit. Click any file in that list to pin its unified diff in the same peek popover. * Click a file to open the diff for that file at that commit * **Up/Down** arrow keys step through files in the commit while the popover is pinned * **Esc** closes the popover * The popover reuses the size persisted by the changes panel and the commit proposal widget, so all three diff peeks stay in sync ### Git Command History Open the Git extension's **Output** tab to follow commands run through Nimbalyst. Push, pull, fetch, commit, and other Git operations appear as they run and remain available after the panel closes or the renderer reloads. Each entry shows: * The command and start time * Live standard output and error output * Running, completed, failed, or interrupted state * Duration and exit code * A suggested recovery step for common Git failures Long errors show a short preview. Choose **View full error** for the complete message or **Copy** to put the error on the clipboard. Use **Clear Log** when you no longer need the completed history; a command that is still running remains attached until it finishes. This is separate from the shell history in the Terminal. Terminal history remembers commands typed into a shell, while Git command history records operations launched by Nimbalyst and their output. ### Auto-Approve Commits Skip the manual approval step for git commit proposals.
**How to use:** 1. Go to **Settings** and enable **Auto-approve commits**, or toggle it directly on any git commit proposal widget 2. When enabled, Claude's commit proposals are committed automatically without waiting for your approval # Pull Request Reviews Review GitHub pull requests inside Nimbalyst. Read the diff, run an AI review, open the branch in a worktree, then comment, approve, or merge. Review GitHub pull requests without leaving Nimbalyst. Pull Request mode brings the conversation, changed files, commits, checks, tracker-based triage, and AI review workflow into one place. See [code review](https://nimbalyst.com/use-cases/code-review/) for how teams run AI-assisted reviews end to end. ## Before You Begin Pull Request mode is available when: * Developer Mode is enabled. See [Turn on/off Developer Mode](/developer-features/turn-on-off-developer-mode); the setting is under Settings, Advanced, Application Mode. * The project is a Git repository whose `origin` remote points at GitHub (GitHub Enterprise hosts work too). * The [GitHub CLI](https://cli.github.com/) is installed and signed in with `gh auth login`. All GitHub access goes through your `gh` CLI. Nimbalyst stores no GitHub tokens of its own. If `gh` is missing or signed out, Pull Request mode shows setup instructions and a recheck button. Open Pull Request mode from the **Pull Requests** button in the navigation gutter or press **Cmd+U**. The button appears once Developer Mode is on and the workspace has a GitHub remote. ## Find the Pull Request That Needs You Use the filters above the pull request list to focus on: * **Open** or **Closed** pull requests * **Awaiting my review** * **Created by me** * **With conflicts** or **Draft** * **Review Status** chips, which appear when pull requests are linked to tracker items (see triage below) Search by title or pull request number, then sort by recent activity. ## Review a Pull Request Select a pull request to open its detail view: * **Conversation** shows the description, inline review threads (open, resolved, and outdated), and the discussion. Add your own pull-request-level comment from the box at the bottom. * **Files Changed** shows the diffs with a file tree. Switch between a full-file compare view and a GitHub-style collapsed diff with unified or split layout. Very large diffs load on demand. * **Commits** shows the commits included in the branch, with per-commit stats and copyable SHAs. * **Checks** shows CI and other GitHub checks grouped by failing, in progress, and passing, with links to the details on GitHub. Results refresh on a polling interval rather than streaming live. The header also shows the source and destination branches, linked Tracker items, review state, and merge readiness.
Pull Request mode with a pull request open on the Conversation tab and the Approve, Review with AI, GitHub, and Open in Worktree actions visible

Review the pull request directly, start an AI review, or open the branch in an isolated worktree.

## Review with AI Click **Review with AI** to start an agent session prefilled with a review command for the pull request. The session opens in the chat pane right next to the pull request, and each prompt carries a compact PR context card so the agent knows exactly which pull request it is reviewing. If tracker items reference the pull request, the session is linked to them automatically. The agent can inspect the pull request, explain the changes, identify risks, and suggest review feedback using the same project context and tools as your other Nimbalyst sessions. ## Open the Pull Request in a Worktree Click **Open in Worktree** to create (or reuse) an isolated worktree on the pull request branch and open an agent session inside it. Edits and Git operations stay separate from your main working directory, and Nimbalyst switches to Agent mode with the session ready. Use a worktree when you want the agent to run tests, make follow-up edits, or investigate the branch without disturbing other work. See [Worktrees](/developer-features/worktrees). ## Triage with Review Statuses Pull request triage runs on Nimbalyst Trackers. Link a pull request to any Tracker item with **Link tracker item** in the pull request header. Once linked: * The item's workflow status appears as a status pill in the header. Click the pill to change the review status. * Rows in the pull request list show a compact status badge, and the sidebar gains matching **Review Status** filter chips. * You can move between the pull request, the Tracker item, and any linked AI session without searching for each one. A common setup is a dedicated tracker type for pull requests with statuses such as Backlog, Needs Review, Inspecting, and Safe, with one item per pull request. Nimbalyst never creates these items automatically; create them yourself or ask your agent to create and link them for the open pull requests. Merging inside Nimbalyst can also advance linked items automatically when their tracker type defines a post-merge workflow status, and a one-click hint offers the update after a pull request merges. ## Comment, Approve, or Merge Add pull-request-level comments from the Conversation tab. Inline review threads from other reviewers are shown for context but cannot be authored inline yet, and there is no request-changes action; use a comment or an approval. Use the actions in the pull request header to approve or merge when the repository and your GitHub account allow it. Nimbalyst supports GitHub's squash, merge-commit, and rebase strategies, limited to the methods the repository allows, and always asks for confirmation before merging. For squash and merge-commit merges you can edit the commit message first. ### GitHub CLI Workflow Permission Some pull requests modify GitHub Actions workflow files. GitHub requires the CLI token to include the `workflow` scope before those changes can be merged. If Nimbalyst reports that the scope is missing, run: ```bash gh auth refresh -h github.com -s workflow ``` Complete the GitHub authorization flow, then return to the pull request and retry the merge. # Agent Teams Agent Teams let one coding agent session spawn teammate agents that work in parallel. How to turn it on and when parallel agents help. ### Agent Teams Agent Teams let a single coding agent session spawn teammate agents that work in parallel.
Running fan-out work across several agents is covered on the [agent orchestration page](https://nimbalyst.com/features/agent-orchestration/). **How to use:** 1. Go to **Settings > Application > Claude Agent** 2. Enable **Agent Teams** 3. Start a session. When the agent decides subtasks can run in parallel, it spawns teammates automatically 4. Each teammate shows a distinct progress indicator in the transcript **Good to know:** * Teammate output stays contained -- it does not leak into the main transcript * The main session waits for all teammates to finish before completing # Nimbalyst Teams: Step by Step A step-by-step walkthrough of Nimbalyst Teams: sign in, invite your team, and work together in shared trackers and documents with your coding agents. Seven steps from a solo workspace to a team working in the same trackers, the same documents, and the same files as their coding agents. Every screen below is the product as it ships. Watch the whole walkthrough in under three minutes, or read the steps below. {% embed url="" %} ## Step 1. Sign in to Nimbalyst Open the user menu at the bottom of the left rail and choose **Sign in**.
The Nimbalyst user menu open, showing Application Settings, Project Settings, No organization, and Sign in

The user menu at the bottom of the left rail.

Sign in with Google or with a magic link sent to your email address. Signing in is what connects this copy of Nimbalyst to a team.
The Account tab in Nimbalyst Settings, showing Continue with Google and an email field for a magic link

Sign in from Settings, under Account.

## Step 2. Create your organization From that same menu, choose **Set up** next to **No organization**.
The user menu with the No organization row highlighted and a Set up action beside it

Set up an organization from the user menu.

Name your organization. Everyone you invite sees this name, and you can change it later.
The New organization dialog on its Name step, with an organization name typed in and the owner's address below the field

Step one of three: name the organization.

Then invite your teammates by email. They join as members, and you can change roles afterwards.
The New organization dialog on its Invite step, with a teammate's email address entered

Step two of three: invite the team.

Everyone you add appears in the organization's member list, where you can change a role or invite more people at any time.
The organization management dialog listing team members with their email addresses and roles, and an invite field at the bottom

The member list for your organization.

## Step 3. Your teammate receives an invite email They receive an email with one button. There is no account to create first.
The invitation email, with an explanation of Nimbalyst and a Join button

The invitation email your teammate receives.

## Step 4. They accept and land in the team Clicking through accepts the invitation and puts them in the organization. From there they can open the team in the desktop app, or keep working in the browser.
The confirmation screen after accepting an invitation, offering to open the desktop app or continue in the browser

Accepted, and in the team.

## Step 5. Working collaboratively in trackers Switch to **Tracker** mode. With a team, the left navigation splits into two groups. The top group belongs to the organization and everyone in it sees the same items. The bottom group stays on your machine.
The tracker sidebar split into a Northwind section marked Shared with 5 people and a Personal section marked Local only

The team's trackers lead. Yours stay local.

Every tracker opens as a grid you can edit in place. Press **Cmd+Shift+N** anywhere in Nimbalyst to launch an agent session against whatever you are looking at, without leaving the board.
A shared bug tracker in grid view with the Launch New Session popup open over it, carrying a prompt about a checkout timeout

Cmd+Shift+N puts an agent on the item in front of you.

Open an item and it expands into a full document the team writes together, with its own agent chat alongside.
A tracker item expanded to full width with a written body and a Chat about this item panel on the right

An item's body is a document, not a text field.

Put a file reference on its own line in that body and it becomes a live embed. Anyone with access can edit it in place, or open it in its own editor.
A tracker item body containing two live embeds, an Excalidraw diagram and a UI mockup, each with its path and an Open action

Embedded files render live inside the item.

Link your own agent sessions and the files they touched to an item, so the work and the record of it stay together.
A tracker item detail panel showing a Sessions section with Link Existing and Launch Session actions

Link an existing session, or launch a new one from the item.

## Step 6. Working collaboratively in documents Right click any file in your project and choose **Share to Team**. Nimbalyst scans the file for embedded files and offers to share those alongside it, so your teammates do not open the document and find empty placeholders.
The file tree context menu open on a markdown file, showing the Share to Team action

Any project file can become a shared document.

**Shared Docs** holds every shared document and folder in one place. A blue dot marks anything changed since you last opened it.
The shared documents space with a folder tree on the left and a table of shared documents with authors, last edited times, and unread dots

One space for everything the organization shares.

Star the documents you work in every day and the **Favorites** filter brings them straight back.
The shared documents space filtered to Favorites, showing a single starred document

Favorites, one click away.

Open a shared document and you are editing the same copy as everyone else, with a labelled cursor for each person. Each teammate's locally running coding agent works in that same document.
A shared launch plan open in Nimbalyst with a teammate's labelled cursor in the text and an agent prompt staged in the chat

People and their agents, in one shared copy.

Select a passage to leave a comment, mention someone with `@`, and reply in the thread. Comments live with the document, so they follow it everywhere it is opened.
A comment thread on a highlighted passage of a shared document, with a reply below the first comment

Comments and replies attach to the passage they are about.

Anything addressed to you shows a badge in the top right corner of the window.
The top-right toolbar cluster in Nimbalyst with an unread count badge on the inbox button

The unread badge, top right.

Open it for a single list of every mention, comment, and message waiting on you, each linked to the document it came from.
The team inbox listing mentions, comments, and messages with the document each one came from

Every mention, comment, and message in one list.

## Step 7. Teammates can work in the browser Someone without the desktop app opens [console.nimbalyst.com](https://console.nimbalyst.com) and reads, writes, and comments on the same shared documents. People on the desktop app and people in the browser work side by side on the same files.
The Nimbalyst web console showing the same shared document tree and table in a browser

The same shared space, in a browser.

See [Web Console](/team-collaboration/web-console) for what the browser supports. ## Where to go next * [Team Collaboration Overview](/team-collaboration/overview) * [Collaborative Documents](/team-collaboration/documents) * [Collaborative Trackers](/team-collaboration/trackers) * [Set Up Nimbalyst Teams](/team-collaboration/setup-teams-and-orgs) # Team Collaboration Overview How Nimbalyst Teams adds shared documents and trackers on top of each teammate’s local workspace and their own locally running coding agents. Each teammate runs the open-source Nimbalyst app on their own machine with their own Claude Code, Codex, or other local agents. Nimbalyst Teams adds a shared layer for files and Trackers without replacing anyone's local workspace, environment, or agents. See [Nimbalyst for Teams](https://nimbalyst.com/teams/) for what the shared workspace covers, or go straight to [Nimbalyst Teams: Step by Step](/team-collaboration/teams-tutorial). {% hint style="info" %} Nimbalyst Teams is in **beta**. Expect bugs. Organizations are free during beta and will require a paid Nimbalyst Teams subscription after launch. {% endhint %}
Two teammates editing the same architecture diagram in real time on a shared canvas, with a live labeled cursor

People and their agents work together on the same shared documents, mockups, diagrams, and trackers.

### One integrated workflow for the whole team Give the whole team higher bandwidth with less context switching. Manage agents, edit the work visually, and track tasks in a shared workspace where each teammate keeps using their own local Nimbalyst and agents, live or asynchronously. Team collaboration is faster when people and agents share the whole workflow. Nimbalyst keeps plans, visual files, Trackers, sessions, reviews, and delivery links together so context survives every handoff. * **One workflow from plan to ship:** Move from a spec to a mockup, implementation session, Tracker update, review, commit, and pull request without rebuilding the story in each tool. * **Every file type in the same context:** Work across markdown, code, mockups, diagrams, spreadsheets, data models, and other supported editors while teammates and their agents stay connected to the same project context. * **Less context switching:** Stop moving between a document app, task tracker, diagram tool, editor, and terminal or copying context from one into another. * **Higher-bandwidth collaboration:** Rich visual editors, live presence, linked work, and immediate status let the team understand and direct more work at once than a collection of text-only tools. ### Multiplayer on the work #### Edit the same docs, mockups, and diagrams together
Two teammates editing the same document, with a UI mockup embedded inline and a live labeled cursor

A shared document can contain an editable mockup, diagram, image, or tracker inline.

* **True multiplayer:** Edit shared markdown, mockups, and diagrams together in real time, with a live cursor for everyone in the document. * **Your agents in the same room:** Each teammate's local Claude Code and Codex agents edit the same shared documents, not separate copies. * **Promote and review:** Promote any local file to a shared one in a click, and review its full change history. ### Plan and track together #### Plan and track the work on one shared board
A shared task list with an item open, showing its linked session, status, priority, owner, and written content

The team and its agents keep the same tracker items, fields, and linked sessions current.

* **Shared boards and trackers:** Plans, decisions, bugs, tasks, and ideas live on shared boards and trackers in the same workspace as your docs. * **Everyone updates the same items:** Teammates and their local agents read and update the same tracker items, so the board reflects what is actually happening. * **One place for status:** See what is in progress, done, or blocked instead of pinging people for updates. ### One connected workspace Shared docs, local files, trackers, and agent sessions live together and link to each other. A tracker can link to the session working it, the source document it came from, and the pull request that closes it. Documents can contain live tracker references and embedded visual files. For a look at how the shared layer works across a whole team, see [how Nimbalyst Teams works](https://nimbalyst.com/teams/how-it-works/). ### How collaboration works 1. **Everyone works locally.** Each teammate runs Nimbalyst on their own machine with their own Claude Code, Codex, or other agents. 2. **Authenticate to Nimbalyst Teams.** Signing in gives each person access to the organizations, projects, shared files, and shared Trackers they are authorized to use. 3. **Promote what should be shared.** Move a local file or Tracker item into the shared team workspace when the team should work on it. Only explicitly shared content enters the team collaboration flow. 4. **Work live, asynchronously, or offline.** Shared files and Trackers sync across everyone's workspace. Previously opened documents remain available from an encrypted local copy, and offline changes upload when the device reconnects. 5. **Keep the work connected.** Shared docs, local files, Trackers, and sessions link to one another so the team and its agents work from one picture instead of scattered tools. ### Set up Nimbalyst Teams Getting a team running takes three steps: 1. Sign in under **Settings > Account > Accounts** and create an organization. 2. Attach the current project to that organization under **Settings > Project > Sharing**. 3. Invite teammates by email from the organization management dialog. Full instructions, including roles, projects, messaging, and encryption, are in [Set Up Nimbalyst Teams and Organizations](/team-collaboration/setup-teams-and-orgs). Continue with [Collaborative Documents](/team-collaboration/documents) or [Collaborative Trackers](/team-collaboration/trackers). ### Teammates without the app Anyone you invite can open your team's shared documents in a browser at [console.nimbalyst.com](https://console.nimbalyst.com), edit them live, and leave comments without installing anything. See [Web Console](/team-collaboration/web-console). ### Enterprise-grade security, local-first by default Your code stays on your machine. Only what you choose to share gets synced, and only the people you invite can read it. * **Encrypted through Cloudflare:** Shared documents, Trackers, and tasks flow through Nimbalyst's Cloudflare sync service and are encrypted in transit and at rest. * **Isolated and authorized per team:** Team data is isolated per team and requires an authenticated, authorized membership. * **SOC 2 Type 2 certified:** Nimbalyst has completed SOC 2 Type 2 certification with audited controls, processes, and documented compliance. * **Local-first by default:** Local files remain on your machine until you promote one for the team and its agents to work on together. Nimbalyst-hosted Teams uses server-managed encryption keys so authorized web, CLI, and agent experiences can access shared team work. Hosted team data is encrypted but is not zero-knowledge. Personal device sync uses a separate end-to-end encrypted model. # Collaborative Documents Share markdown docs, mockups, and diagrams with your team. Teammates and their local coding agents edit the same files in real time. ## Every document, shared with your team and their agents Markdown, mockups, diagrams, and more, edited together in real time or asynchronously. Each teammate's locally running Nimbalyst and configured agents work in the same shared files, not separate copies. See [collaborative documents in Nimbalyst Teams](https://nimbalyst.com/teams/documents/) for how shared editing works.
Two teammates editing the same markdown document in real time, with presence and a live labeled cursor

True multiplayer editing keeps everyone on one shared copy.

### Everyone in the same document at once
Two teammates editing the same document with presence avatars and a live labeled cursor

Presence avatars and labeled cursors show who is in the document and where they are working.

* **True multiplayer:** Type in the same markdown, mockup, or diagram at the same time, with a live cursor for every person in the document. * **See who is here:** Presence avatars show who is in the document and where they are working right now. * **Your agents, in the same file:** Each teammate's local Claude Code and Codex agents edit the same shared document, so people and agents stay on one copy. ### One document, every kind of content inside it Shared documents are not limited to text. Embed a mockup, diagram, image, or inline tracker in the page and edit it in place.
A shared document with a UI mockup embedded inline and a live cursor

The embedded mockup remains editable inside the shared document.

* **Markdown, mockups, and diagrams:** Work in shared markdown, UI mockups, Excalidraw, Mermaid, mind maps, data models, and spreadsheets in one workspace. * **Embed anything inline:** Drop an Excalidraw canvas, mockup, image, or other supported extension file into a document and edit it inline. * **Inline trackers:** Add an editable tracker reference inside a document so the plan and the task remain connected. Type `@` to choose a project file. Put the file reference by itself in a paragraph and Nimbalyst upgrades compatible editor types into a live inline embed.
A shared markdown document containing two live embeds, a mockup showing a tracker board and an Excalidraw diagram, each with a header naming its shared path and an Open action

Embedded files render live inside the shared document. Each embed names its shared path and opens in its own editor.

An embed inside a shared document is a live view of another shared file, not a flattened image. The mockup and the diagram above are still their own documents. Anyone with access can edit them in place, or click **Open** to work on them in the full editor, and the change appears everywhere the file is embedded. ### Sharing a document that contains embeds When you share a markdown file that embeds other files, those embedded files have to be shared too. Otherwise your teammates would open the document and find empty placeholders where the mockup and diagram should be. Nimbalyst handles this in the **Share to Team** dialog. It scans the document for embedded files and lists each one under **Linked documents**, pre-checked.
The Share to Team dialog showing the source file, shared name, destination folder tree, and a Linked documents section listing an embedded mockup and an Excalidraw diagram, both checked and marked Already shared

Share to Team finds the files a document embeds and shares them alongside it.

* **Everything the document needs, in one action:** Leave the linked documents checked and Nimbalyst shares them with the parent document, so the embeds render for everyone. * **Already-shared files are recognized:** An embedded file that is already in the team space is marked **Already shared** and is reused rather than duplicated. * **You stay in control:** Uncheck any linked document you do not want in the team space. Its embed will show as unavailable for teammates until you share it. * **The count reflects your choices:** The confirm button tells you how many documents are about to be shared. Embedding works the same way in a tracker item body. See [Collaborative Trackers](/team-collaboration/trackers). ### Supported Shared File Types Nimbalyst can share and co-edit: * Markdown, plain-text, and code files such as TypeScript, HTML, Swift, and Python * Excalidraw diagrams and supported visual diagrams * Mockups * CSV, TSV, and calc spreadsheets * Data models * Other extension file types that declare collaboration support The editor determines how collaboration appears. Text and code show live cursors and selections, spreadsheets show the selected cell and active editor, and visual editors can show canvas selections and presence. ### Promote any local file to shared in a click
The file context menu open on a document, with a Share to Team action

Start locally, then choose Share to Team when the file is ready for collaboration.

1. In Files mode, right-click the local file. 2. Choose **Share to Team**. 3. Choose its shared name and destination folder. 4. Confirm **Share to Team**. Only what you choose is shared. Your code and other local files remain on your machine. Nimbalyst keeps a link to the originating local file so you can open, relink, or re-upload it when needed. The shared copy flows through Nimbalyst's Cloudflare sync service and is encrypted in transit and at rest. Teammates who return later receive the changes made while they were away and can continue with their own local agents. ### Work Offline Previously opened shared documents open immediately from an encrypted local copy when the network is unavailable. You can continue editing text, supported visual content, and attachments while offline. Nimbalyst keeps document changes and attachment uploads in a durable queue. When the device reconnects, it uploads the queued work and merges it with changes received from teammates. The queue survives a window or application restart. Documents you have never opened still require a connection for their first download. An attachment that is not yet cached shows an unavailable placeholder until Nimbalyst can retrieve it. ### Discuss the work right where it lives
A shared document with a highlighted passage and a comment thread with a reply

Comments keep review feedback beside the exact passage being discussed.

* **Comment in context:** Leave a comment on a passage or section so feedback sits next to the thing it is about. * **Threads that resolve:** Reply, resolve, and reopen threads so review happens in the document instead of a separate chat. * **Everyone stays in sync:** Comments sync in real time so the whole team sees the discussion as it happens. ### Never lose a version
Document History for a shared document, showing a saved revision, its author and metadata, and a Restore as Current Version action

Review saved revisions and restore the one you need without leaving the shared document.

* **Full change history:** Every shared document keeps its history so you can see how it changed and who changed it. * **Restore in one click:** Roll a document back to an earlier version without leaving the editor. * **Review before you trust:** Scan what changed since you last looked so nothing slips by unnoticed. Right-click a document in the Collaboration sidebar and choose **View History**. Press **Cmd/Ctrl+S** in a shared document to save a revision. ### Find shared work in the Shared home **Shared home** lists every document in the team space in one sortable table, with the folder tree beside it.
The Shared home view listing shared documents in a table with Name, Type, Created by, Last edited, Viewed by me, and Folder columns, filter tabs for All, Favorites, Unread, Recently opened, Shared with me, and Shared by me, and unread dots beside several rows

Shared home lists every shared document with its type, folder, author, and when you last looked at it.

* **Sort by any column:** Name, type, who created it, when it was last edited, when you last viewed it, and which folder it lives in. * **Filter to what matters:** **All**, **Favorites**, **Unread**, **Recently opened**, **Shared with me**, and **Shared by me**, with a count on the unread filter. * **Narrow further:** Filter by type, by person, or by folder, and search across every shared document. * **List or tiles:** Switch between the table above and a tile view from the toggle at the top right. ### Favorites, and what changed since you were last here
A shared folder in the Collaboration sidebar, with gold stars marking three favorited files and blue dots marking two files that changed since they were last opened

A gold star marks a favorite. A blue dot marks a document that changed since you last opened it.

* **Favorites:** Star the documents you keep coming back to and reach them from the **Favorites** filter. Starred files show a gold star wherever they appear. * **Changed since you were away:** A blue dot marks each shared document that changed since you last opened it. Opening the document clears the dot. * **New and recently updated:** Use the **Unread** and **Recently opened** filters to catch up on what moved while you were away, sorted by the last change. The Collaboration sidebar also provides shared folders, search, drag-and-drop organization, and **All**, **Favorites**, and **Updated** filters. ### Open shared documents in a browser Shared markdown documents also open at [console.nimbalyst.com](https://console.nimbalyst.com), where teammates can edit them live and comment without installing the desktop app. See [Web Console](/team-collaboration/web-console). # Collaborative Trackers Share one tracker board across your team. Teammates and their locally running AI agents keep the same bugs, features, and plans current. ## One shared board your team and its agents keep current Bugs, features, tasks, plans, and decisions live on shared Trackers in the same workspace as your docs. Teammates and their local agents update the same items in real time or asynchronously, so the board reflects what is actually happening. See [shared trackers in Nimbalyst Teams](https://nimbalyst.com/teams/trackers/) for how the shared board works.
A shared tracker board grouped into tag columns such as API, mobile, reliability, and authentication

Group shared work by tag to see plans across areas and milestones.

### One board, everyone on it
A shared task board with To Do, In Progress, In Review, and Done columns

Use kanban stages, lists, filters, and saved views to organize shared work.

* **Real-time and multiplayer:** The board updates live as people and agents change items, with no refresh or manual synchronization. * **Kanban with your stages:** Move work across the stages you define, from backlog to done, on a shared kanban board. * **Recently changed:** See what moved recently, with a marker on items that changed since you last looked. The tracker also includes a sortable list, filters, saved views, and a tag board. ### Your agents and your team keep it up to date
A tracker item detail kept up to date with a linked session, status, priority, owner, and written content

Open an item to see its current fields, content, owner, and the session working on it.

* **Agents update the board:** Claude Code and Codex agents can create items, change status, and update many trackers as they work. * **People edit too:** Teammates edit the same items by hand, so the board stays accurate whether a person or agent made the change. * **Comments and full history:** Every item keeps a threaded discussion and a record of what changed and who changed it. Enable or disable agent Tracker tools per project under **Settings > Project > Trackers > AI Agent Access**. ### Track any kind of work
The tracker sidebar with configurable types including Modules and Initiatives, and an Authentication module open with child features and fields

Create tracker types and relationships that match how your team organizes work.

* **Bugs, features, and your own types:** Use built-in trackers or define custom types with the fields you need. * **Hierarchy and links:** Break work into parent and child items and link related items across trackers. * **Fields that fit:** Give each type its own fields, statuses, owners, tags, dates, priorities, and progress. See [Custom Tracker Types](/task-management/custom-tracker-types) and [Linking Tracker Items](/task-management/linking-tracker-items). ### A collaborative document inside every item Each full tracker item has a rich body the team edits together, so the plan and discussion live with the task.
A tracker item with a collaborative rich-text body, including an Excalidraw diagram and mockup embedded inline

Write the plan in the item and embed diagrams, mockups, images, and other project files.

* **Write the plan in place:** Draft the spec, repro steps, decision, or rollout plan inside the item. * **Diagrams and mockups too:** Add diagrams, mockups, images, data models, and spreadsheets so the full picture sits with the work. * **Edited together:** The item body is collaborative, so teammates and agents work on it in the same place. ### Every item is wired into the work An item connects to the sessions working it, the parent and child items around it, and the documents that reference it.
An initiative showing its parent, child item, tags, content, and linked session

Build a hierarchy around the work and link the session, source file, and pull request that belong to it.

* **Hierarchy and linked sessions:** Break work into parent and child items, and connect each one to the session working it, the file it came from, and the pull request that closes it.
An agent session reporting updates to linked tracker items, with those items visible in the Trackers panel

The agent updates linked items while it works and reports the changes in the session.

* **Updated from the session:** Claude Code and Codex agents change linked items as they work, so a session and its tracker items stay in step.
A launch-readiness document containing live tracker reference pills with item keys, titles, and statuses

Reference live tracker items in a document so their current status stays beside the plan.

* **Tracker pills in your docs:** Reference an item in any document with a live pill that shows its status and links back to the board. Use **Link Existing**, **Launch Session**, or ask the agent to link the current session when that relationship belongs in the item's history. ### Keep trackers private or share them, and organize by tag
A tracker board grouped by tag, with columns for areas such as API, mobile, reliability, and authentication

Keep personal trackers local, promote team trackers to shared, and group the shared board by tag.

* **Local trackers:** Track your own work in local trackers that stay on your machine. * **Shared trackers:** Promote a tracker to shared so the whole team and its agents work on the same board. * **Board by tag:** Group the board by tag to slice work by area, milestone, or any other label. #### Choose a sync policy per tracker type Sharing is decided per tracker type, not all-or-nothing, under **Settings > Project > Trackers > Team Sync Policy**. Changes apply to every member of the team.
The Team Sync Policy panel listing tracker types such as Plans, Decisions, Bugs, Tasks, Ideas, Milestones, and Releases, each with an item count and a Local, Shared, Hybrid selector, with Override badges on several rows

Each tracker type is Local, Shared, or Hybrid, with its current item count beside it.

* **Shared:** Items sync to all team members in real time. The row reads *Visible to all team members*. * **Local:** Items stay on your machine only. The row reads *Only visible to you*. * **Hybrid:** Each item carries its own sharing choice, so one tracker type can hold both team and private work. An **Override** badge marks a type whose settings differ from the default. Use the pencil to edit it and the revert arrow to return it to the default. Custom types you defined yourself can be deleted from this panel. Inline `#type[...]` items stay local until they are promoted to full items. Shared items show their synchronization state, and list view can display the optional **Shared** column. Shared Tracker data flows through Nimbalyst's Cloudflare sync service and is encrypted in transit and at rest. Local and unshared items remain outside the team workspace. # Web Console (console.nimbalyst.com) Open your team's shared documents in a browser at console.nimbalyst.com, edit them live with teammates, leave comments, and manage your organization. The Nimbalyst Web Console at [console.nimbalyst.com](https://console.nimbalyst.com) opens your team's shared documents in a browser. No install, no local setup, and the same collaboration service and permissions as the desktop app. It exists so the people who need to read and respond to your work do not need to become Nimbalyst users first. Write a plan in the desktop app, share it with your team, and a teammate can open the link, follow your live edits, and leave comments from any browser. {% hint style="info" %} The console is part of Nimbalyst Teams, which is in **beta**. Expect bugs. Organizations are free during beta and will require a paid Nimbalyst Teams subscription after launch. {% endhint %} They can edit it too. Editing runs in both directions: a teammate with edit access types straight into the same document you are in, and their changes land in your desktop app as they make them. You each see the other's cursor while you work.
A shared markdown plan open in the browser editor, with a teammate's labeled cursor in the document, a comments button showing four threads, and an Open in desktop link

A shared plan open in a browser, with a teammate editing alongside you.

### What you can do in a browser * **Open shared documents.** Browse your organization's shared document tree, folders, and projects. * **Edit live.** Shared markdown documents are fully editable, with everyone's changes syncing in real time. * **See who else is here.** Live labeled cursors show each teammate editing alongside you, colored per person. * **Comment on the text.** Select a passage, add a comment, reply, resolve, and mention teammates with `@`. * **Manage your organization.** Billing, roles, invitations, security posture, and organization lifecycle. The browser is a companion to the desktop app rather than a replacement for it. See [What the browser cannot do](#what-the-browser-cannot-do) for the specifics. ### Signing in The console uses the same account as the desktop app. Two ways in: 1. **Continue with email** sends a magic link to your work address. 2. **Continue with Google** uses your connected Google identity.
The Nimbalyst Web Console sign-in screen, with a work email field and a Continue with Google button

Sign in with the account connected to your organization.

If your account belongs to more than one organization, you choose which one to open after signing in. You can switch organizations later from the profile menu at the bottom of the left navigation, without signing in again. Browser sessions last seven days and are scoped to one signed-in account. If you follow a link to a document while signed out, the console remembers where you were headed and returns you there after you sign in.
The console sign-in screen showing an alert reading: Your session is not active. Sign in to continue to this organization link.

Following a shared link while signed out preserves your destination.

### Accepting an invitation When an organization admin invites you by email, the invitation link brings you to the console and accepts your membership. Because the full Nimbalyst experience lives in the desktop app, the console then offers to open Nimbalyst for you, with a download link if you do not have it yet. **Continue in the browser instead** takes you to the shared documents. ### Working in shared documents The left navigation has two modes: **Shared Docs** and **Organization**.
The web console listing an organization's shared documents in a table with Name, Type, Created by, Last edited, and Folder columns, beside a folder tree

Every shared document in the project, with its type, folder, author, and last edit.

In Shared Docs you get a document tree on the left, a tab strip across the top for the documents you have open, and a breadcrumb showing organization, project, folder, and document. The tree and the comments panel are both resizable by dragging their edges, or with the arrow keys once a handle is focused. Double-click a handle to reset it. If your organization has several projects, the project switcher sits at the top of the tree and shows how many shared documents each one holds. Your open tabs, panel widths, and last-used project are remembered in the browser, so returning to the console puts you back where you were. #### Editing together Shared markdown documents are live. Above the document, a status pill reports the connection (**Live**, **Connecting**, **Reconnecting**, **Offline**, or **Read-only**) and a save chip reports whether your changes are saved. The document stays hidden until the first sync completes, so you never type into what looks like an empty document while the server copy is still loading. Each teammate editing with you appears as a colored cursor labeled with their name. Screen readers announce people joining, leaving, and editing. Edits go both ways. Anyone whose organization role allows it can type into the document from the browser, and those changes reach the desktop app and every other open browser as they happen. Viewers and guests are held to reading. #### Commenting Select any text in the document and choose **Add comment**. Comments dock in a panel on the right, which you can toggle from the floating comments button. The button carries a count when the panel is closed. * Reply to a thread, then **Resolve** it once it is handled. * Type `@` in the composer to mention a teammate. * Mentioned teammates are notified.
A shared plan open in the browser with the comments panel docked on the right, showing four threads anchored to passages, each with an author, a timestamp, a reply box, and Resolve and Delete actions

Comments anchor to the passage they are about, with replies and resolve in the docked panel.

Commenting depends on your organization role. Owners, admins, and members can write comments. Viewers and guests can read but not comment. Comments are also withdrawn on any document the server has made read-only for you. #### Opening in the desktop app Every document has an **Open in desktop** link in its status bar that hands the document off to Nimbalyst on your machine. Documents the browser cannot handle offer the same handoff more prominently. ### Organization administration Switch the left navigation to **Organization** for five sections: | Section | What it covers | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Overview** | Your role, membership type, and every project in the organization | | **Billing** | Current plan, status, seat count, and period end; seat changes and payment management run through the billing provider, and the console never sees card details | | **Roles and members** | The member list, each person's role, role changes, member removal, and email invitations | | **Security** | Data custody mode, encryption key epoch and fingerprint, and the twenty most recent organization audit events | | **Danger zone** | Merge this organization into another, or delete it permanently | Deleting an organization requires typing its exact name. Role changes and every other privileged write are checked again by the collaboration service, so the console never grants access on its own. ### What the browser cannot do The console is deliberately narrower than the desktop app. Today: * **Only markdown documents open.** Mockups, diagrams, data models, mind maps, spreadsheets, and code files show as unsupported and need the desktop app. * **Trackers are desktop-only.** The shared tracker boards do not open in a browser. * **Documents above 8 MiB of collaborative state** are too large for a browser tab and offer a desktop handoff instead. * **No document history or version view.** * **No export or embedding.** * **No promoting a local file to the team.** Sharing a local file to your organization happens in the desktop app. * **No personal (non-team) documents**, and no read receipts. * **No creating projects or organizations.** The console works with organizations and projects that already exist. ### Troubleshooting | What you see | What it means | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **No access to this organization** | The link points at an organization your account cannot open. Check you signed in with the right address. | | **Organization access was removed** | Your membership ended while you had the document open. Live access stops immediately. | | **Document not found** | The document was deleted, or it left the project you have access to. | | **Your session expired** | Sign in again. Your destination is preserved. | | **Shared documents are unavailable** | The collaboration service could not be reached. Your route is kept, so a retry returns you to the same place. | | **This document is too large to edit in a browser** | Nothing is lost. Open it in the desktop app, which has no such limit. | | **This document is now read-only** | The server rejected an edit. The rejected change was not saved. | | **This document could not be opened** | The first sync did not complete. Nothing you type would be saved, so editing stays off until the connection returns. **Try again** retries it. | If a sign-in link fails, it has usually been used already or expired. Request a fresh one. ### Related * [Team Collaboration Overview](/team-collaboration/overview) * [Collaborative Documents](/team-collaboration/documents) * [Set Up Nimbalyst Teams and Organizations](/team-collaboration/setup-teams-and-orgs) # Set Up Nimbalyst Teams Create a Nimbalyst organization, attach a project to it, invite teammates, and manage members, projects, messaging, and encryption from the organization management dialog. Nimbalyst Teams has two layers. An **organization** holds the member roster, billing, messaging settings, and encryption. A **project** is one git repository attached to that organization, with its own shared documents and trackers. Nimbalyst uses the project's git remote as its identity, so teammates who open clones of the same repository connect to the same team project. Setup lives in two places: **Settings** for your account and the current project, and the **organization management dialog** for everything organization-wide. {% hint style="info" %} Nimbalyst Teams is in **beta**. Expect bugs. Organizations are free during beta and will require a paid Nimbalyst Teams subscription after launch. {% endhint %} ### Before you begin Make sure that: * You have opened the correct project in Nimbalyst. * The project has a git remote named `origin` if you want automatic project matching. * You are signed in to Nimbalyst under **Settings > Account > Accounts**. * Teammates will sign in with the email addresses you invite. ### Create an organization Your signed-in accounts and the organizations each one belongs to are listed under **Settings > Account > Accounts**. Use **New organization** here to start one, or **Manage** to open the management dialog for an existing one.
Settings, Account, Accounts, showing the signed-in email with its organizations, each with an Admin or Owner role badge, a Manage button, and a New organization button

Every organization your signed-in account belongs to, with your role in each.

Each row shows your role, **Owner** or **Admin**, and how many projects the organization holds. The person who creates an organization becomes its owner. You can also **Add another account** and belong to organizations under more than one identity. ### Attach this project to an organization Project-level sharing lives under **Settings > Project > Sharing**. This panel is where a repository becomes a team project.
Settings, Project, Sharing, showing the Organization section with the signed-in account and the organization attachment controls

Settings > Project > Sharing attaches the current repository to an organization.

To create a team from this project: 1. Open **Settings**. 2. Select **Project** at the top. 3. In the sidebar, select **Sharing**. 4. Click **Create Team**. 5. Confirm the team name and detected git remote. If you have more than one Nimbalyst account, choose the account that should own the team. 6. Click **Create Team**. Nimbalyst creates the organization, registers this repository as its first project, and prepares the team's encryption. If you already administer an organization, use **Add to an existing organization** instead of creating another one: 1. Select the organization. 2. Click **Add Project**. 3. Confirm that this workspace appears as a project under the organization. Each project has its own tracker and document space. Projects in the same organization share the member roster, messaging settings, and encryption. ### Manage the organization Organization administration is a dialog that opens in whatever window you are already in, rather than a fourth Settings scope. Open it any of these ways: * **Organization switcher** in the navigation gutter, then **Manage organization…**. * **Settings > Account > Accounts**, then **Manage** on the organization's row. * The organization row in the **account menu** at the bottom of the navigation gutter. * **Settings > Project > Sharing**, then **Open organization**, which lands on the **Projects** page. * The pending-invitations row in the organization switcher, which lands on **Members**. The dialog's sidebar holds **Members**, **Projects**, and **Settings**, plus **Billing** and **Danger zone** for owners and admins. Plain members do not see the last two. **Window > Organization Messages** (**Cmd/Ctrl+Alt+O**) is a different surface. It opens the messaging window for rooms and direct messages, not the administration dialog. #### Members and roles **Members & Roles** carries a `beta` chip while roles and verification settle. Under **Members**, enter a teammate's email address and click **Invite**. The invite stays pending until that person joins. An owner or admin can revoke a pending invite, remove a member, or move a member between **Admin** and **Member**. This page also shows identity fingerprints so teammates can verify one another. Compare fingerprints through a separate trusted channel before marking someone verified. A changed fingerprint means the member's device identity changed, so verify it again before trusting the new key. Owners and admins can re-share a team key when a verified member changes devices. #### Projects **Projects** lists every project in the organization, including ones you have not cloned locally.
The organization management dialog Projects page, listing a git-linked project with a Manage access button and a reserved Organization Space entry

Every project in the organization, whether or not you have a local clone.

Use **Manage access** to control who can reach a project's shared documents and trackers. To add a project, open it in Nimbalyst and go to **Project Settings > Sharing > Add to an existing organization**. **Organization Space**, a shared area for documents and trackers that belong to the organization rather than to a single repository, is reserved for a later release. #### Settings: messaging, security, and encryption **Settings** covers organization-wide configuration. Members can view this page; only owners and admins can change it.
The organization management dialog Settings page, showing the organization name with a Rename action, Messaging toggles for Rooms and Direct messages, a who-can-create-rooms selector, and a Security panel reading Encrypted by Nimbalyst with encryption active

Rename the organization, control built-in messaging, and check encryption status.

* **Organization:** Rename the organization. The owner's email address is shown beneath it. * **Messaging:** Turn **Rooms** and **Direct messages** off for organizations that chat elsewhere. The Inbox, document comments, and tracker comments are unaffected. **Who can create rooms** offers **Any member** or **Organization admins only**, and is unavailable while Rooms is off. * **Security:** Team data is encrypted in transit and at rest with keys managed by Nimbalyst. This is separate from personal sync encryption, whose keys remain only on your devices. **Billing** and **Danger zone** round out the dialog. Details on encryption, data isolation, and SOC 2 are on the [security page](https://nimbalyst.com/features/security/). ### Join an invited team The invited person should: 1. Sign in to Nimbalyst with the invited email address. 2. Open a clone of the team's repository in Nimbalyst. 3. Open **Settings > Project > Sharing**. 4. Click **Join Team** on the invitation card. Because the repository remote matches the team project, the shared documents and trackers become available once the invitation is accepted and the encryption key is ready. If the invite does not appear, confirm the signed-in email address and the repository's `origin` remote first. ### Use multiple accounts Add or reconnect accounts under **Settings > Account > Accounts**, then switch between them from the account menu in the navigation footer. When you create an organization, add a project to one, or create a shared link, Nimbalyst lets you choose which signed-in account owns that action. Organization membership and project access continue to use that account even when another account is selected for personal mobile sync. If an invitation or team project is missing, first switch to the account whose email address received the invitation. ### Which scope does what | You want to… | Go to | | --------------------------------------------------------- | ---------------------------------- | | Sign in, add an account, or start an organization | **Settings > Account > Accounts** | | Attach this repository to an organization, or join a team | **Settings > Project > Sharing** | | Choose which tracker types sync to the team | **Settings > Project > Trackers** | | Invite people, set roles, verify fingerprints | **Organization dialog > Members** | | Manage project access across the organization | **Organization dialog > Projects** | | Rename the org, control messaging, check encryption | **Organization dialog > Settings** | | Chat in rooms and direct messages | **Window > Organization Messages** | Team content is authorized with the active team membership. Personal session and mobile sync use a separate personal identity and do not grant access to team documents or trackers. See [Application, Account, and Project Settings](/setup-nimbalyst/settings-scopes) for the complete settings model. ### Start collaborating After the team is connected: * Open **Collaboration** mode to create and organize shared documents. * Right-click a supported local file and choose **Share to Team**. * Open **Trackers** to share hybrid items or work in tracker types configured as shared. Continue with [Collaborative Documents](/team-collaboration/documents) and [Collaborative Trackers](/team-collaboration/trackers). # Extension System & Marketplace Install Nimbalyst extensions from the marketplace registry to add editors, AI tools, and panels, or publish an extension you built yourself. Install Nimbalyst extensions from a live marketplace registry, build your own extensions to Nimbalyst with a hardened extension SDK. See all the extensions below and make your own. The full list of published extensions, with screenshots, is at [nimbalyst.com/extensions](https://nimbalyst.com/extensions/). ## What Are Extensions? Extensions are add-ons that give Nimbalyst new capabilities. Each extension can add custom editors for new file types, AI tools that let your agent interact with your content, sidebar panels, settings pages, themes, keyboard shortcuts, and more. Extensions work seamlessly alongside Nimbalyst's built-in editors. When you open a file, Nimbalyst checks if any extension handles that file type and loads the right editor automatically. Extensions have full access to Nimbalyst's theming system, so they always match your current look and feel. ## Extensions in the Marketplace Go to **Settings > Application > Marketplace** to browse and install extensions.
Extension Marketplace showing featured extensions and category filters

The Extension Marketplace in Settings, showing featured extensions, search, and category filters

Click any extension card to see its full details, screenshots, permissions, and install button.
Extension detail modal showing description, screenshots, and install button

Extension detail view with description, highlights, screenshots, and install controls

### What's in the catalog The bundled catalog is updated as extensions are released, so use the Marketplace for the current list, versions, screenshots, and permissions. Recent additions include: * **Electronics Studio** — work with tscircuit and Circuit JSON in schematic, PCB, assembly, and 3D views; run simulations; and export manufacturing and review artifacts. * **Replicad CAD** — build parametric 3D models in TypeScript with a live B-rep preview, STEP import and export, geometry inspection, and printability tools. Marketplace cards show whether an extension is installed and whether an update is available. ### Managing Installed Extensions View all installed extensions under **Settings > Application > Installed**. This is the single panel for everything you have installed — marketplace, GitHub, local dev, and built-in extensions all show up here, each with a colored source pill so you can tell them apart at a glance.
Installed Extensions panel showing all active extensions with details

The Installed Extensions panel shows every active extension, its permissions, and contributed AI tools

Each row has an enable toggle and an indicator if an update is available. Click an extension to open the detail pane, which includes its AI tools, permissions, file path, and **Update**, **Repository**, **Reveal**, and **Uninstall** actions. The Marketplace itself is now Discover-only. When updates are available, an "Installed (N) — M updates" link at the top of Marketplace takes you to the Extensions panel. ### Themes from Extensions Extensions can ship themes. Any theme contributed by an installed extension shows up under **Settings > Application > Themes** in an **Extension Themes** group, and in the gutter theme popup, alongside the built-in themes. Pick one and Nimbalyst applies it just like a first-party theme. If you later disable or uninstall the extension that provided the active theme, Nimbalyst falls back gracefully so your workspace stays usable. ### Installing from GitHub At the bottom of the Marketplace discover page, you can paste a GitHub repository URL to install any extension directly from source. The repository must contain a valid `manifest.json` file. ## Build Your Own Extensions Extensions are self-contained packages that declare their file types, editors, and UI contributions via a manifest. You can build extensions that do everything the built-in ones do. **What you can build:** * **Custom editors** for any file type (spreadsheets, diagrams, visual tools) * **AI tools** that Claude can use to read and modify your editor's content * **Panels** for sidebar views, fullscreen modes, or floating windows * **Application or Project settings pages** with project-aware context * **Project filesystem access** for editors that manage related files * **Typed tracker item pickers and live references** * **Themes, slash commands, file icons, and new file templates** **How development works:** * The **Extension Dev Kit** (bundled with Nimbalyst) scaffolds a new extension project with a starter template, hot reload, and MCP tools for build/install/reload from inside Nimbalyst * Editors integrate through the **EditorHost contract** (load/save, dirty state, theme, external change handling) so custom editors behave exactly like first-party ones * Use the full **Extension SDK** -- clipboard, screenshot export, AI and network permissions, and access to the same MCP tooling that first-party extensions use For full technical documentation on building extensions, see [Building Your Own Extensions](/extensions/building-extensions). # Building Your Own Extensions Build your own Nimbalyst extension with custom editors, AI tools, panels, and themes, packaged with a manifest that declares what it adds. Build extensions that add new capabilities to Nimbalyst -- custom editors, AI tools, panels, themes, and more. Extensions are self-contained packages with a manifest that declares their contributions. Nimbalyst is open source, and the built-in extensions live alongside the app source in [github.com/nimbalyst](https://github.com/nimbalyst). The fastest way to learn the extension API is to read those built-in extensions. The [extensions feature page](https://nimbalyst.com/features/extensions/) covers what extensions can contribute to the app. ## What Can Extensions Do? * **Custom Editors** -- New ways to view and edit file types (spreadsheets, diagrams, 3D models) * **AI Tools** -- Tools that Claude can use to interact with your extension * **AI Completions** -- Call chat models (Claude, OpenAI, LM Studio) directly from your extension * **Panels** -- Sidebar panels, fullscreen views, or floating windows * **Settings Pages** -- Application- or Project-scoped settings with repository context * **Project Filesystem Access** -- Read and update related project files from a custom editor * **Tracker References** -- Add typed item pickers and live tracker reference chips * **Themes** -- Custom color themes * **Slash Commands** -- Commands users can invoke from the chat * **File Icons** -- Custom icons for file types in the sidebar * **New File Types** -- Add entries to the "New File" menu ## Quick Start The recommended workflow is to create and iterate on extensions from inside Nimbalyst: 1. Enable **Extension Dev Tools** in **Settings > Application > Advanced** 2. Use `File > New Extension Project` or ask Claude to run `/new-extension` 3. Describe the extension you want Claude to build from the starter scaffold 4. Ask Claude to build and install the extension with `extension_build` and `extension_install` 5. Use `extension_reload` for rebuild + reinstall during iteration See [Getting Started](/extensions/building-extensions/getting-started) for a step-by-step walkthrough. ## Project Structure A typical extension project: ``` my-extension/ manifest.json # Extension metadata and contributions package.json # npm dependencies tsconfig.json # TypeScript configuration vite.config.ts # Build configuration src/ index.ts # Extension entry point (activate/deactivate) components/ # React components styles.css # Scoped styles ``` ## Development Workflow 1. **Create** -- Use `/new-extension` inside Nimbalyst or copy a starter project 2. **Develop** -- Edit files in your extension project 3. **Build** -- Claude uses `extension_build` to compile 4. **Install** -- Claude uses `extension_install` to load it 5. **Test** -- Open a file with your extension's file type 6. **Iterate** -- Claude uses `extension_reload` for hot updates ## Core Concepts ### The Extension Manifest Every extension needs a `manifest.json` that describes what it provides. At minimum: ```json { "id": "com.example.my-editor", "name": "My Editor", "version": "1.0.0", "main": "dist/index.js" } ``` See [Manifest Reference](/extensions/building-extensions/manifest-reference) for the complete schema. ### The EditorHost Contract Custom editors receive a `host` prop that handles all communication with Nimbalyst -- loading and saving files, tracking dirty state, theme changes, and AI diff mode. The `useEditorLifecycle` hook wraps the host into a single, clean API. See [Custom Editors](/extensions/building-extensions/custom-editors) for the full guide. ### AI Tool Integration AI tools let Claude interact with your editor programmatically. Define tools with a name, description, input schema, and handler function. Claude reads the description to decide when to call your tool. See [AI Tools](/extensions/building-extensions/ai-tools) for examples and best practices. ### Permissions Extensions declare the capabilities they need: | Permission | What It Grants | | ------------ | ---------------------------------------------------------- | | `filesystem` | Read and write files in the workspace | | `ai` | Register AI tools and call chat/completion models directly | | `network` | Make HTTP requests to external services | ## Documentation | Document | Description | | ------------------------------------------------------------------------ | ----------------------------------------- | | [Getting Started](/extensions/building-extensions/getting-started) | Create your first extension in 10 minutes | | [Custom Editors](/extensions/building-extensions/custom-editors) | Build editors for new file types | | [AI Tools](/extensions/building-extensions/ai-tools) | Add tools that Claude can use | | [Manifest Reference](/extensions/building-extensions/manifest-reference) | Complete manifest.json schema | | [API Reference](/extensions/building-extensions/api-reference) | TypeScript types and interfaces | ## Prerequisites * Nimbalyst with Extension Dev Tools enabled (**Settings > Application > Advanced**) * Node.js 18+ * Basic knowledge of React and TypeScript ## Built-in Extension Examples Study the built-in extensions for patterns and best practices: | Extension | File Types | Notable Patterns | | --------------- | ---------------- | ------------------------------------------ | | Excalidraw | `.excalidraw` | Imperative API via refs, 19 AI tools | | CSV Spreadsheet | `.csv`, `.tsv` | RevoGrid with custom save, formula support | | DataModelLM | `.datamodel` | Zustand store, screenshot export | | MockupLM | `.mockup.html` | iframe preview, AI generation | | SQLite Browser | `.db`, `.sqlite` | Panel-based with Jotai, 9 AI tools | These are all in `packages/extensions/` in the [Nimbalyst repository on GitHub](https://github.com/nimbalyst). # Getting Started Create your first Nimbalyst extension step by step, ending with a working custom editor for a new file type built on the extension SDK. This guide walks you through creating your first Nimbalyst extension. By the end, you'll have a working extension that registers a custom editor for `.hello` files. ## Recommended: Create It From Inside Nimbalyst The intended workflow is to scaffold and iterate on extensions from inside Nimbalyst: 1. Enable Extension Dev Tools in **Settings > Application > Advanced** 2. Use `File > New Extension Project` or `Developer > New Extension Project` 3. Or ask Claude to run `/new-extension minimal ~/my-first-extension "Hello Editor"` 4. Ask Claude to build and install it with `extension_build` and `extension_install` 5. Use `extension_reload` while iterating The rest of this guide shows the manual scaffold path if you prefer to create the project yourself. ## Prerequisites 1. **Enable Extension Dev Tools** - Go to **Settings > Application > Advanced** and enable "Extension Dev Tools" 2. **Node.js 18+** - Required for building extensions ## Step 1: Create the Project Create a new directory for your extension: ```bash mkdir my-first-extension cd my-first-extension npm init -y ``` ## Step 2: Install Dependencies ```bash npm install --save-dev typescript vite @nimbalyst/extension-sdk npm install react ``` ## Step 3: Create the Manifest Create `manifest.json` - this tells Nimbalyst about your extension: ```json { "id": "com.example.hello-editor", "name": "Hello Editor", "version": "1.0.0", "description": "A simple custom editor for .hello files", "main": "dist/index.js", "apiVersion": "1.0.0", "contributions": { "customEditors": [ { "filePatterns": ["*.hello"], "displayName": "Hello Editor", "component": "HelloEditor" } ], "newFileMenu": [ { "extension": ".hello", "displayName": "Hello File", "icon": "description", "defaultContent": "Hello, World!" } ] } } ``` `apiVersion` is currently optional but recommended. ## Step 4: Create the Vite Config Create `vite.config.ts`: ```typescript import { defineConfig } from 'vite'; import { createExtensionConfig } from '@nimbalyst/extension-sdk/vite'; export default defineConfig( createExtensionConfig({ entry: './src/index.ts', }) ); ``` ## Step 5: Create the TypeScript Config Create `tsconfig.json`: ```json { "compilerOptions": { "target": "ES2020", "module": "ESNext", "moduleResolution": "bundler", "jsx": "react-jsx", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "declaration": true, "outDir": "dist", "rootDir": "src" }, "include": ["src/**/*"] } ``` ## Step 6: Create the Extension Entry Point Create `src/index.ts`: ```typescript import type { ExtensionContext } from '@nimbalyst/extension-sdk'; import { HelloEditor } from './HelloEditor'; // Export components that the manifest references export const components = { HelloEditor, }; // Called when the extension is loaded export function activate(context: ExtensionContext) { console.log('Hello Editor extension activated!'); } // Called when the extension is unloaded export function deactivate() { console.log('Hello Editor extension deactivated'); } ``` ## Step 7: Create the Editor Component Create `src/HelloEditor.tsx`: ```tsx import React, { useRef, useReducer } from 'react'; import { useEditorLifecycle } from '@nimbalyst/extension-sdk'; import type { EditorHostProps } from '@nimbalyst/extension-sdk'; export function HelloEditor({ host }: EditorHostProps) { const textRef = useRef(''); const textareaRef = useRef(null); const [, forceRender] = useReducer((x) => x + 1, 0); const { isLoading, error, markDirty } = useEditorLifecycle(host, { applyContent: (content: string) => { textRef.current = content; if (textareaRef.current) { textareaRef.current.value = content; } forceRender(); }, getCurrentContent: () => textRef.current, }); const handleChange = (e: React.ChangeEvent) => { textRef.current = e.target.value; markDirty(); }; if (error) return
Error: {error.message}
; if (isLoading) return
Loading...
; return (

Hello Editor

Editing: {host.filePath}