your backlog is plain text

A markdown task tracker with a terminal UI for humans and a CLI for agents. Tasks live in your repo as readable files. Position is priority. Git is your history.

$ cargo install frame copy

Requires Rust. Or download a pre-built binary. View on GitHub →

Quick start
zsh
$ cd my-project $ fr init --track effects "Effect System" $ fr add effects "Parse effect syntax" $ fr push effects "Fix parser crash" # top = highest priority $ fr # open TUI
frame - Example Project
▶ Effects ★ │ Unique │ Infra │ ▶ │ *5 │ ✓ │ ───────────────┴────────┴───────┴───┴────┴───┴─────────── [ ] EFF-015 Effect handler opt pass ▼[ ] EFF-014 Implement effect inference #cc ├ [ ] .1 Add effect variables ├ [>] .2 Unify effect rows #cc └ [ ] .3 Test with nested closures [x] EFF-003 Implement effect handler desugaring [-] EFF-012 Effect-aware DCE #bug [ ] EFF-016 Error msgs for mismatches #needs-input [ ] EFF-017 Research: effect composition #research [ ] EFF-018 Design doc: effect aliases #design ── Parked ────────────────────────────────────────────── [~] EFF-020 Higher-order handlers #research
How it works
1

Tasks are markdown

Each track is a .md file with checkboxes, metadata, notes, and code blocks. Edit them in Frame or any text editor.

2

Position is priority

No priority fields or labels. The task at the top of the list is the most important. Use m in the TUI or fr mv to reprioritize.

3

TUI for humans, CLI for agents

The terminal UI is for navigating and editing. The fr CLI is for coding agents — fr ready --cc to pick up work, fr state EFF-014 done to report progress.

4

Git is your history

No database. No sync service. Your tasks are files in your repo. git log is your audit trail. git diff shows what changed.

File format
# Effect System > Design and implement the algebraic effect system. ## Backlog - [>] `EFF-014` Implement effect inference for closures #cc - added: 2025-05-10 - dep: EFF-003 - spec: doc/spec/effects.md#closure-effects - note: The desugaring needs to handle three cases: 1. Simple perform with no resumption 2. Perform with single-shot resumption 3. Perform with multi-shot resumption - [ ] `EFF-014.1` Add effect variables to closure types - [>] `EFF-014.2` Unify effect rows #cc - [ ] `EFF-014.3` Test with nested closures - [ ] `EFF-015` Effect handler optimization pass - dep: EFF-014 - [-] `EFF-012` Effect-aware dead code elimination #bug - dep: EFF-014, INFRA-003

That's it. Checkboxes for state, backtick IDs, hash tags, indented metadata. Subtasks are just nested tasks. Notes can include code blocks. The file is readable without Frame and editable in any editor.

Project structure
my-project/ frame/ project.toml # Config: tracks, tags, colors inbox.md # Quick capture tracks/ effects.md # One file per work stream compiler-infra.md archive/ effects.md # Done tasks, auto-archived

The project.toml is self-documenting — see the template for the full configuration reference.

Features
tracks Parallel work streams, each a markdown file. Active, shelved, or archived.
states Todo, active, blocked, done, parked. Space to cycle, b to block, ~ to park.
subtasks Three levels deep. Collapsible in the TUI. Dotted IDs: EFF-014.2.1
deps Cross-track dependencies with cycle detection. fr ready shows only unblocked tasks. D opens the dep graph.
search Regex search across titles, notes, tags, IDs. Vim-style /pattern with n/N navigation.
inbox Quick capture queue. Triage into tracks when ready. Enter to pick a track and position.
multi-select v to select, V for range. Bulk state changes, tag edits, moves, and cross-track moves.
undo Full undo/redo stack for all mutations. External file changes insert sync markers to prevent cross-boundary undo.
agents fr ready --cc for agent work. --json on every command. See the agent skill reference.
vim-modal Navigate, Edit, Move, Search, Select modes. hjkl, /, u for undo, ? for contextual help.
CLI
zsh
# What should I work on? $ fr ready --cc --json { "focus_track": "infra", "tasks": [{ "id": "INFRA-015", "title": "Add span tracking to HIR nodes", "tags": ["cc"], "spec": "doc/spec/hir.md#spans" }] } # Task lifecycle $ fr state INFRA-015 active $ fr sub INFRA-015 "Handle multi-file spans" $ fr add infra "Implement span merging" --found-from INFRA-015 $ fr state INFRA-015 done INFRA-015: active → done (resolved 2025-06-01) # Move and organize $ fr mv INFRA-022 --top $ fr mv INFRA-022 --track effects # Maintenance $ fr clean # Normalize, assign IDs, archive done tasks $ fr check # Validate deps and file refs