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 shows the tracker in context alongside docs and sessions, and 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.

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.

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 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 -- Built-in types, statuses, and field definitions

• Kanban and List Views -- Board mechanics, filtering, and drag-and-drop

• Item Detail -- Editing fields, comments, and activity logs

• Creating Items -- All four creation paths with examples

• AI Integration -- How agents create, update, and query items

• Commits and Sessions -- Linking items to git history and conversations

• Custom Tracker Types -- Define your own types with YAML

• Local Config -- Project-level settings and file organization