NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Go modules · #1942 by repository stars
Last release 6 months ago
06 Apr 2026
Ships fairly regularly
a new release about every 2 weeks
Nearly every release is documented
notes for 11 of 11 stable releases
Nothing withdrawn
no release was ever pulled
10 months old
27 releases · first in 2025
One column per month.
A small but useful release focused on making beans easier to configure and more informative in day-to-day use, plus some release infrastructure fixes.
A small but useful release focused on making beans easier to configure and more informative in day-to-day use, plus some release infrastructure fixes.
BEANS_PATH environment variable — You can now set BEANS_PATH in your environment to tell beans where your project's .beans/ directory lives, instead of relying on auto-detection or passing --beans-path every time. Handy if you're working from a different directory or scripting around beans. (#85)
Bean type visible in beans show — The beans show command now displays the bean's type (task, bug, feature, etc.) alongside the other metadata fields, so you get the full picture without needing to inspect the file directly. (#87)
Fixed release pipeline — The GoReleaser workflow was updated to use the built-in GITHUB_TOKEN for releases (18f1c6f) and a separate PAT for Homebrew tap updates (670ecf3), resolving issues with automated releases and tap publishing.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Adds BEANS_PATH environment variable as an alternative to the --beans-path CLI flag for specifying the beans data directory.
Adds BEANS_PATH environment variable as an alternative to the
--beans-path CLI flag for specifying the beans data directory.
When using beans with git worktrees, it's often desirable to have agents
directly use the base checkout's beans directory as a single source of
truth across all worktrees.
Why not use existing approaches?
--beans-path flag - Requires agents to include the flag on every.beans.yml in worktrees - Creates unwantedWhy an environment variable?
An environment variable is easy to set once, transparent across all
beans commands, safe from accidental commits, and follows standard
patterns for environment-specific configuration.
The beans path is now resolved in this order:
--beans-path flag (highest priority) - Explicit user overrideBEANS_PATH env var (medium priority) - Session/environmentExtracted resolveBeansPath() function (cmd/root.go):
os.Getenv("BEANS_PATH") when flag is emptyUpdated flag help text:
"Path to data directory (overrides config and BEANS_PATH env var)"8 test cases in cmd/root_test.go:
| Test | Verifies |
|---|---|
flag_takes_highest_precedence |
Flag wins over both env var and |
| config | |
flag_overrides_env_var |
Flag used even when BEANS_PATH is set to |
| invalid path | |
env_var_used_when_flag_is_empty |
BEANS_PATH is picked up when no |
| flag given | |
config_used_when_flag_and_env_var_are_empty |
Falls through to |
| config when neither is set | |
invalid_flag_path_returns_error |
Error: "does not exist or is not a |
| directory" | |
invalid_env_var_path_returns_error |
Same error for bad env var path |
|
| invalid_config_path_returns_init_suggestion | Suggests beans init
for config fallback |
| file_path_rejected_as_not_a_directory | Regular file (not dir) is
rejected |
# Set once for the session — all beans commands use it
export BEANS_PATH=/path/to/base-checkout/.beans
beans list
beans create "New task" -t task
# Flag still takes precedence when needed
BEANS_PATH=/default/path beans list --beans-path /override/pathNothing published for this version
Nothing published for this version
This release is all about atomicity and polish. The updateBean mutation has become the single, powerful entry point for all bean modifications — metad
This release is all about atomicity and polish. The updateBean mutation has become the single, powerful entry point for all bean modifications — metadata, body content, and relationships can now be updated in one atomic operation with proper concurrency control. The TUI also got a major usability upgrade with a two-column layout that lets you preview bean details without leaving the list among some other quality-of-life improvements.
Atomic bean updates — You can now combine metadata changes, body modifications, and relationship updates into a single updateBean call. Multiple text replacements, appends, status changes, and parent/blocking relationship updates all happen atomically with one ETag validation. This is a huge improvement for AI agents that previously had to chain multiple mutations with manual ETag extraction. (#72, #81)
ETag-based concurrency control — Beans now supports optimistic locking via ETags. When multiple agents work on the same bean, --if-match ensures no updates are silently lost. A race condition where two concurrent updates could both pass ETag validation has also been fixed by moving validation under the write lock. (#59)
Two-column TUI — The terminal UI now shows a detail preview alongside the bean list, so you can scan through beans without opening each one individually. The layout is responsive — it automatically drops to single-column on narrow terminals (below 120 columns). (#42)
Smarter blocker filtering — Completed and scrapped beans no longer count as blockers. If a bean was blocking your work but has since been completed, the blocked bean is now correctly treated as unblocked. (#80)
beans show now accepts multiple bean IDs, so you can inspect several beans at once (97ae9d1)beans delete supports multiple IDs for batch deletion (#66)beans list --ready filters for beans that are actionable — not blocked, excluding in-progress/completed/scrapped/draft (#40)beans create --prefix lets you specify a custom bean ID prefix (#56)beans version no longer requires a .beans directory to run (#28)--json mode (3c0bd52)space to select a bean and automatically jump to the next one for fast batch selection (#38)y) now copies all selected beans, not just the highlighted one (#37)--with-archived flag (#33)blocked_by relationships prevents circular dependency chains (#67)beans version to run without .beans directory (#28) (@sotte)Released by GoReleaser.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
This release brings quality-of-life improvements that make beans easier to use, especially when you're deep in an agentic workflow. The standout chang
This release brings quality-of-life improvements that make beans easier to use, especially when you're deep in an agentic workflow. The standout changes are the ability to quickly copy bean IDs in the TUI and the flexibility to use short IDs everywhere.
Copy bean IDs with a single keystroke — Press y in the TUI to copy the current bean's ID to your clipboard. This makes it trivial to reference beans in commit messages, documentation, or when working with the CLI. (#26)
Short IDs work everywhere — You can now use just the ID portion (e.g., abc1) instead of the full beans-abc1 format when querying via GraphQL. This reduces typing and makes commands more pleasant to work with. (93b6df0)
Documentation
Released by GoReleaser.
Nothing published for this version
This release focuses on performance improvements to the file watching system, making beans more responsive when you're actively editing beans alongsid
This release focuses on performance improvements to the file watching system, making beans more responsive when you're actively editing beans alongside the TUI. We've also added support for OpenCode integration.
Smarter file watching — The file watcher has been completely rearchitected. Instead of reloading all beans whenever any file changes, beans now processes only the affected files and updates the search index incrementally. This means faster response times, especially in projects with many beans. (f3b56cd)
Channel-based event subscriptions — The new watcher uses a fan-out pattern where multiple subscribers (like the TUI) each get their own event channel with typed events (Created, Updated, Deleted). Slow subscribers no longer block others, and the API is cleaner with Subscribe() returning an event channel and unsubscribe function. (63bd573)
OpenCode integration — Added a beans-prime.ts plugin for OpenCode users. Drop it into .opencode/plugin/ in your project (or ~/.opencode/plugin/ globally) to give your AI assistant beans context at session start. (2eabadd)
beans prime prompt for clearer agent instructions (bf9a4ec)Released by GoReleaser.
76dc94a : fix(tui): don't quit on Q when create modal is open ( @hmans )
7b07650 : fix: remove column headers from TUI list view ( @hmans )
It's still early days for Beans, so this release unfortunately includes some breaking changes.
This release brings major improvements to the TUI experience, making it faster and more intuitive to work with beans directly from your terminal. You can now manage almost every aspect of a bean without leaving the TUI; statuses, types, priorities, parents, and blocking relationships all have dedicated keyboard shortcuts.
More CLI commands are now using GraphQL internally, with the GraphQL schema gaining new filtering and mutation abilities that your agent can leverage for highly efficient interactions.
We've also added a full-text search index to allow for fuzzy search capabilities, making it easier for both yourself and your agent to find the right data quickly.
It's still early days for Beans, so this release unfortunately includes some breaking changes.
Simplified bean linking — The way beans link to each other has been fundamentally reworked. The old links field is gone, replaced by explicit parent and blocking fields. This makes relationships clearer and easier to work with. If you have existing beans using the old format, you'll need to migrate them manually (or ask your agent to do it; it'll usually do a good job with this). (#17)
Renamed 'backlog' status to 'draft' — The backlog status is now called draft, better reflecting its purpose as a holding area for beans that need refinement before they're ready to work on. Update any scripts or workflows that reference the old status name. (3673945)
Renamed beans query to beans graphql — The command for running GraphQL queries has been renamed to better describe what it does. (ddb1754)
TUI picker modals for everything: Press s to change status, t for type, P for priority, p for parent, and b for blocks. Each opens a focused picker modal that lets you make changes instantly. No more context switching to the command line for simple updates. (ad3382e, 8910c67, 95710b8, 2bfe0fe, 9565a9c)
Multi-select mass editing — Select multiple beans with Space, then apply changes to all of them at once. Perfect for triaging a batch of bugs or moving several tasks to in-progress. (8fd3d29)
Create and edit beans from the TUI — Press c to create a new bean (defaults to draft status), or e to open the current bean in your editor. Changes are automatically detected when you save and close. (5c6f192, 10c805d)
Responsive terminal width handling — Both beans list and the TUI now adapt intelligently to your terminal width, showing more tags and information when space is available, and gracefully degrading on narrow terminals without crashing. (769fba8, 9e32a11)
beans c and beans new now work as aliases for beans create. beans u works for beans update. (180c833, e9fbd3b)beans archive now shows you which beans will be archived before asking for confirmation. (43990e6)children, blockedBy, and blocking fields directly in your queries (e.g., get only incomplete children of a milestone). (e7019f6)beans prime command now searches parent directories for .beans.yml, making it work correctly from subdirectories. (6f8de83)beans list or the TUI. (207e43e)beans show --json output to be more useful. (89c02ac)Released by GoReleaser.
Nothing published for this version
6dc609d : feat: add tree view to beans list ( @hmans )
Nothing published for this version
129438e : feat!: remove $EDITOR integration from beans update ( @hmans )
beans prompt to beans prime (@hmans)Released by GoReleaser.
Nothing published for this version
v0.1.31 Compare # Choose a tag to compare
v0.1.31
Compare
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →