MIME TODO is a deterministic, spec-first issue tracker that lives inside your SCM repository as a plain-text TODO file. It uses a standards-based MIME format for data storage and integrates with Bugzilla for syncing issues and work logs.
View on Bitbucket | NPM Package
What it does
Instead of a separate issue tracker, your issues live in a TODO file right next to your code. Each issue is stored as a MIME message, making the format both human-readable and machine-parseable. The CLI manages the full issue lifecycle: create, start, done, hold, and cancel.
MIME TODO follows git-based workflow conventions, generating commits as issues move through their lifecycle. It also supports syncing with Bugzilla, so you can push and pull issues and work logs between your local TODO file and a Bugzilla instance.
Key features
- Issue lifecycle management - create, start, done, hold, and cancel issues from the command line
- Git-based workflow - automatic commit conventions as issues change state
- Bugzilla integration - sync issues and work logs with a Bugzilla instance
- Standalone Bugzilla CLI - a REST API client for Bugzilla that works independently
- Module-to-product mapping - configure how local modules map to Bugzilla products
- Read-only views - inspect issues, sprints, and issue lists without modifying state
Using it
Say you’re working on a project and you need to add a login page. You create an issue for it:
mime-todo create --type feature --title "Add login page" --plan "OAuth2 flow with Google provider"
That writes a new MIME entry into your TODO file and commits it. The issue gets an ID, say 1. When you’re ready to work on it, you start it:
mime-todo start 1 --plan "Using passport.js, wiring up the Google strategy first"
Now you do your work. Write code, make commits, the usual. If you have Bugzilla set up, you can push your work log over at any point:
mime-todo push
That syncs your commits to the corresponding Bugzilla bug as comments. It’s context-aware — on an issue branch it pushes work commits, on develop it pushes status transitions.
When you’re done, you close it out:
mime-todo done 1 --summary "Login page with Google and GitHub OAuth"
If something comes up and you need to pause, you can put it on hold instead:
mime-todo hold 1 --reason "Waiting on API design review"
And if the feature gets dropped entirely:
mime-todo cancel 1 --reason "No longer needed after scope change"
You can check on things at any point with mime-todo list or mime-todo show 1. Everything stays in the TODO file, versioned alongside your code.
Design goals
- Spec-first: the TODO file format is defined by a schema, validated with JSON Schema (AJV)
- Deterministic: issue state transitions follow strict rules with no ambiguity
- Repository-native: issues live with the code, tracked by the same SCM
- Standards-based: uses MIME format (RFC 2045) for structured, extensible data storage
Tech stack
TypeScript, Node.js (>=18), Yargs, mailparser, AJV, esbuild, Vitest