npm package: @sanera/bingo
Description: Minimal Claude Code agent framework for building custom pipelines
Latest version: 0.4.0-beta.1

# Claude Code Agent Core

A minimal, stripped-down framework for building custom Claude Code agent pipelines.

This is a barebones version of the Bingo project, keeping only the core functionality for:
- Creating and executing Claude Code CLI commands
- Parsing JSON/text responses
- Session continuity management
- Basic exit detection

## Quick Start

### Option 1: Use Directly (Recommended for Testing)

```bash
# Create a project
./setup.sh my-project
cd my-project

# Run the agent loop
../bingo_loop.sh
../bingo_loop.sh --help     # Show options
../bingo_loop.sh --reset    # Reset session

# Run with tmux monitor
../bingo_tmux.sh spec.txt   # Run with tmux monitor
../bingo_tmux.sh --attach   # Attach to running session
```

### Option 2: Install Globally

```bash
./install.sh

# Then from any directory:
bingo-setup my-project      # Create new project
cd my-project
bingo                       # Run agent loop
bingo-tmux                  # Run with tmux monitor
bingo-stop                  # Stop all agents and tmux session
bingo-monitor               # Show monitor panel only
bingo-init                  # Initialize in existing project
bingo-skills                # Generate project-specific skill files
```

## Core Functions

When you `source bingo_loop.sh`, you get access to these functions for building custom pipelines:

```bash
#!/bin/bash
source /path/to/bingo_loop.sh

# Initialize the agent environment
init_agent

# Load project configuration from .bingorc
load_config

# Execute agent and get output file path
output_file=$(execute_agent 1 "Custom context for iteration 1")

# Get the last analysis result (JSON)
analysis=$(get_last_analysis)
echo "Files modified: $(echo $analysis | jq '.analysis.files_modified')"

# Check if should exit
exit_reason=$(check_exit_condition)
if [[ -n "$exit_reason" ]]; then
    echo "Should exit: $exit_reason"
fi

# Reset session state
reset_session
```

### Available Functions

| Function | Description |
|----------|-------------|
| `init_agent` | Create directories and initialize state files |
| `load_config [file]` | Load configuration from `.bingorc` |
| `get_session` | Get current session ID for continuity |
| `save_session <output_file>` | Save session ID from Claude response |
| `reset_session` | Clear all session state |
| `build_claude_command <prompt> [context] [session_id]` | Build CLI command (populates `CLAUDE_CMD_ARGS`) |
| `execute_agent <loop_num> [context]` | Execute Claude and return output file path |
| `check_exit_condition` | Check if should exit (returns reason or empty) |
| `get_last_analysis` | Get last response analysis as JSON |

## Project Structure

```
my-project/
├── .bingo/
│   ├── PROMPT.md      # Instructions for the agent
│   ├── fix_plan.md    # Task list (checkboxes)
│   ├── AGENT.md       # Build/run instructions
│   ├── specs/         # Detailed specifications
│   └── logs/          # Execution logs
├── .bingorc           # Configuration
└── src/               # Your code
```

## Configuration (.bingorc)

```bash
# Project name
PROJECT_NAME="my-project"

# Timeout per execution (minutes)
CLAUDE_TIMEOUT_MINUTES=15

# Output format: json or text
CLAUDE_OUTPUT_FORMAT="json"

# Allowed tools (comma-separated)
ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *)"

# Session continuity
CLAUDE_USE_CONTINUE=true
SESSION_EXPIRY_HOURS=24

# Skills directory
SKILLS_DIR=".claude/skills"
```

## Status Reporting

The agent expects Claude to output a status block:

```
---BINGO_STATUS---
STATUS: IN_PROGRESS | COMPLETE | BLOCKED
FILES_MODIFIED: <number>
EXIT_SIGNAL: false | true
RECOMMENDATION: <brief summary>
---END_BINGO_STATUS---
```

Set `EXIT_SIGNAL: true` when all tasks are complete.

## Tmux Monitor

The tmux interface shows real-time agent activity with token tracking:

```
┌─────────────────────┬──────────────────┐
│                     │  TOKEN USAGE     │
│   Agent Output      │  Current: 12K    │
│   (bingo_loop.sh)   │  Average: 15K    │
│                     │  Total: 150K     │
│                     ├──────────────────┤
│                     │  TASK PROGRESS   │
│                     │  [████░░░] 60%   │
└─────────────────────┴──────────────────┘
```

Token stats tracked:
- **Current Agent**: Tokens used in the current/last iteration
- **Average Agent**: Average tokens per iteration
- **Total Used**: Cumulative tokens across all iterations

Controls: `Ctrl+b ←/→` switch panes, `Ctrl+b d` detach, `Ctrl+b z` zoom

## Project Skills

Skills are SKILL.md files in `.claude/skills/` that define project-specific standards. Workers automatically receive skill content as context and follow these specifications.

### Creating Skills

```bash
# Create a design skill from project description
bingo-skills design -d "E-commerce platform for artisan goods"

# Create from spec file
bingo-skills design project_spec.txt

# List available skill types
bingo-skills --list
```

### How Skills Work

1. **Generation**: `bingo-skills <type>` creates `.claude/skills/<type>/SKILL.md`
2. **Injection**: Workers automatically receive skill content in their context
3. **Enforcement**: Workers follow skill specifications as source of truth

## Example Custom Pipeline

```bash
#!/bin/bash
source ./bingo_loop.sh

init_agent
load_config

# Custom loop with your own logic
for i in {1..20}; do
    echo "=== Iteration $i ==="

    # Add custom context
    context="Iteration $i of 20. Focus on high-priority tasks first."

    # Execute
    output=$(execute_agent $i "$context")

    if [[ $? -eq 0 ]]; then
        # Success - check analysis
        analysis=$(get_last_analysis)
        files=$(echo "$analysis" | jq '.analysis.files_modified')
        echo "Modified $files files"

        # Your custom logic here
        # e.g., run tests, check coverage, etc.

        # Check exit condition
        if [[ $(check_exit_condition) == "project_complete" ]]; then
            echo "Project complete!"
            break
        fi
    else
        echo "Execution failed, retrying..."
        sleep 30
    fi

    sleep 5
done
```

## Requirements

- **jq** - JSON processing
- **git** - Version control
- **coreutils** - For `timeout` command (macOS: `brew install coreutils`)
- **Claude Code CLI** - `npx @anthropic-ai/claude-code` (downloaded automatically)

## File Reference

```
bingo_loop.sh           # Main agent core (source this for custom pipelines)
bingo_tmux.sh           # Tmux-based monitoring interface
setup.sh               # Create new projects
install.sh             # Global installation
lib/
  response_analyzer.sh # Parse Claude responses
  date_utils.sh        # Cross-platform date functions
  timeout_utils.sh     # Cross-platform timeout
  token_utils.sh       # Token estimation and tracking
  log_monitor.sh       # Real-time log monitor with token stats
templates/
  PROMPT.md            # Default agent instructions
  fix_plan.md          # Default task list template
  AGENT.md             # Default build instructions
  bingorc.template     # Default configuration
```

## License

MIT License - See [LICENSE](LICENSE)