mrkl

mrkl, rhymes with sparkle
Lightweight CLI for structured markdown task tracking.
Track work in your repo, not in a separate app.

---

Why mrkl?

• No external service — tasks live in .tasks/ as structured markdown
• Git-native — commit, branch, and diff your tasks like any other file
• AI-agent friendly — consistent YAML frontmatter for programmatic parsing
• Conventional commits vocabulary — feat, fix, chore, etc.
• Zero config — one command to set up

Install

pnpm add -g @xxkeefer/mrkl

Quick Start

mrkl init                                    # set up .tasks/
mrkl create feat "user auth"                 # create a task
mrkl create fix "login loop" -P 5            # with priority (1-5)
mrkl list                                    # interactive TUI
mrkl list --plain                            # pipe-friendly output
mrkl done fub-09a3k1                         # mark done + archive
mrkl close fub-09a3k2 -r "duplicate"         # close with reason

Every command has a short alias: i init, c create, ls list, e edit, d done, p prune, x close.

Running a command without arguments opens an interactive TUI.

Commands

Command	Alias	Description
init	i	Initialize .tasks/ in the current project
create	c	Create a new task
edit	e	Edit a task in an interactive TUI
list	ls	List tasks (interactive TUI or --plain)
done	d	Mark task(s) done and archive
close	x	Close task(s) with optional reason and archive
prune	p	Delete archived tasks before a cutoff date
install-skills	—	Install bundled Claude Code skills

create

mrkl create <type> <title> [--desc <text>] [--ac <text>]... [--priority <1-5>]

Types: feat fix chore docs perf refactor test ci build style

list

mrkl list [--type <type>] [--status <status>] [--search <text>] [--sortby <field:dir>] [--plain]

TUI controls:

Key	Action
↑↓	Navigate tasks
/	Search / filter
s	Cycle sort field
d	Toggle sort direction
p	Toggle preview panel
Tab	Switch between Tasks / Archive
Enter	Open task in edit TUI
Esc	Quit

edit

mrkl edit [id]          # by ID or prefix — omit to pick from list

done / close

mrkl done <id...>
mrkl close <id...> [--reason <text>]

prune

mrkl prune <YYYY-MM-DD> [--force]

Icons

All output uses single-cell Unicode symbols — no emoji, consistent across terminals.

Symbol	Meaning
○	todo
◑	in-progress
✔	done / success
✖	closed / error
⚠	warn
ℹ	info
▼▽◇△▲	priority (lowest → highest)
« »	blocks / blocked-by
◉ ◌	epic / child

Task File Format

Tasks are markdown with YAML frontmatter, stored in .tasks/:

---
id: fub-09a3k1
title: user authentication
type: feat
status: todo
priority: 3
created: '2026-03-20'
parent: fub-08z1a0
blocks:
  - fub-09b2c3
---

## Description

Implement user authentication with OAuth2.

## Acceptance Criteria

- [ ] login page renders
- [ ] OAuth flow completes

Statuses: todo in-progress done closed

Relationships: Tasks can have a parent (epic/child hierarchy) and blocks (dependency tracking). These are displayed in the list TUI with ◉/◌ and «/» indicators.

Team Workflow

IDs are temporal base36 (ddd-mmmmmm — days since epoch + milliseconds since midnight). No counter, no config, no sync — create tasks on any branch and merge without conflicts.

Development

git clone https://github.com/xxKeefer/mrkl.git
cd mrkl
pnpm install
pnpm test
pnpm dev list        # run CLI in development
pnpm build

Contributing

See CONTRIBUTING.md.

License

MIT