> For the complete documentation index, see [llms.txt](https://docs.nimbalyst.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nimbalyst.com/task-management/overview.md). # Tracker Overview Nimbalyst has a built-in issue tracker that keeps bugs, features, tasks, and plans in your project, next to your docs and AI sessions. Nimbalyst's tracker manages work items, bugs, tasks, features, ideas, decisions, and plans, directly alongside your AI sessions and project files. Use it when you want the work you are tracking and the agents doing the work in the same place, instead of copying between a separate ticket tool and your editor. Each item type has its own status workflow, fields, and icon, and you can define custom types to fit your project. 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 personal to you 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.md).

The tracker kanban board showing a Bugs board with To Do, In Progress, In Review, and Done columns, filter chips and type list in the left sidebar — The kanban board for the Bugs type. The sidebar holds filters and one entry per tracker type; the toolbar has search, sort, import, and +New.

## 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.

The 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 Without a tracker, 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, with 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 seven built-in item types: * **Bug**: Defects and issues to fix * **Task**: General work items and to-dos * **Idea**: Early-stage ideas before they become work * **Decision**: Architectural and product decisions with context * **Plan**: Larger initiatives with progress tracking * **Milestone**: Groups of work organized around a target date * **Release**: Groups of work shipped through an alpha or stable channel Each type has its own statuses, fields, and color-coded icon. You can also define [custom tracker types](/task-management/custom-tracker-types.md). ### How items get created Items can come from several 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 items are stored Depending on how you create it, an item lives in one of three places: * In Nimbalyst's local database, as a native tracker item * Inside a markdown file, if you created it with an inline `#type[...]` tag * As a markdown file itself, if the file carries `trackerStatus` frontmatter Items you share also sync through the team's tracker space. Sharing an individual item is explicit; a tracker type that is shared with the team shares all of its items by design. See [Sharing Plans and Trackers](/task-management/sharing-plans-and-trackers.md). ### Learn more * [Item Types and Fields](/task-management/item-types-and-fields.md): Built-in types, statuses, and field definitions * [Kanban and List Views](/task-management/kanban-and-list.md): Board mechanics, filtering, and saved views * [Item Detail](/task-management/item-detail.md): Editing fields, comments, and activity logs * [Creating Items](/task-management/creating-items.md): All of the creation paths with examples * [AI Integration](/task-management/ai-integration.md): How agents create, update, and query items * [Commits and Sessions](/task-management/commits-and-sessions.md): Linking items to git history and conversations * [Custom Tracker Types](/task-management/custom-tracker-types.md): Define your own types * [Local Config](/task-management/local-config.md): Project-level settings and file organization --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.nimbalyst.com/task-management/overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.