frame

[>] frame

your backlog is plain text

A markdown task tracker with a terminal UI for humans and a CLI for agents.

Tasks live in markdown files inside your repo. Position is priority. Git is your history.

How it works

Your project gets a frame/ directory with markdown files — one per work stream (called a track). Tasks are checkbox list items with optional IDs, tags, dependencies, notes, and subtasks:

- [>] `EFF-014` Implement effect inference for closures #cc
  - 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 during inference #cc
  - [ ] `EFF-014.3` Test with nested closures

The TUI gives you a full visual interface. The CLI gives agents programmatic access. Both read and write the same markdown files.

Install

cargo install frame

Or download a pre-built binary from GitHub Releases.

Quick start

cd my-project
fr init --track effects "Effect System"
fr add effects "Parse effect syntax"
fr push effects "Fix parser crash"       # Push to top (highest priority)
fr                                       # Open TUI

Task states

Space cycles todo → active → done. b sets blocked. ~ sets parked.

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

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

TUI

fr with no arguments launches the TUI.

Vim-style modal interface. Four primary modes: NAVIGATE, EDIT, MOVE, SEARCH, plus SELECT for bulk operations. Press ? for the full key binding reference, or > to open the command palette.

The short version: ↑↓/jk to move, ←→/hl to collapse/expand, 1–9 for track tabs, K for board view, Space to cycle state, e to edit, a to add, m to move, / to search, Enter for detail view. QQ or Ctrl-Q to quit.

CLI

Designed for coding agents. Every read command supports --json. See skills/managing-frame-tasks/SKILL.md for the full agent reference, and doc/agent-setup.md for how to configure frame for agent use in your project.

# What should I work on?
fr ready --cc --json

# Capture something quickly
fr inbox "Parser crashes on empty blocks" --tag bug

# Task lifecycle
fr add effects "Implement handler desugaring" --after EFF-003
fr state EFF-004 active
fr dep EFF-004 add EFF-003
fr sub EFF-004 "Add effect variables"
fr state EFF-004 done

# Move and organize
fr mv EFF-010 --top
fr mv EFF-010 --track infra

# Maintenance
fr clean             # Normalize, assign IDs, archive done tasks
fr check             # Validate deps and file refs

Using frame with git

Track files are generated artifacts whose structure carries meaning: a task's ID is its identity, and finishing a task moves it between sections. Merged line by line, that move reads as a delete plus an add — and resolving the resulting conflict by keeping both sides yields two copies of one task, one open and one done, in a file that still looks fine.

So run this once per clone:

fr git setup

It adds the .gitignore pattern and the .gitattributes entries, and registers frame's merge driver so git merges track files by task identity instead. fr init does it for you in a new project. The first two are committed; the driver lives in .git/config and cannot be, so each clone runs it once — fr check warns when one hasn't.

Key concepts

Tracks are ordered work streams. Active tracks appear as tabs. Tracks can be shelved or archived.

Position is priority. Top of the backlog = highest priority. Use m (TUI) or fr mv (CLI) to reprioritize.

Tags are freeform labels. Conventional: #cc, #bug, #research, #design, #needs-input.

Dependencies are cross-track references. fr ready filters to tasks whose deps are all done.

Inbox is a quick-capture queue. Triage items into tracks when you're ready.

Actor tokens give concurrent clones collision-free IDs: each working copy mints task IDs in its own token-namespace (EFF-14 on the primary, EFF-a1 on a tokened clone), so unsynced clones never produce the same ID.

fr clean normalizes formatting, assigns IDs, archives completed tasks, and validates references. Runs automatically when external changes are detected.

Multiple projects are supported via a global registry — use fr projects to list, add, or remove projects.

Personal tool — designed for one developer (and their agents) managing their own work. It uses advisory file locking, not a database, so it's not built for concurrent team access.

Terminal support

Tested on macOS with Ghostty. It should work on any terminal that supports the Kitty keyboard protocol (Kitty, WezTerm, foot), but hasn't been tested.