BEANS

Unified autonomous development plugin for Claude Code combining git-backed issue tracking, spec-driven execution, and code intelligence tools.


What is BEANS?

BEANS is a Claude Code plugin that automates the entire software development lifecycle:

``
/beans "Add OAuth2 authentication"
`

This single command:
1. Creates a tracked issue (Beads)
2. Researches your codebase (Ralph)
3. Generates requirements, design, and tasks
4. Executes tasks autonomously with quality checks
5. Commits, pushes, and closes the issue

Features

$3

| Component | Purpose | Source |
|-----------|---------|--------|
| Beads | Git-backed issue tracking | package/beads/ |
| Ralph | Spec-driven autonomous execution | package/smart-ralph/ |
| Valyu | Knowledge retrieval MCP | package/valyu/ |
| Code Intelligence | AST analysis & snapshots | plugin/lib/ |

$3

| Agent | Role |
|-------|------|
| research-analyst | Codebase research and analysis |
| product-manager | Requirements generation |
| architect-reviewer | Technical design |
| task-planner | Task breakdown |
| spec-executor | Autonomous task execution |
| code-reviewer | Security, quality, performance review |
| test-engineer | Test coverage optimization (85%+) |
| optimizer | Fix issues found by reviewer |
| doc-generator | Documentation generation |
| integration-tester | E2E and integration tests |
| plan-synthesizer | Quick mode artifact generation |
| qa-engineer | Quality assurance |
| refactor-specialist | Code refactoring |

$3

- ast-grep - Pattern-based semantic code search
- repomix - AI-friendly codebase snapshots
- tree-sitter - AST parsing for 100+ languages
- ctags/cscope - Symbol navigation

Quick Start

$3

`bash


Install CLI from npm

npm install -g @morebeans/cli

Or with bun

bun install -g @morebeans/cli

Initialize in your project

cd /your/project
beans init
beans config --valyu # Set Valyu API key (optional)
beans doctor # Verify setup
`

$3

`bash
beans init # Initialize BEANS in current project
beans config # Configure API keys interactively
beans config --valyu # Set Valyu API key
beans config --github # Set GitHub token
beans config --show # Show current configuration
beans doctor # Check installation status
beans help # Show help
`

$3

API keys stored in ~/.beans/config.json:
`json
{
"valyu_api_key": "val_...",
"github_token": "ghp_..."
}
`

$3

`bash


In Claude Code:

/beans # List ready issues
/beans "Add dark mode toggle" # Full autonomous flow
/beans "Add dark mode" --quick # Quick mode (skip spec phases)
/beans task-042 # Build existing issue

Individual phases:

/beans:research # Research phase only
/beans:requirements # Requirements phase only
/beans:design # Design phase only
/beans:tasks # Task planning only
/beans:implement # Execute tasks

Beads commands:

/bd:create "Bug: login fails" # Create issue
/bd:show task-042 # Show issue details
/bd:ready # List unblocked issues
/bd:close task-042 # Close issue
`

Architecture

`
beans/
├── package/
│ ├── beads/ # Git-backed issue tracker (Go)
│ │ └── claude-plugin/ # 31 Claude Code commands
│ ├── smart-ralph/ # Spec-driven development
│ │ └── plugins/
│ │ ├── ralph-specum/ # Research→Design→Tasks→Execute
│ │ └── ralph-speckit/ # Constitution-first methodology
│ └── valyu/ # Knowledge retrieval MCP
│
└── plugin/ # Unified BEANS plugin
├── plugin.json # Manifest + hooks
├── CLAUDE.md # Documentation
├── commands/
│ ├── beans.md # Main /beans command
│ ├── bd/ # 31 beads commands
│ └── ralph/ # 13 ralph commands
├── agents/ # 13 subagents
├── skills/ # 10 skill definitions
├── templates/ # Spec templates
├── lib/
│ └── code-intelligence.sh # AST tools wrapper
├── config/
│ └── hooks.json # Auto-review hooks
└── scripts/
├── beans-setup.sh # Environment setup
├── verify-beans-setup.sh # Verify installation
├── build-unified.sh # Rebuild from sources
└── install.sh # Install to project
`

Workflow

$3

`
/beans "Add OAuth2 login"
│
▼
┌─────────────────┐
│ Create Issue │ → task-042
└────────┬────────┘
│
▼
┌─────────────────┐
│ Research │ → research.md
└────────┬────────┘
│ (user reviews, runs /beans:requirements)
▼
┌─────────────────┐
│ Requirements │ → requirements.md
└────────┬────────┘
│ (user reviews, runs /beans:design)
▼
┌─────────────────┐
│ Design │ → design.md
└────────┬────────┘
│ (user reviews, runs /beans:tasks)
▼
┌─────────────────┐
│ Tasks │ → tasks.md
└────────┬────────┘
│ (user runs /beans:implement)
▼
┌─────────────────┐
│ Execute │ Loops through tasks
│ + Quality │ code-reviewer → optimizer → test-engineer
└────────┬────────┘
│
▼
┌─────────────────┐
│ Complete │ Close issue, commit, push
└─────────────────┘
`

$3

`bash
/beans "Add OAuth2 login" --quick
`

Skips interactive phases, auto-generates all artifacts, starts execution immediately.

Hooks

| Event | Action |
|-------|--------|
| SessionStart | Load beads context (bd prime) |
| PreCompact | Preserve beads context |
| PostEdit | Auto-review with code-reviewer (haiku) |
| PreCommit | Run lint + tests |
| TaskComplete | Verify coverage + sync beads |

Code Intelligence

`bash


Source the library

source ~/.local/share/beans/code-intelligence.sh

AST-based code search

ag_find 'console.log($$$)' src/
ag_todos src/

Codebase snapshots

snapshot_codebase "task-001" "1"

File analysis

analyze_file src/app.ts

Directory analysis

analyze_directory src/
`

Environment Variables

`bash
export VALYU_API_KEY="..." # For Valyu research (optional)
export GITHUB_TOKEN="..." # For PR creation (optional)
`

Development

$3

`bash


Rebuild from source packages


./plugin/scripts/build-unified.sh
`

$3

The unified plugin merges:
- package/beads/claude-plugin/ → plugin/commands/bd/
- package/smart-ralph/plugins/ralph-specum/ → plugin/commands/ralph/, plugin/agents/
- Custom agents → plugin/agents/
- Code intelligence → plugin/lib/`

Related Projects

- Beads - Original git-backed issue tracker
- Smart Ralph - Spec-driven development plugins
- Claude Code Plugins - Official plugin docs

License

MIT License - see LICENSE for details.

---

BEANS v2.0 - Autonomous development, simplified.