1# rumilo
  2
  3Rumilo is a CLI that dispatches specialized research subagents. It supports two modes:
  4
  5- `web` for web research (search + fetch, stored in a sandboxed workspace)
  6- `repo` for git repository exploration (clone to workspace, git-aware tools)
  7
  8## Requirements
  9
 10- Bun
 11- Git (for repo mode)
 12- Kagi session token
 13- Tabstack API key
 14
 15## Configuration
 16
 17Rumilo reads configuration from `$XDG_CONFIG_HOME/rumilo/config.toml`.
 18
 19Example:
 20
 21```toml
 22[defaults]
 23model = "anthropic:claude-sonnet-4-20250514"
 24cleanup = true
 25
 26[web]
 27model = "anthropic:claude-sonnet-4-20250514"
 28
 29[repo]
 30model = "anthropic:claude-sonnet-4-20250514"
 31```
 32
 33### Custom Models
 34
 35You can define custom OpenAI-compatible endpoints like Ollama, vLLM, or self-hosted models in the `[custom_models]` section:
 36
 37```toml
 38[custom_models.ollama]
 39provider = "ollama"
 40api = "openai-completions"
 41base_url = "http://localhost:11434/v1"
 42api_key = "ollama"
 43id = "ollama/llama3"
 44name = "Llama 3 (Ollama)"
 45reasoning = false
 46input = ["text"]
 47cost = { input = 0, output = 0 }
 48context_window = 128000
 49max_tokens = 4096
 50```
 51
 52Use custom models with the `custom:` prefix:
 53
 54```bash
 55rumilo web "query" --model custom:ollama
 56rumilo repo -u <uri> "query" --model custom:ollama
 57```
 58
 59#### Custom Model Fields
 60
 61- `provider`: Provider identifier (e.g., "ollama", "custom")
 62- `api`: API type - typically "openai-completions"
 63- `base_url`: API endpoint URL
 64- `api_key`: API key (see value resolution below)
 65- `id`: Unique model identifier
 66- `name`: Human-readable display name
 67- `reasoning`: Whether the model supports thinking/reasoning
 68- `input`: Input modalities - `["text"]` or `["text", "image"]`
 69- `cost`: Cost per million tokens (can use 0 for local models)
 70- `context_window`: Maximum context size in tokens
 71- `max_tokens`: Maximum output tokens
 72- `headers`: Optional custom HTTP headers (values support same resolution as `api_key`)
 73
 74#### Value Resolution
 75
 76The `api_key` and `headers` fields support three formats, following [pi-coding-agent conventions](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/docs/models.md):
 77
 78- **Environment variable name:** bare name is checked as env var, then used as literal
 79  ```toml
 80  api_key = "MY_API_KEY"   # resolves process.env.MY_API_KEY, or literal "MY_API_KEY"
 81  ```
 82- **Env var reference:** explicit `$VAR` or `${VAR}`
 83  ```toml
 84  api_key = "$MY_API_KEY"  # always resolves from env
 85  ```
 86- **Shell command:** `!command` executes and uses stdout
 87  ```toml
 88  api_key = "!security find-generic-password -ws 'my-api'"
 89  ```
 90
 91#### Compatibility Flags (Optional)
 92
 93Some OpenAI-compatible endpoints have quirks. Use the `compat` section to override:
 94
 95```toml
 96[custom_models.mistral]
 97provider = "mistral"
 98api = "openai-completions"
 99base_url = "https://api.mistral.ai/v1"
100# ... other fields ...
101
102[custom_models.mistral.compat]
103max_tokens_field = "max_tokens"
104requires_tool_result_name = true
105requires_thinking_as_text = true
106requires_mistral_tool_ids = true
107```
108
109See [pi-ai documentation](https://deepwiki.com/badlogic/pi-mono/2.6-custom-models-and-compatibility) for all compat flags.
110
111### Credentials
112
113Set credentials either via config or environment:
114
115- `KAGI_SESSION_TOKEN`: Kagi session token
116- `TABSTACK_API_KEY`: Tabstack API key
117
118## Usage
119
120```bash
121rumilo web "how does X work"
122rumilo web -u https://example.com/docs "explain the auth flow"
123rumilo repo -u https://github.com/org/repo "how is caching implemented"
124```