Release Notes for v0.4.2

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.

Highlights

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)

Bug Fixes

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.

v0.4.2 Latest

Latest

Compare

Choose a tag to compare

Summary

Adds BEANS_PATH environment variable as an alternative to the
--beans-path CLI flag for specifying the beans data directory.

Motivation

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
  single command invocation, which is error-prone and easy to forget
• Modifying .beans.yml in worktrees - Creates unwanted
  modifications that might accidentally get committed or cause merge
  conflicts

Why 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.

Changes

Path Resolution Precedence

The beans path is now resolved in this order:

1. --beans-path flag (highest priority) - Explicit user override
2. BEANS_PATH env var (medium priority) - Session/environment
   setting
3. Config file (lowest priority) - Default behavior

Implementation

Extracted resolveBeansPath() function (cmd/root.go):

• Centralizes path resolution logic into a testable function
• Checks os.Getenv("BEANS_PATH") when flag is empty
• Context-aware error messages (explicit path vs config fallback)

Updated flag help text:

• "Path to data directory (overrides config and BEANS_PATH env var)"

Tests

8 test cases in cmd/root_test.go:

|
| 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 |

Usage

# 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/path

Release Notes for v0.4.0

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.

Highlights

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)

Other Improvements

CLI

• 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 output is now properly formatted in --json mode (3c0bd52)

TUI

• Press space to select a bean and automatically jump to the next one for fast batch selection (#38)
• Yanking (y) now copies all selected beans, not just the highlighted one (#37)

Architecture

• Bean archiving replaces deletion — completed and scrapped beans are archived for project memory instead of being permanently removed (#30)
• Archived beans are always loaded in the background, removing the need for a --with-archived flag (#33)
• Short IDs are now normalised when storing relationship links, preventing broken references (#50)
• Complete cycle detection for blocked_by relationships prevents circular dependency chains (#67)

Agent & Plugin

• Simplified and streamlined the agent prompt template for better compatibility with less capable models (#32, #31)
• OpenCode plugin now includes availability checks for improved robustness (#58)

Full Changelog

Features

• 726a3f2: feat(cli): Add --prefix flag to create command (#56) (@kyle-cassidy)
• aef7585: feat(list): add --ready workflow flag (#40) (@hmans)
• 3d3f841: feat(plugin): improve OpenCode plugin robustness with availability checks (#58) (@matleh)
• 97ae9d1: feat(show): support multiple bean IDs (@hmans)
• e1c178c: feat(tui): Two-column layout with detail preview (#42) (@sotte)
• b56c928: feat(tui): space selects bean and jumps to next one (#38) (@sotte)
• 179a71d: feat(tui): yank copies all selected beans, not just highlighted one (#37) (@sotte)
• ccb4845: feat: add ETag support for optimistic concurrency control (#59) (@matleh)
• b726959: feat: add body modification flags and GraphQL mutations (#60) (@matleh)
• 284bf3b: feat: archive beans for project memory instead of deleting (#30) (@hmans)
• 0845fde: feat: atomic bean updates with body modifications (#72) (@matleh)
• 6beaf6a: feat: atomic relationship updates in updateBean (#81) (@matleh)
• cb0fb2d: feat: ignore completed/scrapped blockers in isBlocked filter (#80) (@hmans)
• 4537e5b: feat: support multiple bean IDs in beans delete (#66) (@hmans)

Bug Fixes

• 7c7468a: fix(build): correct ldflags paths for version info in mise build (@hmans)
• b8d7053: fix(cli): allow beans version to run without .beans directory (#28) (@sotte)
• e9d4270: fix(list): --ready excludes in-progress beans (@hmans)
• 0e02dd2: fix(tui): Fix missing space between bean ID and type (#47) (@divaltor)
• e2c017d: fix: In the prompt primer, request the agent to check for existing beans before creating a new one (@hmans)
• 93ea28f: fix: add complete cycle detection for blocked_by relationships (#67) (@hmans)
• c36744a: fix: add trailing newline to bean files (#77) (@Maxi91f)
• d7b01db: fix: always load archived beans, remove --with-archived flag (#33) (@hmans)
• e8539e9: fix: cleanup prompt (@hmans)
• 2f47632: fix: normalise short IDs when storing relationship links (#50) (@Isoceth)
• 3c0bd52: fix: prettify JSON output in --json mode (@hmans)
• 74d84b0: fix: remove the in-progress check from the prompt (@hmans)
• 8a52faf: fix: trim down prompt (@hmans)
• e628ab1: fix: tweak prompt with instructions on what to do after working on a task (@hmans)

Other

• c7024e4: refactor(prompt): simplify agent instructions template (#31) (@czottmann)
• 5291e0e: refactor(prompt): simplify template for less capable models (#32) (@hmans)

Released by GoReleaser.

v0.4.0

Compare

Choose a tag to compare

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.

Highlights

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)

Other Improvements

Documentation

• Clarified completion rules: beans with unchecked todo items should NOT be marked as completed. This is particularly important for agentic workflows where the agent needs clear guidance on when work is actually done. (#27)

Changelog

Features

• a3d95eb: feat(tui): add 'y' shortcut to copy bean-id (#26) (@sotte)
• 1eb1f04: feat: add bean for agent-specific beans prime output (@hmans)
• 93b6df0: feat: support short IDs (without prefix) in GraphQL queries (@hmans)

Released by GoReleaser.

v0.3.4

Compare

Choose a tag to compare

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.

Highlights

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)

Other Improvements

• Refined the beans prime prompt for clearer agent instructions (bf9a4ec)

Bug Fixes

• Edge cases in the watcher are now handled gracefully: rapid updates to the same file coalesce properly, create+delete sequences are processed correctly, and invalid files are skipped without breaking the watcher

Changelog

Features

• 63bd573: feat: add channel-based file watcher with typed events (@hmans)

Bug Fixes

• bf9a4ec: fix: Tweak beans prime prompt (@hmans)

Performance

• f3b56cd: perf: update beancore state incrementally instead of full reload (@hmans)

Released by GoReleaser.

v0.3.3

Compare

Choose a tag to compare

Changelog

Bug Fixes

• 76dc94a: fix(tui): don't quit on Q when create modal is open (@hmans)

Released by GoReleaser.

v0.3.2

Compare

Choose a tag to compare

Changelog

Bug Fixes

• 7b07650: fix: remove column headers from TUI list view (@hmans)

Released by GoReleaser.

v0.3.1

Compare

Choose a tag to compare

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.

Breaking Changes

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)

Highlights

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)

Other Improvements

TUI

• Help overlay — Press ? to see all available keyboard shortcuts. (024656d, 95710b8)

CLI

• New command aliases — beans c and beans new now work as aliases for beans create. beans u works for beans update. (180c833, e9fbd3b)
• Archive preview — beans archive now shows you which beans will be archived before asking for confirmation. (43990e6)
• ID comments in front matter — Beans now include their ID as a comment in the YAML front matter, making it easier to reference them. (5607a1d)

GraphQL

• Filter parameters on relationship fields — You can now filter children, blockedBy, and blocking fields directly in your queries (e.g., get only incomplete children of a milestone). (e7019f6)

Other

• Prime command finds .beans.yml upward — The beans prime command now searches parent directories for .beans.yml, making it work correctly from subdirectories. (6f8de83)
• Unified CLI and TUI rendering — Bean rows now render consistently whether you're using beans list or the TUI. (207e43e)

Bug Fixes

• Fixed TUI crash when window width is very narrow. (9e32a11)
• Fixed glamour style detection causing startup delays. (ac15669)
• Fixed blocking picker showing an extra empty row. (cea0a19, 8a0daf4)
• Fixed tree continuation lines not rendering properly in list views. (b402b62)
• Fixed tags not showing when space was available in TUI. (0c5357f)
• Simplified beans show --json output to be more useful. (89c02ac)

Full Changelog

⚠️ Breaking Changes

• 3673945: feat!: rename 'backlog' status to 'draft' (@hmans)
• 142631e: feat!: simplify bean linking with explicit parent and blocks fields (#17) (@hmans)
• ddb1754: feat(cli)!: rename 'beans query' to 'beans graphql' (@hmans)

Features

• 43990e6: feat(archive): show bean list before confirmation prompt (@hmans)
• 180c833: feat(cli): add 'c' and 'new' aliases for 'beans create' (@hmans)
• e9fbd3b: feat(cli): add 'u' alias for 'beans update' (@hmans)
• 9565a9c: feat(tui): add 'b' shortcut to manage blocking relationships (@hmans)
• 7dd9fba: feat(tui): add 'c' shortcut to create new beans (@hmans)
• 10c805d: feat(tui): add 'e' shortcut to edit bean in external editor (@hmans)
• 2bfe0fe: feat(tui): add parent picker modal for changing bean parents (@hmans)
• 95710b8: feat(tui): add priority picker and help overlay (@hmans)
• ad3382e: feat(tui): add status picker modal with 's' shortcut (@hmans)
• 8910c67: feat(tui): add type picker modal with 't' shortcut (@hmans)
• 24f2bd9: feat(tui): show bean title in picker modals and consolidate modal code (@hmans)
• fe58dba: feat(tui): swap tags and title column order in list view (@hmans)
• 5c6f192: feat: TUI 'c' shortcut opens editor and defaults to draft status (@hmans)
• cb73e3a: feat: TUI updates updated_at when bean is saved in editor (@hmans)
• d34acbe: feat: add /generate-release-notes command (@hmans)
• 5607a1d: feat: add ID comment to bean front matter (@hmans)
• e7019f6: feat: add filter parameter to GraphQL relationship fields (@hmans)
• 8fd3d29: feat: add multi-select mass editing in TUI (@hmans)
• 769fba8: feat: make beans list responsive to terminal width (@hmans)

Bug Fixes

• 8a0daf4: fix(tui): fix blocking picker extra row and height issues (@hmans)
• f695195: fix(tui): improve blocking picker UX with batched changes (@hmans)
• cea0a19: fix(tui): prevent extra row appearing in blocking picker on toggle (@hmans)
• dc02402: fix(tui): refresh beans list when closing picker modals (@hmans)
• ac15669: fix(tui): use fixed glamour style to avoid slow terminal detection (@hmans)
• b402b62: fix: add proper tree continuation lines in list and TUI views (@hmans)
• b7aad89: fix: improve responsive tags display and add column headers (@hmans)
• 9e32a11: fix: prevent TUI crash when window width is very narrow (@hmans)
• 6f8de83: fix: prime command now searches upward for .beans.yml (@hmans)
• 0c5357f: fix: show more tags in TUI when space is available (@hmans)
• 89c02ac: fix: simplify beans show --json output (@hmans)

Other

• 024656d: refactor(tui): simplify help overlay (@hmans)
• 207e43e: refactor: unify CLI and TUI bean row rendering (@hmans)

Released by GoReleaser.

v0.3.0

Compare

Choose a tag to compare

Changelog

Features

• 6dc609d: feat: add tree view to beans list (@hmans)
• 529f053: feat: add tree view to beans tui (@hmans)
• 8feefe6: feat: provide Claude Code plugin marketplace (#13) (@hmans)

Released by GoReleaser.

v0.2.0

Compare

Choose a tag to compare

Changelog

⚠️ Breaking Changes

• 129438e: feat!: remove $EDITOR integration from beans update (@hmans)
• 64524b4: feat!: rename beans prompt to beans prime (@hmans)

Features

• c823e32: feat: add GraphQL mutations for bean CRUD operations (@hmans)
• bf738c4: feat: add full-text search using Bleve (#10) (@hmans)
• 5f7a6a6: feat: migrate show and roadmap commands to use GraphQL (@hmans)

Bug Fixes

• ce8c3c7: fix: Relax the prompt's opinion on TodoWrite (@hmans)

Other

• b3c576b: refactor: simplify create, update, delete commands (@hmans)

Released by GoReleaser.

v0.1.32

Compare

Choose a tag to compare

v0.1.31

Compare

Choose a tag to compare