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](#businessman-skill) initialized
- **Pane 1**: A bash shell ready to run [Ralph](https://github.com/Th0rgal/open-ralph-wiggum) for autonomous coding tasks

The tool fetches available models from a [llama-swap](https://github.com/dotcross/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](https://claude.ai/download) (`claude` command)
- [Open Ralph Wiggum](https://github.com/Th0rgal/open-ralph-wiggum) (`ralph` command) - for autonomous coding
- [tmux](https://github.com/tmux/tmux) (for terminal multiplexing)
- [jq](https://stedolan.github.io/jq/) (for JSON parsing)
- [curl](https://curl.se/) (for API requests)

## Installation

1. Clone this repository
2. Run the installation script:
   ```bash
   ./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

```bash
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:
```json
{
  "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`

## 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:
```bash
tmux capture-pane -pt :0.1
```

### Direct Usage
You can also run Ralph manually in Pane 1:
```bash
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