# ExoBrain CLI

> A Python CLI reasoning engine for AI agents. Sends prompts to OpenRouter or any OpenAI/Anthropic-compatible endpoint, returns responses. Works as CLI, MCP tool, or Python library. v0.2.5.

## Install

```bash
# Preferred (isolated, fast)
uv tool install exobrain-cli

# Alternatives
pipx install exobrain-cli
pip install exobrain-cli

# From source
git clone https://github.com/sl-build/exobrain.git
cd exobrain && uv pip install -e .

# Verify
exobrain --version   # exobrain 0.2.x
```

Requires Python 3.11+.

## Quick start for agents

1. Install: `uv tool install exobrain-cli`
2. Set API key: `exobrain init`
3. Add to SOUL.md or system prompt:
```
You have an external reasoning engine. Use `exobrain think "..."` for complex reasoning, planning, and analysis.
```
4. (Optional) Add the ExoBrain skill from `skills/exobrain.md` for structured usage patterns.

## Setup (one-time)

**Interactive:**
```bash
exobrain init
```
Walks through: provider choice, API key, default model, connection test.

**Non-interactive (agent-friendly):**
```bash
# 1. Set API key in env
export OPENROUTER_API_KEY="sk-or-v1-..."

# 2. Optional: set default model
exobrain config-set model openai/gpt-4o
exobrain config-set timeout 300   # seconds, default 180

# 3. Verify
exobrain status
exobrain providers
exobrain think "Reply with OK" --raw
```

## Use

```bash
exobrain think "How does async/await work?"
exobrain think "Explain" --context-file code.py
cat err.log | exobrain think "Why?" --stdin-context
exobrain think "hi" --provider opencode_go --model qwen3.7-max --raw
```

Output is the model's reply to stdout. Use `--json` for structured, `--stats` for token counts on stderr.

## Custom providers

Add `[providers.<name>]` to `~/.config/exobrain/config.toml`:

```toml
[providers.opencode_go]
type = "anthropic-compatible"
base_url = "https://opencode.ai/zen/go/v1"
api_key_env = "OPENCODE_GO_API_KEY"
models = ["qwen3.7-max", "qwen3.6-plus"]
default_model = "qwen3.7-max"
```

Then set the key: `export OPENCODE_GO_API_KEY="sk-..."` and use:
`exobrain think "hi" --provider opencode_go --model qwen3.7-max`.

Adapter type → API format:
- `openai-compatible` → OpenAI `/chat/completions` (uses `openai` SDK)
- `anthropic-compatible` → Anthropic `/messages` (uses `anthropic` SDK)

## Flags for `think`

| Flag | Effect |
|---|---|
| `--provider` / `-P` | Provider name (built-in: `openrouter`) |
| `--model` / `-m` | Model ID, scoped to provider (no `provider/model` syntax) |
| `--profile` / `-p` | Reasoning profile (see `exobrain profiles`) |
| `--depth` / `-d` | `quick` \| `normal` (default) \| `deep` \| `exhaustive` |
| `--context` / `-c` | Inline context string |
| `--context-file` / `-f` | Path to context file |
| `--stdin-context` / `-s` | Read context from stdin |
| `--max-tokens` / `-t` | Override max output tokens (default 16384) |
| `--temperature` | Override temperature |
| `--raw` / `-r` | Skip system prompt (faster, no profile) |
| `--json` / `-j` | Strip code fences, output clean JSON |
| `--stats` | Print usage stats to stderr |
| `--plan` | Use planner profile, produce structured plan |
| `--session-id` | Isolate plan state |

## Built-in commands

| Command | Purpose |
|---|---|
| `exobrain` | Quickstart text |
| `exobrain init` | First-time setup wizard |
| `exobrain status` | Show config + key source + provider list, optional ping |
| `exobrain providers` | Table of all providers (built-in + custom) |
| `exobrain config` | Show `[defaults]` from config.toml |
| `exobrain config-set KEY VAL` | Set `provider`, `model`, or `timeout` |
| `exobrain think PROMPT` | Run prompt through model |
| `exobrain plan [done\|block REASON]` | Manage structured plan |
| `exobrain key` | Show key location |
| `exobrain key-set KEY` | Save key to `~/.hermes/profiles/<active>/.env` |
| `exobrain profiles` | List profiles |
| `exobrain profile-add NAME --prompt PROMPT [--depth D] [--temp T]` | Add profile |
| `exobrain profile-remove NAME` | Remove profile |
| `exobrain profile-show NAME` | Show profile details |

## Files & paths

| Path | Purpose |
|---|---|
| `~/.config/exobrain/config.toml` | User config (defaults + custom providers) |
| `~/.hermes/profiles/<active>/.env` | API keys (sourced by `exobrain` wrapper) |
| `~/.hermes/.env` | Global API keys (fallback) |
| `~/.local/bin/exobrain` | CLI binary (after `uv tool install`) |

## API key resolution order

1. Env var `<api_key_env>` from config.toml
2. Generic `EXOBRAIN_API_KEY` env var
3. `~/.hermes/profiles/<active>/.env` (parsed)
4. `~/.hermes/.env` (parsed)
5. For OpenRouter: also checks `OPENROUTER_API_KEY`
6. Interactive prompt (saves to profile .env)

## Python API

```python
from exobrain import client

# High-level
text = client.call_and_print(
    prompt="Explain this",
    provider="openrouter",     # or custom name
    model="openai/gpt-4o",     # optional
    depth="deep",              # quick|normal|deep|exhaustive
    show_stats=True,
)

# Low-level
from exobrain.provider import complete
text, stats = complete(
    messages=[{"role": "user", "content": "Hello"}],
    model="qwen3.7-max",
    provider="opencode_go",
    max_tokens=256,
    temperature=0.3,
)
print(text, stats.prompt_tokens, stats.completion_tokens)
```

## Common errors

| Error | Cause | Fix |
|---|---|---|
| `OPENROUTER_API_KEY not found` | Key not in env or .env | `export OPENROUTER_API_KEY=...` or `exobrain init` |
| `Request timeout` | Model slow + low timeout | `exobrain config-set timeout 300` |
| `Model not supported for format oa-compat` | Used wrong adapter type | Set `type = "anthropic-compatible"` for Anthropic-style endpoints |
| `Invalid body format` | Provider expects fields CLI didn't send | Check `type` matches the provider's actual API |
| `Unknown provider` | Provider not in config | `exobrain providers` to see available; add custom in config.toml |
| `exobrain: command not found` | PATH missing `~/.local/bin` | Add `export PATH="$HOME/.local/bin:$PATH"` to shell rc |

## Exit codes

`0` success · `1` generic · `2` input error · `3` API failure · `4` bad response · `130` interrupted.

## Backward compat

`brain` = `exobrain` (alias). The `brain` wrapper script at `~/.local/bin/brain` sources the profile `.env` before calling `exobrain`, so you don't need to `export` keys in every shell.

## Source / docs

- Repo: https://github.com/sl-build/exobrain
- PyPI: https://pypi.org/project/exobrain-cli/
- Plugin (Hermes): https://github.com/sl-build/exobrain/tree/main/plugin

## MCP integration

ExoBrain exposes itself as MCP tools for Hermes. Tool IDs: `brain_think`, `brain_plan_done`, `brain_plan_block`. Install the plugin: `pip install exobrain hermes-exobrain`.

## License

MIT
