Why I Switched My Workflow to TrackDown
When TODOs aren't enough, and JIRA is too much...
After months of trying to make Claude Code's built-in todos work for serious development, I finally admitted they weren't cutting it. The todos are fine for quick reminders—"fix this typo" or "add error handling here"—but they're too ephemeral for real project management. They disappear into conversation history, can't be prioritized, and offer no way to track progress across sessions.
I needed something more substantial. Something that could bridge the gap between Claude Code's lightweight task suggestions and proper project management without the overhead of traditional systems.
That's when I discovered TrackDown.
What TrackDown Actually Is
TrackDown isn't another SaaS platform fighting for your subscription dollars. It's a lightweight issue tracking system that stores tickets as markdown files directly in your Git repository. Think of it as "git clone for your tickets"—the tagline that perfectly captures what makes it different.
Created by Martin Goellnitz for distributed teams who were tired of centralized issue trackers, TrackDown treats project management data as a first-class citizen in version control. Issues live in a single issues.md file that travels with your codebase, enabling complete offline functionality and eliminating the "context switching tax" of web-based tools.
The user base tells the story: small distributed development teams (2-10 developers), open source maintainers, and developers working in disconnected environments who prioritize simplicity and control over feature breadth.
The GitHub Issues Problem
Before TrackDown, I was using GitHub Issues for serious project tracking. The integration seemed obvious—issues live next to code, developers are already in the GitHub workflow, and the API enables automation.
But the performance was killing me.
Simple queries took 5-10 seconds. Creating pull requests in repositories with 40,000+ commits could take 2 minutes. The web interface required constant context switching between my editor and browser. And when working offline—whether on flights or just in focused deep work sessions—the system became completely inaccessible.
GitHub Issues works well for public repos with distributed contributors, but for personal projects and client work, the overhead wasn't justified by the benefits.
The Markdown Revolution in AI Development
What pushed me toward TrackDown wasn't just the performance issues—it was recognizing how markdown has become the lingua franca of AI-assisted development.
Research shows markdown is 16% more token-efficient than JSON or XML formats. More importantly, large language models are extensively trained on markdown content, making them naturally proficient at parsing and generating it. When Claude Code reads a TrackDown issue, it understands the structure intuitively: titles, descriptions, status markers, and priority indicators all parse cleanly.
This aligns with a broader trend I've been tracking. Dan Seltzer's markdown-based CRM system, which I covered in "The Convergent Mind," demonstrates how treating markdown as a first-class integration format enables seamless AI workflows. Microsoft's MarkItDown project converts various file formats to markdown specifically for LLM processing. Cloudflare's Workers AI documentation emphasizes markdown conversion as a best practice.
The pattern is clear: markdown isn't just human-readable—it's AI-optimal.
TrackDown in Practice
Setting up TrackDown takes about five minutes. You add a single shell script to your project, run trackdown.sh init, and start creating issues. The learning curve is measured in hours, not weeks.
Issues get stored in issues.md with a simple but effective format:
## Issue #12: Implement user authentication [OPEN] [HIGH]
**Created:** 2025-01-15
**Assigned:** bob@matsuoka.com
Add JWT-based authentication system with:
- Login/logout endpoints
- Token refresh mechanism
- Protected route middleware
**Progress:**
- [x] Research JWT libraries
- [ ] Implement login endpoint
- [ ] Add token validation
- [ ] Write tests
The Git hooks handle status updates automatically. Commits containing "refs #12" mark issues as in-progress. Commits with "fixes #12" close them. Project management data stays synchronized with code changes without manual intervention.
Version-Aligned Project Management
Here's what sold me: TrackDown data lives in your codebase. When I switch Git branches, the issues switch too. When I merge a feature branch, the associated issues update their status. It's like having a time machine for project management data.
This version alignment solves a persistent problem with external issue trackers. GitHub Issues for a three-month-old branch don't reflect the current reality of that branch. TrackDown issues do, because they're stored in the same version control system as the code.
For AI-assisted development, this alignment proves crucial. When Claude Code analyzes a codebase, it can read the current issue context directly from the repository. No API calls, no authentication, no external dependencies. The AI understands what you're working on because the issues are right there in the file tree.
Integration Without Lock-in
TrackDown supports bidirectional mirroring with GitHub, GitLab, Bitbucket, Gitea, and Redmine. You can maintain a local copy of issues while continuing to use web interfaces for stakeholder communication.
The syntax is straightforward: trackdown.sh github <project> <owner> <token> establishes a connection. trackdown.sh mirror synchronizes issues bidirectionally. This acknowledges that many teams can't completely abandon web-based tools due to organizational requirements but still want the benefits of distributed issue tracking.
I've been using this hybrid approach with clients. TrackDown handles my personal workflow and detailed technical tracking. GitHub Issues manages client-facing communication and high-level project status. The mirroring keeps them synchronized without forcing clients to learn new tools.
The Claude Code Integration
While TrackDown doesn't offer direct Claude Code integration (yet), the markdown format creates natural synergies. When Claude Code suggests a todo, I can quickly promote it to a TrackDown issue:
echo "## Issue #$(trackdown.sh next): Fix error handling in auth middleware [OPEN] [MEDIUM]
**Created:** $(date +%Y-%m-%d)
**Assigned:** bob@matsuoka.com
Claude Code identified missing error handling in auth middleware. Need to add proper try/catch blocks and error responses." >> issues.md
Claude Code can also read existing TrackDown issues when analyzing a project. The markdown format provides context that helps the AI understand current priorities and avoid suggesting tasks that are already tracked.
My goal is that Claude Code's "todo" becomes a mix of very lightweight tasks (fix this typo, add this comment) and TrackDown tickets for substantial work. The AI handles immediate suggestions; TrackDown manages the strategic backlog.
Performance That Matters
TrackDown operations are instantaneous because they work with local files. Creating issues, updating status, searching, and filtering all happen in milliseconds rather than seconds. This performance difference isn't just about speed—it's about maintaining developer flow.
The offline capability proves essential for focused work sessions. When I'm in deep development mode, the last thing I want is waiting for web interfaces to load or losing context to authentication timeouts. TrackDown issues are always available, always current, and never require network access.
Small teams report 5-10x faster onboarding with TrackDown compared to enterprise solutions. The learning curve is measured in hours, not weeks. For AI-assisted development where iteration speed matters, this advantage compounds quickly.
The Lightweight Philosophy
TrackDown embodies what one developer called "the anti-JIRA philosophy." No custom workflows, no mandatory fields, no administrative overhead. Issues are markdown files. Status is text. Priority is a tag. The system does exactly what you need and nothing you don't.
This simplicity becomes crucial when working with AI assistants that can generate code at unprecedented speeds. The bottleneck often shifts from development to project coordination. Tools that minimize coordination overhead while maintaining essential functionality provide competitive advantages.
As development teams embrace AI-assisted workflows, the preference for lightweight tools reflects a broader shift in priorities. When AI can handle much of the implementation complexity, developer tools need to get out of the way rather than adding their own complexity.
Should You Switch?
TrackDown works best for:
Small teams (2-10 developers) who value simplicity over features
Projects where offline access matters
Developers comfortable with command-line tools
Teams already using Git for everything else
AI-assisted development workflows where markdown integration provides value
It doesn't work well for:
Large teams requiring complex approval workflows
Stakeholders who need web-based dashboards
Projects requiring detailed time tracking or reporting
Teams that depend on JIRA integrations
Bottom Line
After two weeks with TrackDown, I can't imagine going back to web-based issue tracking for personal projects. The performance, simplicity, and version alignment have eliminated friction I didn't realize I was accepting.
The AI integration potential excites me most. As tools like Claude Code become more sophisticated, having project management data in AI-readable formats will enable new workflows we're only beginning to explore. TrackDown positions me for that future while solving immediate problems today.
The system does exactly what it promises: git clone for your tickets. Sometimes that's exactly what you need.