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)

# 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

./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:

#!/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)

# 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

# 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

#!/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