# Via Homebrew
brew install hmans/beans/beans

# Via Go
go install github.com/hmans/beans@latest

# Initialize beans in a project
beans init

# Verify setup and integrity
beans check

beans create "Implement user login"
# Creates new bean with auto-generated ID

beans create "Fix auth bug" --tag bug --tag urgent --type bug
# Creates bean with tags and type

beans create "Refactor API" --priority high --status todo
# Creates bean with priority and status

beans create "Add onboarding flow" --body "Scope: screens + copy"
# Adds body content

beans list                    # List all beans
beans list --tag urgent       # Filter by tag
beans list --status todo      # Filter by status
beans list --type feature     # Filter by type
beans list --search "login"   # Full-text search (Bleve query syntax)

beans update <id> --status in-progress
beans update <id> --title "New title"
beans update <id> --tag bug --remove-tag urgent
beans update <id> --priority high --type feature
beans update <id> --body "Updated scope notes"

beans show <id>               # Show full bean details
beans show <id> --body-only   # Only body content
beans show <id> --raw         # Raw markdown (no styling)

beans delete <id>             # Delete bean (prompts unless --force)
beans archive                 # Delete completed/scrapped beans

beans check                   # Validate config and bean graph
beans check --fix             # Auto-fix broken links/self-references
beans tui                     # Interactive terminal UI

beans roadmap                 # Markdown roadmap from milestones/epics
beans graphql '{ beans { id title status } }'

beans prime
# Outputs current beans, tags, and status for AI context

// ~/.opencode/plugin/beans-prime.ts
import type { Plugin } from "@opencode-ai/plugin";

export const BeansPrimePlugin: Plugin = async ({ $, directory }) => {
  let prime = undefined;

  try {
    const hasBeans = await $`which beans`.quiet();
    const hasConfig = await $`test -f ${directory}/.beans.yml`.quiet();

    if (hasBeans.exitCode === 0 && hasConfig.exitCode === 0) {
      const result = await $`beans prime`.cwd(directory).quiet();
      prime = result.stdout.toString();
    }
  } catch (e) {
    // Silently skip if beans not available
  }

  return {
    "experimental.chat.system.transform": async (_, output) => {
      if (prime) output.system.push(prime);
    },
    "experimental.session.compacting": async (_, output) => {
      if (prime) output.context.push(prime);
    },
  };
};

export default BeansPrimePlugin;

# In your repo's AGENTS.md:
IMPORTANT: before you do anything else, run `beans prime` and heed its output.

# Run before coding session
beans prime >> ~/.claude/context/beans.txt

# 1. Start work on a feature
beans create "Add dark mode support" --tag ui --type feature

# 2. Work on it, update progress
beans update <bean-id> --status in-progress --body "Started working on color scheme"

# 3. Complete the feature
beans update <bean-id> --status completed
beans update <bean-id> --body "Dark mode implemented for all views"

---
id: 12345678
title: "Implement user login"
status: todo
tags: [feature, auth]
priority: high
created: 2024-01-15T10:00:00Z
updated: 2024-01-15T14:30:00Z
---

## Description

Implement user login with email and password.

## Notes

- Use existing auth infrastructure
- Follow security best practices

# .beans.yml
directory: .beans
format: markdown
templates:
  default: |
    ---
    id: {{.ID}}
    title: "{{.Title}}"
    status: open
    created: {{.Created}}
    ---

    {{.Description}}