Quick Start Guide

1 Install Kollab

Install Kollab with uv. It fetches Python 3.12 for you if you don't have it:

Other ways: Homebrew on Apple Silicon Macs, an install script that needs no Python, pipx or pip. See Installation.

2 Launch Kollab

Start the application by running:

You'll see the Kollab welcome screen with the input prompt at the bottom. With no provider set up yet, Kollab opens the setup wizard by itself. Prefer a browser? kollab --web-ui opens the same agents there.

3 Set Up a Model With /setup

Kollab needs a model to talk to. /setup (also /onboard and /wizard) is a guided wizard, so you need no environment variables or hand-edited JSON:

1. Pick a provider: Anthropic, OpenAI with an API key, OpenAI with your ChatGPT sign-in, Google Gemini, OpenRouter, or Custom / Local for any OpenAI-compatible endpoint or a local model.
2. Add a key and confirm the endpoint. The key is optional for a local server.
3. Choose a model from the list, or type a model id.
4. Review. Press t to test the connection, then Enter to save and switch to it.

4 Start Chatting

Type your message and press Enter to send. Kollab supports:

• Multi-line input (Shift+Enter for new line)
• Conversation history (scroll to review)
• Real-time streaming responses
• Syntax highlighting for code

5 Use Slash Commands

Type / to see available commands:

6 Try Pipe Mode

Use Kollab in scripts with pipe mode for quick queries:

Or pipe from stdin:

7 Use Agents

Agents are custom configurations with specialized system prompts. Create agents in your project's .kollab/agents/ directory, or globally in ~/.kollab/agents/:

# Create an agent directory
mkdir -p .kollab/agents/code-reviewer

# Add a system prompt
cat > .kollab/agents/code-reviewer/system_prompt.md << 'EOF'
You are a code reviewer. Focus on:
- Code quality and best practices
- Potential bugs and edge cases
- Performance considerations
EOF

Switch to your agent:

8 Load Skills

Skills are markdown files that add specific instructions to your agent. Create a skill:

# Add a skill to your agent
cat > .kollab/agents/code-reviewer/security-check.md << 'EOF'
## Security Check Skill

When reviewing code, also check for:
- SQL injection vulnerabilities
- XSS attack vectors
- Hardcoded secrets or credentials
- Input validation issues
EOF

Load and unload skills dynamically:

9 Explore Plugins

Extend Kollab with plugins. Kollab loads plugins from the project's plugins/ directory and from the installed package; base classes live in the kollabor_plugins package:

# my_plugin.py
from kollabor_plugins import BasePlugin

class MyPlugin(BasePlugin):
    def register_hooks(self):
        self.register_hook('pre_user_input', self.my_handler)

    async def my_handler(self, context):
        # Your custom logic here
        return context