{"id":"cf5eb6bb-03e7-4f79-9107-6810f433929a","slug":"joshsegall-frame","kind":"skill","name":"frame","summary":"A markdown task tracker with a terminal UI for humans and a CLI for agents.","owner":"joshsegall","repoUrl":"https://github.com/joshsegall/frame","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-02-08T09:46:25.000Z","addedAt":"2026-10-21T22:32:11.370Z","logoUrl":"https://avatars.githubusercontent.com/u/270672?u=2bdf820dca28745526f9a4f4ec65848884aaed8e&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["productivity","files-documents","design-media"],"tags":["cli","developer-tools","markdown","productivity","ratatui","rust","task-management","task-tracker"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-22T07:27:01.134Z","sample":false,"url":"https://conduits.dev/tools/joshsegall-frame","language":"Rust","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# [>] frame\n\n[![CI](https://github.com/joshsegall/frame/actions/workflows/ci.yml/badge.svg)](https://github.com/joshsegall/frame/actions/workflows/ci.yml)\n[![Crates.io](https://img.shields.io/crates/v/frame.svg)](https://crates.io/crates/frame)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n**your backlog is plain text**\n\nA markdown task tracker with a terminal UI for humans and a CLI for agents.\n\nTasks live in markdown files inside your repo. Position is priority.\nGit is your history.\n\n## How it works\n\nYour project gets a `frame/` directory with markdown files — one per\nwork stream (called a **track**). Tasks are checkbox list items with\noptional IDs, tags, dependencies, notes, and subtasks:\n\n```markdown\n- [>] `EFF-014` Implement effect inference for closures #cc\n  - dep: EFF-003\n  - spec: doc/spec/effects.md#closure-effects\n  - note:\n    The desugaring needs to handle three cases:\n    1. Simple perform with no resumption\n    2. Perform with single-shot resumption\n    3. Perform with multi-shot resumption\n  - [ ] `EFF-014.1` Add effect variables to closure types\n  - [>] `EFF-014.2` Unify effect rows during inference #cc\n  - [ ] `EFF-014.3` Test with nested closures\n```\n\nThe TUI gives you a full visual interface. The CLI gives agents\nprogrammatic access. Both read and write the same markdown files.\n\n## Install\n\n```bash\ncargo install frame\n```\n\nOr download a pre-built binary from [GitHub Releases](https://github.com/joshsegall/frame/releases).\n\n## Quick start\n\n```bash\ncd my-project\nfr init --track effects \"Effect System\"\nfr add effects \"Parse effect syntax\"\nfr push effects \"Fix parser crash\"       # Push to top (highest priority)\nfr                                       # Open TUI\n```\n\n## Task states\n\n| Char  | State   | Meaning              |\n|-------|---------|----------------------|\n| `[ ]` | todo    | Not started          |\n| `[>]` | active  | In progress          |\n| `[-]` | blocked | Waiting on something |\n| `[x]` | done    | Complete             |\n| `[~]` | parked  | Deferred             |\n\n`Space` cycles todo → active → done. `b` sets blocked. `~` sets parked.\n\n## Project structure\n\n```\nmy-project/\n  frame/\n    project.toml          # Config: tracks, tags, colors\n    inbox.md              # Quick capture\n    tracks/\n      effects.md          # One file per work stream\n      compiler-infra.md\n    archive/\n      effects.md          # Done tasks, auto-archived\n```\n\nSee [`project.toml`](src/templates/project.toml) for the full configuration\nreference — the template is self-documenting.\n\n## TUI\n\n`fr` with no arguments launches the TUI.\n\nVim-style modal interface. Four primary modes: **NAVIGATE**, **EDIT**,\n**MOVE**, **SEARCH**, plus **SELECT** for bulk operations.\nPress `?` for the full key binding reference, or `>` to open the command palette.\n\nThe short version: `↑↓`/`jk` to move, `←→`/`hl` to collapse/expand,\n`1`–`9` for track tabs, `K` for board view, `Space` to cycle state, `e` to edit,\n`a` to add, `m` to move, `/` to search, `Enter` for detail view.\n`QQ` or `Ctrl-Q` to quit.\n\n## CLI\n\nDesigned for coding agents. Every read command supports `--json`.\nSee [`skills/managing-frame-tasks/SKILL.md`](skills/managing-frame-tasks/SKILL.md)\nfor the full agent reference, and [`doc/agent-setup.md`](doc/agent-setup.md)\nfor how to configure frame for agent use in your project.\n\n```bash\n# What should I work on?\nfr ready --cc --json\n\n# Capture something quickly\nfr inbox \"Parser crashes on empty blocks\" --tag bug\n\n# Task lifecycle\nfr add effects \"Implement handler desugaring\" --after EFF-003\nfr state EFF-004 active\nfr dep EFF-004 add EFF-003\nfr sub EFF-004 \"Add effect variables\"\nfr state EFF-004 done\n\n# Move and organize\nfr mv EFF-010 --top\nfr mv EFF-010 --track infra\n\n# Maintenance\nfr clean             # Normalize, assign IDs, archive done tasks\nfr check             # Validate deps and file refs\n```\n\n## Using frame with git\n\nTrack files are generated artifacts whose structure carries meaning: a task's ID\nis its identity, and finishing a task *moves* it between sections. Merged line by\nline, that move reads as a delete plus an add — and resolving the resulting\nconflict by keeping both sides yields two copies of one task, one open and one\ndone, in a file that still looks fine.\n\nSo run this once per clone:\n\n```bash\nfr git setup\n```\n\nIt adds the `.gitignore` pattern and the `.gitattributes` entries, and registers\nframe's merge driver so git merges track files by task identity instead. `fr\ninit` does it for you in a new project. The first two are committed; the driver\nlives in `.git/config` and cannot be, so **each clone runs it once** — `fr check`\nwarns when one hasn't.\n\n## Key concepts\n\n**Tracks** are ordered work streams. Active tracks appear as tabs.\nTracks can be shelved or archived.\n\n**Position is priority.** Top of the backlog = highest priority.\nUse `m` (TUI) or `fr mv` (CLI) to reprioritize.\n\n**Tags** are freeform labels. Conventional: `#cc`, `#bug`,\n`#research`, `#design`, `#needs-input`.\n\n**Dependencies** are cross-track references. `fr ready` filters to\ntasks whose deps are all done.\n\n**Inbox** is a quick-capture queue. Triage items into tracks when\nyou're ready.\n\n**Actor tokens** give concurrent clones collision-free IDs: each working\ncopy mints task IDs in its own token-namespace (`EFF-14` on the primary,\n`EFF-a1` on a tokened clone), so unsynced clones never produce the same ID.\n\n**`fr clean`** normalizes formatting, assigns IDs, archives completed\ntasks, and validates references. Runs automatically when external\nchanges are detected.\n\n**Multiple projects** are supported via a global registry — use\n`fr projects` to list, add, or remove projects.\n\n**Personal tool** — designed for one developer (and their agents) \nmanaging their own work. It uses advisory file locking, not a \ndatabase, so it's not built for concurrent team access.\n\n## Terminal support\n\nTested on macOS with Ghostty. It should work on any terminal that\nsupports the Kitty keyboard protocol (Kitty, WezTerm, foot), \nbut hasn't been tested.\n"}