{"id":49781443,"url":"https://github.com/sahil87/idea","last_synced_at":"2026-06-10T20:00:33.365Z","repository":{"id":355574540,"uuid":"1227091504","full_name":"sahil87/idea","owner":"sahil87","description":"Worktree-aware idea capture and backlog tracker — markdown-first, CLI-native","archived":false,"fork":false,"pushed_at":"2026-06-08T10:42:00.000Z","size":246,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T12:18:55.196Z","etag":null,"topics":["agents","backlog","cli","developer-tools","fab-kit","markdown","note-taking","productivity","terminal"],"latest_commit_sha":null,"homepage":"https://shll.ai/idea","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sahil87.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-02T07:29:54.000Z","updated_at":"2026-06-08T10:42:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sahil87/idea","commit_stats":null,"previous_names":["sahil87/idea"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/sahil87/idea","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sahil87%2Fidea","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sahil87%2Fidea/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sahil87%2Fidea/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sahil87%2Fidea/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sahil87","download_url":"https://codeload.github.com/sahil87/idea/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sahil87%2Fidea/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34168086,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","backlog","cli","developer-tools","fab-kit","markdown","note-taking","productivity","terminal"],"created_at":"2026-05-11T21:01:09.802Z","updated_at":"2026-06-10T20:00:33.358Z","avatar_url":"https://github.com/sahil87.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# idea\n\n\u003e Part of [@sahil87's open source toolkit](https://shll.ai) — see all projects there.\n\n[![Latest release](https://img.shields.io/github/v/release/sahil87/idea)](https://github.com/sahil87/idea/releases) [![Downloads](https://img.shields.io/github/downloads/sahil87/idea/total)](https://github.com/sahil87/idea/releases) [![Stars](https://img.shields.io/github/stars/sahil87/idea?style=social)](https://github.com/sahil87/idea/stargazers)\n\nCapture 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.\n\n## Why idea?\n\n- **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.\n- **Per-repo, not global** — every repo has its own backlog. No central app to log into, no cross-project noise.\n- **Worktree-aware** — by default `idea` reads/writes the *current* worktree's backlog, so parallel changes don't step on each other. `--main` opts into the shared backlog when you need it.\n- **Short, addressable IDs** — every idea gets a 4-character ID like `[qu1d]` you can type into any command. Queries also match free-text substrings.\n- **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.\n\n## Install\n\nHomebrew tap:\n\n```bash\nbrew install sahil87/tap/idea\n```\n\nOr build and install manually from a clean checkout (requires Go and `just`):\n\n```bash\njust local-install\n```\n\nBuilds the binary and copies it to `~/.local/bin/idea`. Make sure that directory is on your `$PATH`.\n\nTo upgrade later: `idea update` (self-upgrades via Homebrew).\n\nFor Homebrew details, manual-build prerequisites, shell completion, and upgrades, see the full [install guide](docs/site/install.md).\n\n## Shell completion\n\n`idea shell-init \u003cshell\u003e` emits eval-safe tab-completion for your shell. Add this line to your rc file:\n\n```sh\neval \"$(idea shell-init zsh)\"   # in ~/.zshrc\neval \"$(idea shell-init bash)\"  # in ~/.bashrc\n```\n\nSupports `zsh`, `bash`, `fish`, and `powershell`. Tab-completes subcommands, flags, and the `idea \u003ctext\u003e` shorthand.\n\n\u003e 💡 Have other sahil87 tools? [`shll shell-install`](https://github.com/sahil87/shll#shll-shell-install--wire-the-rc-file-recommended) handles all of their shell integrations and autocompletions at once.\n\n## Quick Start\n\nA typical capture-and-triage session:\n\n```text\n$ idea \"refactor auth middleware to use JWT\"\nAdded: [qu1d] 2026-05-11: refactor auth middleware to use JWT\n\n$ idea \"add rate limiting to public endpoints\"\nAdded: [dpr1] 2026-05-11: add rate limiting to public endpoints\n\n$ idea \"update README with new setup steps\"\nAdded: [xumo] 2026-05-11: update README with new setup steps\n\n$ idea list\n- [ ] [qu1d] 2026-05-11: refactor auth middleware to use JWT\n- [ ] [dpr1] 2026-05-11: add rate limiting to public endpoints\n- [ ] [xumo] 2026-05-11: update README with new setup steps\n\n$ idea done dpr1\nDone: - [x] [dpr1] 2026-05-11: add rate limiting to public endpoints\n\n$ idea list                 # open items only\n- [ ] [qu1d] 2026-05-11: refactor auth middleware to use JWT\n- [ ] [xumo] 2026-05-11: update README with new setup steps\n```\n\nQueries (the `\u003cid\u003e` arg on `show`, `done`, `reopen`, `edit`, `rm`) match against either the ID or the description text — substring, case-insensitive. So `idea done auth` would also have closed `qu1d`.\n\n## Command reference\n\n| Command | Summary |\n|---------|---------|\n| `idea \"text\"` | Add a new idea (shorthand for `idea add`). |\n| `idea add \"text\"` | Add a new idea to the backlog. |\n| `idea list` | List open ideas. `--all` includes done items, `--done` only done, `--json` for scripting, `--sort id\\|date`, `--reverse`. |\n| `idea show \u003cquery\u003e` | Show a single idea matching the query (by ID or substring). |\n| `idea done \u003cquery\u003e` | Mark an idea as done. |\n| `idea reopen \u003cquery\u003e` | Reopen a completed idea. |\n| `idea edit \u003cquery\u003e \"text\"` | Replace an idea's description. |\n| `idea rm \u003cquery\u003e --force` | Delete an idea (requires `--force` to confirm). |\n| `idea update` | Self-update via Homebrew. |\n\nRun `idea \u003ccommand\u003e --help` for inline flag details, browse the [full command reference](https://shll.ai/tools/idea/commands/) on shll.ai, or see [`docs/specs/overview.md`](https://github.com/sahil87/idea/blob/main/docs/specs/overview.md) for the full CLI reference and [`docs/specs/backlog-format.md`](https://github.com/sahil87/idea/blob/main/docs/specs/backlog-format.md) for the file format contract.\n\n### Worktree-aware by default\n\nThis is the one behavior worth knowing in detail. `idea` resolves the backlog file based on where you run it:\n\n| Where you are | What you type | Which file `idea` touches |\n|---------------|---------------|----------------------------|\n| Main repo | `idea add \"...\"` | `\u003cmain\u003e/fab/backlog.md` |\n| Linked worktree | `idea add \"...\"` | `\u003cworktree\u003e/fab/backlog.md` (local to this worktree) |\n| Linked worktree | `idea --main add \"...\"` | `\u003cmain\u003e/fab/backlog.md` (shared with the team) |\n| Anywhere | `idea --file path/to/file.md ...` | that file (relative to git root) |\n| Anywhere | `IDEAS_FILE=... idea ...` | the env-var path |\n\nWhy the default favors the current worktree: when you're heads-down on a change and capture a thought, you usually mean \"for *this* branch.\" `--main` is the explicit opt-in for \"add this to the shared roadmap.\" In the main worktree, both behave identically.\n\n## Integration with fab-kit\n\n`fab/backlog.md` is the same file fab-kit reads, so the loop closes naturally:\n\n1. **Capture** — `idea \"add retry logic to API client\"`\n2. **Triage** — `idea list` to review what's open\n3. **Start work** — `/fab-new \u003cid\u003e` (in your AI agent) pulls the description from the backlog and spins up a change folder + branch\n4. **Close** — `idea done \u003cid\u003e` after the change ships\n\nFor bulk work, `fab batch new` reads every open idea and spawns a worktree + Claude session per item — the whole backlog becomes a parallel work queue in one command.\n\nThe backlog format is a stable public contract — any tool that follows [`backlog-format.md`](https://github.com/sahil87/idea/blob/main/docs/specs/backlog-format.md) can read or write the file without coupling to `idea`'s internals.\n\nFor a deeper walkthrough of worktree resolution, the fab-kit loop, and the backlog format, see [workflows](docs/site/workflows.md).\n\n## Gotchas\n\n- **`idea rm` requires `--force`.** This is intentional — deletes are destructive and there's no undo. Use `idea done` if you just want the item out of `idea list`.\n- **Ambiguous queries refuse to act.** If your query matches more than one idea, `idea done`, `edit`, and `rm` print the matches and exit without changing anything. Disambiguate with the 4-char ID.\n- **Lines with extra brackets are invisible to queries.** fab-kit's `/fab-new` writes issue IDs into a second bracket (e.g., `- [ ] [qu1d] [DEV-1011] 2026-05-11: ...`). Those lines are preserved verbatim in the file but won't appear in `idea list` or match `idea show` — they're treated as inert pass-through content. See [`backlog-format.md`](https://github.com/sahil87/idea/blob/main/docs/specs/backlog-format.md) for the Shape A vs. Shape B distinction.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsahil87%2Fidea","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsahil87%2Fidea","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsahil87%2Fidea/lists"}