Billet
Menu

Billet

One live board for the Markdown task files your coding agents write in your repos.

Download Get the skills

Completely free, no account needed. For macOS, Windows, and Linux. The skills are open source.

Billet in list view for a sample project called lantern: open tasks grouped by status on the left, two of them running, and task 16, Export notes as a Markdown folder, open on the right with its Outcome, Current state, Scope, and Approach.

One task, start to finish

Task 16 in a sample project. Each step changes a few lines in its file, and the board follows within a second.

  1. You ask for a Markdown export. The agent checks the idea against the code and writes task 16. It lands in Proposed, since a decision about it is still open.

    "status"
    "proposed"
    "created"
    "2026-10-31"

    A new file, with the next ID from tasks.json.

  2. Once you make the decision, the task moves to Ready. Ask your agent to update it, or drag the card yourself.

    "status"
    "proposed""ready"

  3. The task is marked running on its branch, md-export. Its card glows and shows how long the agent has been at it.

    "status"
    "ready""in-progress"
    "started"
    null"2026-10-31"
    "running"
    null"2026-10-31T14:02:00+01:00"
    "branch"
    null"md-export"

  4. The agent checks the work and marks the task done. The running marker clears and the card moves to the top of Done.

    "status"
    "in-progress""done"
    "finished"
    null"2026-10-31"
    "running"
    "2026-10-31T14:02:00+01:00"null

    Plus one Unreleased entry in CHANGELOG.md.

Billet’s board for a sample project called lantern. Task 16, Export notes as a Markdown folder, is new at the bottom of Proposed and selected. Task 8 is running in In progress. The same board with task 16 moved to the Ready column. The same board with task 16 in In progress, outlined in orange and running for 23 minutes on the branch md-export, below task 8, which has been running for 48 minutes. The same board with task 16 at the top of the Done column, finished on 10-31. The project now has 6 open, 7 done, and 3 canceled tasks.

Plain files in your repo

Each task is one Markdown file in docs/tasks/, with a small JSON header for status, order, and blockers. Your agents write them through the skills, and they branch and merge with your code like anything else in the repository.

Billet only watches those files. There is nothing to sync, no account, no server, and no database, and nothing leaves your machine. A file it cannot read is listed by name with the reason, never hidden.

lantern/
└─ docs/tasks/
   ├─ tasks.json
   ├─ 0015-pin-notes-to-the-sidebar.md
   └─ 0016-export-notes-as-a-markdown.md
docs/tasks/0016-export-notes-as-a-markdown.md
---
{
  "id": 16,
  "title": "Export notes as a Markdown folder",
  "status": "in-progress",
  "hardness": "medium",
  "area": "export",
  "tags": ["files"],
  "order": 16,
  "blocked_by": [],
  "created": "2026-10-31",
  "started": "2026-10-31",
  "finished": null,
  "reason": null,
  "running": "2026-10-31T14:02:00+01:00",
  "branch": "md-export"
}
---
## Outcome

A notebook can be exported as one folder of plain
Markdown files…
The project picker open over the list view, showing four projects with their running and open task counts. lantern-site has nothing open and is dimmed.

Every project, one keystroke away

Point Billet at a folder such as ~/Developer and every project with a docs/tasks/ folder shows up. ⌘P switches between them, and projects with nothing open are dimmed.

Keyboard-first, with a list and a board view, zoom, light and dark appearance, and a focus mode for long tasks.

The skills

Short instruction files your agent loads. Install the billet-* skills once, run billet-init in a project, then manage tasks by asking. They all follow one shared format file, so every skill writes tasks the same way.

billet-skillsOn GitHub, zlib license

Set up and plan

billet-init
Sets up a project once: creates the task folder and tells the project’s agents about it.
billet-add
Turns an idea into a task file, checked against the code and existing tasks.
billet-critique
Challenges a plan before work starts: weak spots, wrong assumptions, missing decisions.
billet-split
Breaks a large task into pieces only when they can really be worked on in parallel.

Work

billet-start
Starts or continues a task, asks open questions first, and marks it running on its branch.
billet-finish
Verifies the work, closes the task, and adds a changelog entry.
billet-cancel
Drops a task with a reason and keeps its record.

Keep tidy

billet-list
Reports open tasks with their IDs, status, and hardness.
billet-leftovers
Checks whether recent work finished what it set out to do and files what is left.
billet-groom
Cleans up the board’s data and checks it is still accurate against the code.

Questions

Something missing? Find me on socials.

Do I need an AI agent to use it?

No. A task is a Markdown file with a small JSON header, so you can write one by hand. The skills just mean your agent keeps the files for you.

Which agents do the skills work with?

Any coding agent that supports skills. Run one like any other skill, for example /billet-add, or just ask your agent to add a task.

Can Billet change my tasks?

It never creates tasks, writes their text, or talks to a model. You can tidy by hand: drag a card to another status, mark its hardness, or clear a stale running marker. Those edits follow the skills’ rules, touch only the header, and never overwrite a newer change an agent just made.

How does it know an agent is working on a task?

When an agent starts a task, the start skill writes a running timestamp and the branch into the task’s header. Finishing clears it. Billet shows how long that has been and on which branch. If a session dies halfway, clear the stale marker from the task’s right-click menu.

Where are my tasks stored?

In each project’s docs/tasks/ folder, inside your repository. Billet itself only keeps its own settings, such as recent projects, the list or board view, and the window position.

Can I use my own columns?

Yes. A tasks.json beside the task files lists the status columns in order. The defaults are proposed, ready, in-progress, done, and canceled.

Why is it called Billet?

A billet is a written order that assigns someone a job, which is what a task file is. Pin them to a board and you get a billet board.

I’ve been using it for months now, and it works nicely for local task management. I wouldn’t go back to writing tasks by hand and working through them myself.

Download Billet

Completely free, with no account or paid tier. Nothing is uploaded or tracked.

  • macOS
  • Windows
  • Linux

Coming soon

The skills are available now. Get them on GitHub.

Check out my other projects