bentwookie 0.2.3

AI coding loop workflow manager with SQLite state and Claude Agent SDK integration

BentWookie

"I bent my wookie." - Ralph Wiggum

BentWookie - AI coding loop that manages development requests through a phase-based workflow using the Claude Agent SDK for execution, with centrally managed deployment and infrastructure configurations.

QuickStart

Using Claude Max (Recommended)

# Install
python -m pip install bentwookie

# Initialize with Claude Max subscription
bw init --auth max

# Create your first project and request
bw project create myapp --desc "My application"
bw request create myapp -n "Add login" -m "Implement user authentication"

# Start processing
bw loop start --foreground

Using API Key

# Initialize with API key mode
bw init --auth api

# Set your API key
export ANTHROPIC_API_KEY="your-key-here"

# Start processing
bw loop start --foreground

Overview

BentWookie v2 provides:

• SQLite Database: Persistent state management for projects and requests
• Claude Agent SDK Integration: Automated processing through development phases
• Phase-Based Workflow: plan → dev → test → deploy → verify → document → commit
• Git Integration: Automatic commit and push with AI-generated commit messages
• Project Customization: Project-level prompts and claude.md file integration
• Flexible Configuration: Global, project-level, and request-level settings
• CLI Interface: Full control via command line
• Web UI: Browser-based dashboard with auto-refresh for real-time status
• Daemon Mode: Background processing of queued requests
• Smart Workspace Detection: Automatically finds BentWookie workspace
• Editable Prompts: Phase templates in data/prompts/ - edit without restart
• Rate Limit Handling: Automatic retry with backoff on API limits

Installation

# Clone the repository
git clone -b AIGen02 https://github.com/bentwookie/bentwookie.git
cd bentwookie

# Create virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .

# Or install with dev dependencies (pytest, ruff, mypy, etc.)
pip install -e ".[dev]"

Requirements

• Python 3.10+
• SQLite (included with Python)
• Claude Agent SDK (claude-agent-sdk) - installed automatically
• Flask (for web UI) - installed automatically

Authentication

BentWookie supports two authentication modes:

Mode	Description	Setup
max	Claude Max subscription	Authenticate via claude CLI (web auth)
api	API key	Set ANTHROPIC_API_KEY environment variable

Claude Max (Recommended)

Uses your Claude Max subscription via the Claude Code CLI's web authentication:

# Ensure you're authenticated with Claude CLI
claude --version

# Initialize BentWookie with max mode
bw init --auth max

API Key

Uses the Anthropic API directly (requires credits):

# Initialize with API mode
bw init --auth api

# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

Get an API key at console.anthropic.com

Switching Modes

bw config --auth max    # Switch to Claude Max
bw config --auth api    # Switch to API key
bw config --show        # View current settings

CLI Commands

Initialization

bw init                      # Initialize (prompts for auth mode)
bw init --auth max           # Use Claude Max subscription
bw init --auth api           # Use API key
bw init --db-path ./my.db    # Custom database path

Configuration

bw config --show                        # View all current settings with descriptions
bw config --auth max                    # Switch to Claude Max mode
bw config --auth api                    # Switch to API key mode
bw config --max-turns 100               # Set max API calls per phase
bw config --poll-interval 60            # Set daemon poll interval (seconds)

# Commit phase configuration
bw config commit                        # Show current commit settings
bw config commit --enabled              # Enable commit phase globally
bw config commit --disabled             # Disable commit phase globally
bw config commit --branch current       # Commit to current branch
bw config commit --branch other --branch-name main  # Commit to specific branch

Project Management

bw project create <name>                          # Create a project
bw project create <name> -d "desc"                # With description
bw project create <name> -v mvp                   # Set version (poc, mvp, v1, v1.1, v2)
bw project create <name> -p 3                     # Set priority (1-10, lower = higher)
bw project create <name> --codedir /path/to/code  # Set default code directory
bw project create <name> --prompt "Use type hints and docstrings"  # Project-level guidelines
bw project create <name> --claude-md /path/to/claude.md  # Project-specific instructions

# Commit phase overrides (project-level)
bw project create <name> --commit                 # Enable commit phase for this project
bw project create <name> --no-commit              # Disable commit phase for this project
bw project create <name> --commit-branch current  # Use current branch
bw project create <name> --commit-branch other --commit-branch-name develop  # Use specific branch

bw project list                       # List all projects
bw project list --phase dev           # Filter by phase (dev, qa, uat, prod)

bw project show <name|id>             # Show project details
bw project delete <name|id>           # Delete project (and all requests)
bw project delete <name> --force      # Skip confirmation

Request Management

bw request create <project> -n "Name" -m "Prompt"    # Create request
bw request create <project> -n "Fix bug" -m "..." -t bug_fix
bw request create <project> -n "Add feature" -m "..." --priority 2
bw request create <project> -n "Feature" -m "..." --codedir /custom/path

# Commit phase overrides (request-level)
bw request create <project> -n "Feature" -m "..." --commit  # Force commit for this request
bw request create <project> -n "Feature" -m "..." --no-commit  # Skip commit for this request
bw request create <project> -n "Feature" -m "..." --commit-branch feature-branch  # Custom branch

bw request list                       # List all requests
bw request list --project myapp       # Filter by project
bw request list --status wip          # Filter by status (tbd, wip, done, err, tmout)
bw request list --phase dev           # Filter by phase

bw request show <id>                  # Show request details
bw request update <id> --status wip   # Update status
bw request update <id> --phase dev    # Update phase
bw request delete <id>                # Delete request

Daemon Control

bw loop start                    # Start daemon (background)
bw loop start --foreground       # Start in foreground (see output)
bw loop start --foreground -d    # Foreground with debug logging
bw loop start --poll 60          # Custom poll interval (seconds)
bw loop start --log logs/bw.log  # Custom log file

bw loop stop                     # Stop the daemon
bw loop status                   # Check if daemon is running

Logs are written to logs/{loopname}_{today}.log by default (e.g., logs/bwloop_2026-01-21.log).

Status & Web UI

bw status                        # Show system status
bw web                           # Start web UI (http://127.0.0.1:5000)
bw web --port 8080               # Custom port
bw web --host 0.0.0.0 --debug    # Public access with debug mode

How It Works

Request Phases

Requests progress through these phases automatically:

Phase	Description	Tools Available
plan	Analyze requirements, create implementation plan	Read, Glob, Grep
dev	Implement the changes	Read, Write, Edit, Bash, Glob, Grep
test	Run tests, verify quality	Read, Bash, Glob, Grep
deploy	Deploy to target environment (skipped for local-only)	Bash
verify	Verify deployment success (skipped for local-only)	Read, Bash, WebFetch, Glob, Grep
document	Update documentation	Read, Write
commit	Create git commit with AI-generated message (optional)	Bash, Read, Grep
complete	Request finished	-

Note: The deploy and verify phases are automatically skipped for local-only infrastructure. The commit phase can be enabled/disabled globally, per-project, or per-request.

Request Statuses

Status	Code	Description
Pending	tbd	Waiting to be processed
In Progress	wip	Currently being processed
Done	done	Completed successfully
Error	err	Failed with error
Timeout	tmout	Exceeded time limit

Request Types

• new_feature - New functionality
• bug_fix - Fix for existing bug
• enhancement - Improvement to existing feature

Commit Phase

The commit phase automatically creates git commits with AI-generated commit messages:

Features:

• Analyzes changes with git status and git diff
• Generates meaningful commit messages following best practices
• Supports current branch or specific target branch
• Pushes to remote automatically
• Never fails the request (errors logged as warnings)

Configuration:

# Global settings
bw config commit --enabled --branch current

# Project-level override
bw project create myapp --commit-branch other --commit-branch-name develop

# Request-level override
bw request create myapp -n "Feature" -m "..." --commit-branch feature-x

Branch Modes:

• current: Commit to whatever branch is currently checked out
• other: Commit to a specific named branch (creates if needed)

Project Customization

Project Prompt: Add default instructions that apply to all requests in a project:

bw project create myapp --prompt "Always use type hints and write docstrings"

Claude.md Integration: Link to a project's claude.md file for detailed project-specific instructions:

bw project create myapp --claude-md /path/to/myapp/claude.md

The content is appended to the system prompt for every request in that project.

Editable Prompts

Phase templates are stored in data/prompts/phases/ and can be edited directly:

# Edit the dev phase prompt
vim data/prompts/phases/dev.md

# Edit the system prompt
vim data/prompts/system.md

Changes take effect immediately - no restart required. Templates use Python string formatting with variables like {project_name}, {request_name}, {code_dir}, etc.

Rate Limit Handling

BentWookie automatically handles API rate limits:

• Detects rate limit errors (429, "too many requests", etc.)
• Keeps request as tbd so it gets retried (not marked as err)
• Pauses daemon for 60 seconds before retrying
• Logs warnings instead of errors for rate limits

Web UI

The web interface provides:

• Dashboard: Overview of projects, requests, and status counts
• Projects: Create, view, edit, and manage projects with full configuration
• Requests: Create, filter, and update requests with commit overrides
• System: Daemon status and system health with auto-refresh every 3 seconds

Access at http://127.0.0.1:5000 after running bw web.

Custom Port

bw web                    # Default port 5000
bw web --port 8080        # Custom port
bw web --host 0.0.0.0     # Allow external access

Database Schema

BentWookie uses SQLite with four main tables:

project            - Projects container
├── request        - Development requests (linked to project)
├── infrastructure - Infrastructure config (compute, storage, etc.)
└── learning       - Project learnings/notes

Key Fields

Project:

• Core: prjid, prjname, prjversion, prjpriority, prjphase, prjdesc
• Customization: prjprompt, prjclaudemd, prjcodedir
• Commit Config: prjcommitenabled, prjcommitbranchmode, prjcommitbranchname

Request:

• Core: reqid, prjid, reqname, reqtype, reqstatus, reqphase, reqprompt, reqpriority
• Paths: reqcodedir, reqplanpath, reqtestplanpath, reqdocpath
• Commit Config: reqcommitenabled, reqcommitbranch
• Testing: reqtestretries, reqerror

Infrastructure: infid, prjid, inftype, infprovider, infval, infnote

Request Infrastructure (overrides): rinfid, reqid, inftype, infprovider, infval, infnote

Learning: lrnid, prjid, lrndesc (prjid=-1 for global learnings)

Project Structure

src/bentwookie/
├── __init__.py           # Package exports
├── cli.py                # CLI commands (Click)
├── constants.py          # Configuration constants
├── models.py             # Data models (Project, Request, etc.)
├── settings.py           # Settings management (auth mode, etc.)
├── logging_util.py       # Logging configuration
├── db/
│   ├── __init__.py       # Database module exports
│   ├── connection.py     # SQLite connection manager
│   ├── queries.py        # CRUD operations
│   └── schema.sql        # Database schema
├── loop/
│   ├── __init__.py       # Loop module exports
│   ├── daemon.py         # Background daemon
│   ├── processor.py      # Request processor (Claude SDK)
│   └── phases.py         # Phase-specific logic
├── web/
│   ├── __init__.py       # Web module exports
│   ├── app.py            # Flask application
│   ├── templates/        # Jinja2 HTML templates
│   └── static/           # CSS styles
└── templates/
    └── phases/           # Bundled phase templates (fallback)
        ├── plan.md
        ├── dev.md
        ├── test.md
        ├── deploy.md
        ├── verify.md
        ├── document.md
        ├── commit.md
        └── system.md

data/
├── bentwookie.db         # SQLite database
├── settings.json         # Configuration settings
└── prompts/              # Editable prompt templates (created by bw init)
    ├── system.md         # System prompt template
    └── phases/           # Phase-specific prompts
        ├── plan.md
        ├── dev.md
        ├── test.md
        ├── deploy.md
        ├── verify.md
        ├── document.md
        └── commit.md
docs/                     # Generated documentation
logs/                     # Log files

**Note**: Templates in `data/prompts/` take precedence over bundled templates and can be edited without restarting. Changes take effect immediately.

Python API

from bentwookie import (
    init_db,
    create_project,
    create_request,
    list_requests,
)

# Initialize
init_db()

# Create project
prjid = create_project("myapp", prjdesc="My application")

# Create request
reqid = create_request(
    prjid=prjid,
    reqname="Add feature",
    reqprompt="Implement user dashboard",
    reqtype="new_feature",
)

# List pending requests
for req in list_requests(status="tbd"):
    print(f"{req['reqid']}: {req['reqname']}")

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest test/ -v

# Run linter
ruff check src/

# Run type checker
mypy src/bentwookie/

Configuration

Settings File

Settings are stored in data/settings.json:

{
  "auth_mode": "max",
  "model": "claude-opus-4-5",
  "max_turns": 50,
  "max_iterations": 5,
  "poll_interval": 30,
  "commit_enabled": true,
  "commit_branch_mode": "current",
  "commit_branch_name": null,
  "doc_retention_days": 30
}

Configuration Hierarchy

BentWookie uses a three-level configuration hierarchy for commit settings:

1. Request-level (highest priority) - Set on individual requests
2. Project-level (middle priority) - Set on projects
3. Global (lowest priority) - System-wide defaults in settings.json

Example:

• Global: Commit enabled, use current branch
• Project "myapp": Commit to "develop" branch (overrides global)
• Request #42: Commit disabled (overrides project and global)

This allows flexible control: most requests use defaults, but you can customize per-project or per-request as needed.

Log Path Placeholders

The default log path is logs/{loopname}_{today}.log. You can customize it:

bw loop start --log "logs/{loopname}_{today}.log"

Available placeholders:

• {today} - Current date (YYYY-MM-DD)
• {loopname} - Loop identifier
• {datetime} - Full datetime stamp

Troubleshooting

"No initialized BentWookie workspace found"

BentWookie looks for a workspace in:

1. Current directory
2. Parent directory
3. Immediate child directories

If you see this error:

cd /path/to/your/bentwookie/workspace
bw loop start

Or initialize a new workspace:

bw init

Daemon says "already running" but isn't

If the daemon crashed or was killed, the PID file may be stale:

rm data/bentwookie.pid
bw loop start --foreground --debug

Debug mode

Use --debug (or -d) for verbose logging:

bw loop start --foreground --debug

Check the log file at logs/bwloop_YYYY-MM-DD.log for detailed output.

Commit phase not running

Check if it's enabled:

bw config commit  # Show current settings

Enable it globally:

bw config commit --enabled

Or enable for specific project/request:

bw project create myapp --commit
bw request create myapp -n "Feature" -m "..." --commit

Migration from v1

BentWookie v2 replaces the file-based task system with SQLite:

v1	v2
Markdown task files	SQLite database
Stage directories (1plan, 2dev...)	Phase field on request
--init, --plan, --next_prompt	init, project, request, loop commands
Manual stage movement	Automatic phase progression

The v1 modules (core.py, config.py, wizard.py) are preserved for backwards compatibility.

License

MIT