Plan, run, and track AI coding work feature by feature—with local Markdown cards and Git worktrees.
Download:[Get the latest Windows x64 installer]·[Installation guide]
Platforms:md² is an Electron desktop app. Windows x64 has a signed installer; macOS and Linux can run from source, but do not have prebuilt packages yet.
md2_integrate_into_project.mp4 #
In a traditional coding workflow, the source code is the center: you open a project and instruct an AI agent to change it. md² shifts the focus to the work being requested—a feature description, bug report, or job. Source-code changes remain the output, but they are no longer the organizing center.
Each request is stored as a Markdown card in your repository. Everything related to the work hangs off that card:
- its Git worktree
- the coding agent working on it
- chat history
- commits
- design notes and documentation
- token usage and cost
Reusable prompts and actions live at project level. They support the cards: run an action from a card and md² supplies that card's description and worktree context.
The card becomes the shared context for both you and your agents. Instead of reconstructing the work and its history from editor windows, folders, and disconnected conversations, you can follow and manage it from one place. Because cards are ordinary local Markdown files, agents can read and update the same project knowledge directly.
md² starts the CLIs already installed and authenticated on your machine. It does not call model APIs directly, and either CLI is optional when using md² as a Markdown-backed project board.
| Without md² | With md² |
|---|---|
| Agent conversations grouped by chat | Activity grouped by feature |
| Worktrees identified by folders/windows | Worktrees assigned to cards |
| Repeated prompts scattered around | Reusable project actions |
| Token use largely invisible | Cost tracked by action and feature |
Full docs: https://jan-bogaerts.github.io/md2/
A card can be linked to the worktree and coding agent working on it. Instead of searching through editor windows and terminals, you can see the state of the entire project in one place.
Agents can update their cards automatically as work progresses.
A feature often takes multiple prompts, sessions, and commits to complete.
md² links those interactions back to the feature instead of presenting one large, disconnected history of agent conversations.
Cards, design notes, plans, and other project information are ordinary Markdown files stored inside the repository.
Agents can read and update them directly without requiring access to an external project-management service. The files can also be searched, diffed, versioned, and edited with normal development tools.
Repeated prompts often grow into large collections of instructions or skills. all of them can consume tokens and introduce irrelevant context.
md² lets you create smaller reusable actions for specific tasks. Actions can contain automatically resolved placeholders such as:
{{card-file}}
This keeps prompts focused on the current task.
Not every development task requires an AI agent.
Command actions can commit changes, update diagrams, run tests, change card state, or execute scripts at specific points in the workflow.
For recurring complex work, an agent can create a script once and md² can reuse it later without spending tokens on the same reasoning every time.
md² tracks token usage and cost:
- per action
- per feature
- across the complete project
This makes it easier to understand where agent time and tokens are being spent.
md² is still an evolving concept — see design/architecture/initial description for the original design notes this project is built from.
Run reusable actions from a card, follow the agent conversation, and commit or integrate the assigned worktree without losing the feature context.
The card remains the shared source of truth for its definition, agent activity, worktree, and resulting changes.
Download and install the latest Windows release, or follow thesource setupon macOS or Linux.- Click the GitHub icon, upper left corner, follow link to get a GitHub access token, copy-paste token in.
- Open project, select a folder that contains a git repository.
The repo has three parts: app/ (the React/Vite web UI), desktop/ (the Electron host shell), and shared/ (types and logic used by both). Each subproject has its own package.json
and npm scripts, but a root package.json
wires up the common workflows.
Node.js(LTS) and npm- Git
npm run install:all
This installs dependencies for both app
and desktop
.
npm run dev
This starts the Vite dev server for app
and, once it's up, launches the Electron shell (desktop
) pointed at it. To run either half on its own: npm run dev:app
or npm run dev:desktop
.
app/.env.example
and desktop/.env.example
list optional Sentry/Aptabase keys for error reporting and analytics. Copy to .env
and fill in if you want telemetry locally — neither is required to build or run the app.
Each subproject is standalone and has its own npm scripts.
cd app
npm run lint
npm run lint-fix
npm run test
cd desktop
npm run lint
npm run lint-fix
npm run test