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:

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