sahil87/idea

idea

Part of HexoKit — see all projects there.

Capture and manage ideas from the command line. A worktree-aware backlog tracker that keeps fab/backlog.md as the source of truth — plain Markdown, queryable from the CLI, shareable with the rest of your team via git.

Install

curl -fsSL https://shll.ai/install | sh -s -- idea

Installs idea (plus the shll meta-CLI) via Homebrew, handling tap trust automatically. To install the entire shll toolkit instead:

curl -fsSL https://shll.ai/install | sh

Why idea?

• Plain Markdown, not a database — your backlog is a checked-in fab/backlog.md file. Hand-edit it, grep it, diff it, review it in PRs. idea is one (canonical) writer of the format; the file is the contract.
• Per-repo by default, with a global escape hatch — every repo has its own backlog, so there's no cross-project noise. When you're not in a repo (or want a personal, cross-cutting list), idea falls back to a system-level backlog at ~/.config/idea/backlog.md — reachable from anywhere with --system (-s).
• Worktree-aware — by default idea reads/writes the current worktree's backlog, so parallel changes don't step on each other. --main (-m) opts into the shared backlog, and --system (-s) targets the global one.
• Short, addressable IDs — every idea gets a 4-character ID like [qu1d] you can type into any command. Queries also match free-text substrings.
• Hooks into fab-kit — fab/backlog.md is the same file fab-kit's /fab-new reads, so capturing an idea today and starting a change from it tomorrow is one command.

Other ways to install

Build and install manually from a clean checkout (requires Go and just):

just local-install

Builds the binary and copies it to ~/.local/bin/idea. Make sure that directory is on your $PATH.

To upgrade later: idea update (self-upgrades via Homebrew).

For Homebrew details, manual-build prerequisites, shell completion, and upgrades, see the full install guide.

Shell completion

idea shell-init <shell emits eval-safe tab-completion for your shell. Add this line to your rc file:

eval "$(idea shell-init zsh)"   # in ~/.zshrc
eval "$(idea shell-init bash)"  # in ~/.bashrc