npm package: @metabob/minibob
Description: Goal-first development vessel - everything is a goal processed through the activity/impulse system
Author: Metabob
Latest version: 0.4.3

# miniBob

A goal-first development assistant. Tell it what you want to accomplish and it figures out how to do it.

## Prerequisites

- [Bun](https://bun.sh) runtime (v1.0+)
- An Anthropic API key ([get one here](https://console.anthropic.com))

## Installation

### From npm (when published)

```bash
npm i -g @metaBob/miniBob@latest
```

### From source

```bash
git clone https://github.com/metaBobProject/metaBob-devBob
cd metaBob-devBob/repos/miniBob
bun install
```

## Quick Start

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

# Run your first goal
miniBob --single "create a hello world script"

# Or start interactive mode
miniBob
```

## Usage

### Interactive Mode (REPL)

```bash
miniBob
```

This starts an interactive session where you can type goals naturally:

```
> Fix the login bug in auth.ts
> Add unit tests for the user module
> Refactor the database connection to use connection pooling
```

### Single Goal Mode

Execute a single goal and exit:

```bash
miniBob --single "Create a hello world script"
miniBob -s "Add input validation to the signup form"
```

### CLI Flags

| Flag | Description |
|------|-------------|
| `-s, --single <goal>` | Execute a single goal and exit |
| `-q, --quiet` | Only show errors |
| `-v` | Verbose output (info, costs, durations) |
| `-vv` | Debug output |
| `-vvv` | Trace output |
| `--idle` | Start in bored state (works until interrupted) |
| `--caffeine` | Disable automatic boredom tasks |

### REPL Commands

| Command | Description |
|---------|-------------|
| `/help` | Show available commands |
| `/status` | Check connectivity and system status |
| `/config` | Show current configuration |
| `/auth` | Show and configure authentication |
| `/cheer[!]` | Positive feedback on last activity (add `!` for stronger) |
| `/chide[!]` | Negative feedback on last activity (add `!` for stronger) |
| `/continue` | Continue working on the last goal |
| `/bye` | Exit the REPL |

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ANTHROPIC_API_KEY` | Yes | Your Anthropic API key (for LLM) |
| `METABOB_API_KEY` | No | metaBob backend key (enables learning features) |
| `MINIBOB_MODEL` | No | Model to use (default: claude-sonnet-4-20250514) |
| `MINIBOB_WORKDIR` | No | Working directory |
| `MINIBOB_PROVIDER` | No | LLM provider: `anthropic` or `openai` |

### Config File

Create `~/.metaBob/config.json` for persistent settings:

```json
{
  "providers": {
    "anthropic": { "apiKey": "sk-ant-..." }
  },
  "metaBob": {
    "apiKey": "your-metaBob-key"
  },
  "model": "claude-sonnet-4-20250514",
  "workingDirectory": "/path/to/default/project"
}
```

Only two keys are needed:
- **LLM key** (`providers.anthropic.apiKey`) - Required for miniBob to work
- **metaBob key** (`metaBob.apiKey`) - Optional, enables activity learning and recommendations

Or create `.metaBob/config.json` in your project for project-specific settings.

## Offline Mode

miniBob works without network connectivity using embedded templates and local caching. When the backend is unavailable:

- Uses built-in activity templates
- Caches executions locally for later sync
- Intelligent template selection based on goal keywords

No configuration needed - offline mode activates automatically.

## Examples

```bash
# Create a new feature
miniBob -s "Add a logout button to the navbar"

# Fix a bug
miniBob -s "Fix the 404 error on the /users endpoint"

# Refactor code
miniBob -s "Extract the validation logic into a separate module"

# Write tests
miniBob -s "Add unit tests for the OrderService class"

# Documentation
miniBob -s "Update the API documentation for the new endpoints"
```

## Troubleshooting

### Check system health

```bash
miniBob doctor
```

### Common issues

**No API key configured**
```bash
export ANTHROPIC_API_KEY=sk-ant-...
# Or add to ~/.metaBob/config.json
```

**Goal not achieving expected results**
- Use `-v` for verbose output to see what miniBob is doing
- Use `/chide` to provide negative feedback and help it learn
- Try rephrasing your goal more specifically

## Documentation

- [CLAUDE.md](./CLAUDE.md) - Development guidelines and architecture
- [CHANGELOG.md](./CHANGELOG.md) - Version history