# Kollabor

[![Python Version](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/kollabor)](https://pypi.org/project/kollabor/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A terminal AI chat where **everything has hooks**. Every action -- user input, API calls, responses, tool use, rendering -- triggers hooks that plugins can intercept and modify. Use any LLM provider, build custom plugins, automate with pipe mode.

```bash
brew install kollaborai/tap/kollabor   # macOS
kollab                                  # start chatting
```

## Why Kollabor

Most terminal AI tools are closed boxes. Kollabor is an **open pipeline** -- every stage is a hook you can tap into.

- **Hook everything** -- intercept user input, transform API requests, post-process responses, modify tool calls
- **Plugin system** -- drop a Python file in `plugins/`, it auto-discovers and loads
- **Any provider** -- OpenAI, Anthropic, Google, Azure, OpenRouter, Ollama, LM Studio, or any OpenAI-compatible endpoint
- **OAuth login** -- use your ChatGPT subscription directly with `kollab --login openai`
- **MCP support** -- Model Context Protocol for tool integration
- **Pipe mode** -- `echo "query" | kollab -p` for scripting and automation
- **Agent system** -- multi-step task execution with tool calling
- **Slash commands** -- `/profile`, `/save`, `/terminal`, `/permissions`, and more

## Install

```bash
brew install kollaborai/tap/kollabor        # macOS (recommended)
```

```bash
curl -sS https://raw.githubusercontent.com/kollaborai/kollabor-cli/main/install.sh | bash  # cross-platform
```

Or manually: `uv tool install kollabor` / `pipx install kollabor` / `pip install kollabor`

## Quick Start

Kollabor auto-detects your API keys from standard environment variables:

| Environment Variable | Provider | Notes |
|---|---|---|
| `ANTHROPIC_API_KEY` | Anthropic | Claude models |
| `OPENAI_API_KEY` | OpenAI | GPT models |
| `GEMINI_API_KEY` | Google | Gemini models |
| `OPENROUTER_API_KEY` | OpenRouter | 300+ models from any provider |

```bash
export ANTHROPIC_API_KEY=sk-ant-...
kollab
```

That's it. No config files needed.

### OpenAI OAuth (ChatGPT subscription)

Use your existing ChatGPT Plus/Pro account -- no API key needed:

```bash
kollab --login openai
```

Opens your browser, you authorize, and you're in. Uses the Responses API with your subscription quota.

### Custom Profiles

For more control, create named profiles with env vars following the pattern `KOLLABOR_{NAME}_{FIELD}`:

```bash
# Local LLM via Ollama
KOLLABOR_LOCAL_PROVIDER=custom
KOLLABOR_LOCAL_BASE_URL=http://localhost:11434/v1
KOLLABOR_LOCAL_MODEL=llama3.1

kollab --profile local
```

Use `/profile` interactively to list, switch, and create profiles. See [FEATURES.md](docs/reference/FEATURES.md) for all configuration options.

### Pipe Mode

```bash
kollab "What is the capital of France?"        # direct query
echo "Explain this code" | kollab -p           # from stdin
cat document.txt | kollab -p                   # from file
kollab --timeout 5min "Complex analysis task"  # with timeout
```

## Providers

| Provider | Type | How to Connect |
|---|---|---|
| Anthropic | Native | `ANTHROPIC_API_KEY` |
| OpenAI | Native | `OPENAI_API_KEY` or `kollab --login openai` |
| Google Gemini | Native | `GEMINI_API_KEY` |
| Azure OpenAI | Native | `KOLLABOR_AZURE_*` env vars |
| OpenRouter | Gateway | `OPENROUTER_API_KEY` (300+ models) |
| Ollama | Custom | `KOLLABOR_LOCAL_BASE_URL=http://localhost:11434/v1` |
| LM Studio | Custom | `KOLLABOR_LMSTUDIO_BASE_URL=http://localhost:1234/v1` |
| Any OpenAI-compatible | Custom | `KOLLABOR_{NAME}_BASE_URL=...` |

## Hooks & Plugins

Every stage of the pipeline is hookable:

```
user input → pre_user_input → pre_api_request → [LLM API] → post_api_response → pre_message_display → output
                                                    ↓
                                              pre_tool_use → [tool execution] → post_tool_use
```

Write a plugin:

```python
from kollabor_plugins import BasePlugin
from kollabor_events import EventType, HookPriority

class MyPlugin(BasePlugin):
    def register_hooks(self):
        self.event_bus.register_hook(
            EventType.PRE_API_REQUEST,
            self.on_request,
            priority=HookPriority.NORMAL
        )

    async def on_request(self, context):
        # inject custom headers, modify messages, add tools, whatever
        context["headers"]["X-Custom"] = "value"
        return context
```

Drop it in `plugins/` and it loads automatically. Plugins can register slash commands, add status bar widgets, merge config, and hook into 30+ event types.

## Slash Commands

| Command | Description |
|---|---|
| `/profile` | List, switch, create LLM profiles |
| `/save` | Save conversation (markdown, jsonl, clipboard) |
| `/terminal` | Manage tmux sessions |
| `/permissions` | Configure tool approval modes |
| `/login` | OAuth login (OpenAI) |
| `/mcp` | Manage MCP servers |
| `/resume` | Resume a previous conversation |
| `/help` | Show all available commands |

Type `/` in the app to see the full command menu with 20+ commands.

## Architecture

Kollabor is a monorepo. Each package is independently versioned and installable.

| Package | What it does |
|---|---|
| [kollabor-ai](packages/kollabor-ai) | LLM providers, profiles, OAuth, streaming |
| [kollabor-agent](packages/kollabor-agent) | Tool execution, MCP, permissions |
| [kollabor-tui](packages/kollabor-tui) | Terminal UI, rendering, design system |
| [kollabor-events](packages/kollabor-events) | Event bus, hook registry |
| [kollabor-config](packages/kollabor-config) | Configuration system |
| [kollabor-plugins](packages/kollabor-plugins) | Plugin framework, SDK |
| [kollabor-engine](packages/kollabor-engine) | Web UI backend |

The `kollabor/` directory is a thin orchestration layer that wires the packages together.

```
.
├── kollabor/                  # Orchestration (app lifecycle, CLI, commands)
├── packages/                  # Independent packages (see table above)
├── plugins/                   # Plugin implementations
├── tests/                     # Test suite
└── main.py                    # Entry point
```

## Development

```bash
git clone https://github.com/kollaborai/kollabor-cli.git
cd kollabor-cli
pip install -e ".[dev]"
python main.py
```

```bash
python tests/run_tests.py                    # all tests
python -m black kollabor/ plugins/ tests/    # format
python -m mypy kollabor/ plugins/            # type check
```

See [CLAUDE.md](CLAUDE.md) for architecture details, coding standards, and contribution guidelines.

## Links

- [Quick Start Guide](docs/reference/quick-start.md)
- [Feature Reference](docs/reference/FEATURES.md)
- [Plugin Development](docs/reference/plugin-development-tutorial.md)
- [Bug Tracker](https://github.com/kollaborai/kollabor-cli/issues)

## License

MIT
