todoprompt

A terminal UI that scans your codebase for TODO comments (using ripgrep) and turns the one you pick into a ready-to-paste prompt for a coding agent.

┌─ TODOs (3) ────────────────────┐┌─ src/a.ts:2 ───────────────────────────────┐
│ ▶ src/a.ts:2                   ││ ts                                          │
│   TODO: validate inputs        ││  1 export function add(a: number, b: number)│
│   src/a.ts:7                   ││  2   // TODO: validate inputs are finite     │
│   TODO refactor this helper    ││  3   return a + b;                          │
│   src/style.css:2              ││  4 }                                        │
│   TODO: use theme token        ││  5 // regular comment                       │
└────────────────────────────────┘└─────────────────────────────────────────────┘
 ↑/↓ move  enter prompt  c config  r rescan  q quit

• Two-pane browser — found TODOs on the left, the surrounding code (with the TODO centred) on the right.
• Prompt generator — press Enter to turn a TODO into a prompt from a configurable template, edit it inline, and copy it to the system clipboard.
• Config screen — customise the prompt template, the search term, and the include/exclude globs without leaving the app. Settings persist to ~/.config/todoprompt/config.json.

Requirements

• Bun — the renderer (OpenTUI) loads a native library via FFI, which Bun provides out of the box. The CLI runs under Bun even when installed with npm.
• ripgrep (rg) on your PATH.

Install

npm install -g todoprompt
# or
bun install -g todoprompt

The published package's executable uses a #!/usr/bin/env bun shebang, so Bun must be installed and on your PATH.

Run without installing:

bun x todoprompt

Usage

todoprompt                       # scan the current directory
todoprompt -d ~/Sites/my-app     # scan a specific directory
todoprompt --dir ./packages/web
todoprompt --help

Keys

| Screen | Keys | | ---------- | ----------------------------------------------------------------------------------- | | Browse | ↑/↓ or j/k move · Enter build prompt · c config · r rescan · q quit | | Prompt | e edit · c copy to clipboard · r reset to template · Esc back | | Config | ↑/↓ move · Enter edit field · Esc back & rescan | | | in a field: Enter save (Ctrl+S for the template) · Esc cancel |

Configuration

Stored at ~/.config/todoprompt/config.json (honours XDG_CONFIG_HOME). Everything below is editable from the in-app Config screen.

| Setting | Description | | --------------- | ---------------------------------------------------------------------- | | Search term | The regex passed to ripgrep (default TODO; try TODO\|FIXME\|HACK). | | Include globs | Comma-separated globs of files to search (each becomes -g <glob>). | | Exclude globs | Comma-separated globs to skip (each becomes -g !<glob>). | | Context lines | How many lines to show either side of a TODO. | | Prompt template | The text generated for each TODO. Supports the tokens below. |

ripgrep also honours your .gitignore, so generated/vendored files are skipped on top of the exclude globs.

Prompt template tokens

| Token | Replaced with | | -------------- | ------------------------------------------------------ | | {{relPath}} | File path relative to the scanned directory | | {{absPath}} | Absolute file path | | {{line}} | Line number of the TODO | | {{column}} | Column of the matched keyword | | {{todo}} | The TODO text (from the keyword to end of line) | | {{lineText}} | The full matched line, trimmed | | {{context}} | The surrounding code window (raw source) | | {{lang}} | Language hint for the fenced code block (ts, php…) | | {{cwd}} | The directory being scanned |

Development

bun install
bun run src/cli.tsx        # run against the current directory
bun run typecheck          # tsc --noEmit
bun test                   # headless render + logic checks (scripts/smoke.tsx)

License

MIT