goal

Track goals and tasks from the command line. Built for AI agents, and for the people who work with them.

简体中文 | English

Install

dart pub global activate goal

Requires Dart 3.4 or later.

Quick start

$ goal init
ok ledger at .goal

$ goal add "Fix login crash on iOS" -p1 --round R12
ok #1 created (todo) round=R12 Fix login crash on iOS

$ goal set 1 wip --agent agent_a
ok #1 todo -> wip +agent=agent_a

$ goal set 1 done "fixed login.dart; flutter test green"
ok #1 wip -> done +note="fixed login.dart; flutter test green"

$ goal add "Add offline mode" -p2
ok #2 created (todo) Add offline mode

$ goal ready
2  P2  todo  5m  -  Add offline mode
-- 1 ready

Commands

command	what it does
goal init	create a ledger in ./.goal (once per project)
goal add <title>	add a ticket; flags: -p0..-p3 --deps a,b --round R -m <text>
goal set <id> [status] [note...]	update a ticket — change status, add a note, set --agent, --deps, --round, -pN, correct the text with --title/--detail (- reads stdin, like -m), or unset fields with --clear agent|pri|round|deps. No arguments = heartbeat. Ids accept the # prefix.
goal list [filters]	list tickets. Filter by bare words: status, round, priority, #id, or title text — combined freely (goal list wip R12). The same filters accept flags: -pN --round <R> --id <id>
goal ready	todo tickets whose dependencies are all done, highest priority first
goal show <id>	everything about one ticket — archived tickets too, tagged [archived]
goal render [-o file] [--json]	export a readable markdown view, or JSON (the JSON backup includes the archive)
goal archive [--dry-run]	move done tickets out of the active ledger; --dry-run previews what would move
goal rm <id>	delete a ticket outright (journaled; the id is never reused)

Statuses: todo wip done blocked failed parked.

Notes are timestamped and append-only — use them for settlement details: files changed, verification commands, evidence links.

$ goal set 3 done "files: a.dart, b.dart; verify: dart test; evidence: docs/3.png"

Long notes can be piped in to avoid quoting trouble: goal set 3 done -m - reads the note from stdin.

Multiline and special characters are welcome everywhere: titles, details and notes are stored verbatim — show is the verbatim view — while receipts, list and render always print structurally safe single-line entries. Truncation is grapheme-cluster safe, so RTL scripts (Arabic, Hebrew, Persian) and composed emoji round-trip without a cut splitting a letter from its harakat or an emoji from its joiners; Unicode line separators (U+2028) are treated as line breaks in views and never leak into receipts. Bare words after goal add join into one title, so an unquoted title still succeeds on the first try, and every receipt states the new values (+agent=… +deps=1,2 +note="…") so no follow-up show is needed.

Dependencies

A ticket with --deps waits until every dependency is done (or archived) before it shows up in goal ready. Cycles are rejected outright.

$ goal add "Re-review fix" --deps 3
$ goal ready          # empty until ticket 3 is done

Where is my data?

Everything lives in ./.goal/ next to your project. Add .goal/ to your .gitignore. Point GOAL_HOME elsewhere if you want it out of the repo.

Done tickets are moved to the archive by goal archive; the active ledger stays small. goal render gives you a markdown or JSON snapshot at any time.

License

MIT