businessman/README.md

businessman

A CLI tool that spawns a tmux session with Claude Code and Ralph, designed for interactive AI-assisted development workflows.

Overview

businessman creates a dedicated tmux session with two panes:

• Pane 0: Runs Claude Code with the Businessman skill initialized
• Pane 1: A bash shell ready to run Ralph for autonomous coding tasks

The tool fetches available models from a llama-swap API endpoint, lets you select a model, and configures Claude Code with appropriate context window settings based on the model's capabilities.

The Businessman Skill

The Businessman skill is a collaborative design assistant that works with Claude Code to break down tasks and spawn Ralph when needed. It does not require you to interact with Ralph directly unless you want to.

What the Businessman Skill Provides

Feature	Description
Collaborative Design	Engages in back-and-forth discussion to clarify requirements and design the approach
Prompt Generation	Creates versioned prompt files (e.g., prompt1.md, prompt2.md) based on your design discussion
Ralph Orchestration	Spawns Ralph in Pane 1 with the correct prompt file and agent settings
Status Monitoring	Lets you check Ralph's progress on demand via tmux commands

How It Works

When you initialize the Businessman skill, you enter a collaborative workflow:

1. You propose a task - "Let's build a CLI tool that manages todos"
2. Skill asks clarifying questions - "What commands should it support? How should it store data?"
3. You approve the design - After discussion, you confirm the approach
4. Skill spawns Ralph - The skill automatically starts Ralph in Pane 1 with a properly formatted prompt file
5. You monitor/interact - You can check Ralph's status or add context as needed

You do not need to manually run Ralph commands. The skill handles Ralph spawning and orchestration. If you prefer to run Ralph yourself directly in Pane 1, that's also possible - the skill just makes it easier.

Requirements

• Claude Code CLI (claude command)
• Open Ralph Wiggum (ralph command) - for autonomous coding
• tmux (for terminal multiplexing)
• jq (for JSON parsing)
• curl (for API requests)

Installation

1. Clone this repository
2. Run the installation script:

   ./install-businessman.sh
   

3. The script will:
   • Prompt for your llama-swap API endpoint
   • Install businessman to /usr/local/bin/businessman
   • Install the Businessman skill to ~/.claude/skills/businessman/SKILL.md

Usage

businessman [project-directory]

If no directory is specified, the current directory is used.

What happens when you run businessman:

1. Connects to your llama-swap API endpoint to fetch available models
2. Displays a list of models with their context lengths
3. Prompts you to select a model
4. Starts a new tmux session named businessman-<timestamp>
5. Configures Claude Code with the selected model and context settings
6. Attaches you to the session with Pane 0 ready for Claude interaction

API Endpoint Requirements

The businessman tool expects your llama-swap API endpoint to:

• Respond to GET /v1/models with a JSON response containing:
  • data[].id - The model identifier
  • data[].meta.llamaswap.context_length - The model's context window size (optional)

Example response format:

{
  "data": [
    {
      "id": "llama-3.1-8b",
      "meta": {
        "llamaswap": {
          "context_length": 8192
        }
      }
    }
  ]
}

Environment Variables

businessman exports the following environment variables to the tmux session:

Variable	Description
ANTHROPIC_BASE_URL	Set to your llama-swap API endpoint
ANTHROPIC_AUTH_TOKEN	Set to "dummy" (llama-swap doesn't require real auth)
ANTHROPIC_DEFAULT_SONNET_MODEL	Selected model ID
ANTHROPIC_DEFAULT_HAIKU_MODEL	Selected model ID
ANTHROPIC_DEFAULT_OPUS_MODEL	Selected model ID

Context-Aware Settings

If the selected model has a context length:

Context Size	Settings Applied
> 200,000 tokens	CLAUDE_CODE_DISABLE_1M_CONTEXT=0, CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000
<= 200,000 tokens	CLAUDE_CODE_DISABLE_1M_CONTEXT=1, CLAUDE_CODE_AUTO_COMPACT_WINDOW=<model-ctx>

If no context length is available:

• CLAUDE_CODE_DISABLE_1M_CONTEXT=1

Environment Variable Propagation

Important: The environment variables are written to a temporary file and sourced by each tmux pane at startup. This ensures Claude Code in Pane 0 receives the correct model settings. Do not delete the temporary environment file while the tmux session is running.

Using the Businessman Skill

The skill is automatically initialized when you run businessman. To use it manually after the session is running:

claude "Use the businessman skill to initialize our session"

The skill will then guide you through collaborative task design and automatically spawn Ralph in Pane 1 when you're ready to execute.

Tmux Session Management

• Pane 0: Claude Code (model selected during startup)
• Pane 1: Bash shell - can run Ralph directly or be orchestrated by the Businessman skill

To detach from the tmux session: Ctrl+b then d

To reattach: tmux attach -t businessman-<timestamp> (see the startup message for the session name)

To list sessions: tmux ls

Ralph Integration

Ralph runs in Pane 1 and can be used in two ways:

Via the Businessman Skill (Recommended)

The skill automatically spawns Ralph for you during collaborative design sessions. When you and the skill agree on a task design, the skill writes a prompt file and starts Ralph with the appropriate settings. You can check status with:

tmux capture-pane -pt :0.1

Direct Usage

You can also run Ralph manually in Pane 1:

ralph --prompt-file ./prompt1.md --max-iterations 5 --agent claude-code

Use ralph --status to check progress, and ralph --add-context "..." to inject hints if needed.

Summary

Approach	When to Use
Businessman skill + Ralph	Collaborative design with interactive clarification and automatic task breakdown
Direct Ralph usage	When you already have a specific prompt file and want to run it directly

License

MIT