Configuration

Configure Kollab CLI using environment variables, configuration files, agents, and skills to customize your LLM workflow.

Environment Variables

A small set of environment variables control the API key and the system prompt. The model, endpoint, max tokens, and temperature are configured through profiles and loadouts, not environment variables.

API Key

# Global API key
KOLLAB_API_KEY=your-api-key-here

# Per-profile key (KOLLAB_<PROFILE>_<FIELD> pattern)
KOLLAB_CLAUDE_API_KEY=your-anthropic-key-here

System Prompt Configuration

# Option 1: Direct string
KOLLAB_SYSTEM_PROMPT="You are a helpful coding assistant."

# Option 2: Path to custom prompt file
KOLLAB_SYSTEM_PROMPT_FILE="./my_custom_prompt.md"

Priority Order: CLI --system-prompt flag > KOLLAB_SYSTEM_PROMPT > KOLLAB_SYSTEM_PROMPT_FILE > local .kollab/agents/default/system_prompt.md > global ~/.kollab/agents/default/system_prompt.md

Using .env Files

# Create .env file
KOLLAB_API_KEY=your-key-here
KOLLAB_SYSTEM_PROMPT_FILE="./prompts/specialized.md"

# Load and run
export $(cat .env | xargs)
kollab

Agents

Agents are custom configurations with specialized system prompts and skills. They're resolved from the local .kollab/agents/ directory in your project, or globally from ~/.kollab/agents/ (local wins).

Agent Directory Structure

.kollab/agents/
├── default/
│   └── system_prompt.md          # Base system prompt
├── lint-editor/
│   ├── system_prompt.md          # Agent's system prompt
│   ├── agent.json                # Optional configuration
│   ├── create-tasks.md           # Skill file
│   └── fix-file.md               # Another skill
└── code-reviewer/
    ├── system_prompt.md
    └── review-checklist.md

Agent Configuration (agent.json)

{
  "description": "Specialized linting and code fixing agent",
  "profile": "anthropic",
  "skills": ["create-tasks", "fix-file"]
}

Field	Description
`description`	Human-readable description of the agent
`profile`	Preferred LLM profile to use with this agent
`skills`	Skills to auto-load when agent is activated

Using Agents

# Switch to an agent

/agent lint-editor

# List available agents

/agent list

Skills

Skills are markdown files containing instructions or context that can be dynamically loaded into an agent's system prompt during a session.

Creating a Skill

Create a .md file in your agent's directory:

<!-- Skill for fixing linting errors -->

# Fix File Skill

When asked to fix linting errors:

1. Run the linter on the specified file
2. Parse the error output
3. Apply fixes one at a time
4. Verify each fix doesn't break tests
5. Commit with descriptive message

Using Skills

# Load a skill

/skill fix-file

# List available skills for current agent

/skills

# Unload a skill

/skills unload fix-file

Skills are appended to the system prompt under ## Skill: {name} headers, allowing the LLM to use the skill's instructions contextually.

Tools

Kollab supports tool calling, allowing the LLM to execute terminal commands, edit files, and interact with external services. Two parsing modes are available: Native API and XML-based.

Native Tool Calling

When using LLM providers that support native function calling (OpenAI, Anthropic, etc.), Kollab sends tool definitions directly to the API. The LLM responds with structured function calls that are executed automatically. Native mode is preferred when available.

When to use: Native mode is recommended when your LLM provider supports it. It provides more reliable parsing and better error handling than XML mode.

XML-Based Tool Calling

For LLMs without native function calling support, Kollab uses XML parsing. The LLM outputs tool calls using direct XML tags inline with its response text. Each tool type has its own tag structure.

Terminal Commands

<!-- Execute shell commands -->
<terminal>ls -la src/</terminal>
<terminal>git status</terminal>
<terminal>python -m pytest tests/</terminal>

File Operations

<!-- Read a file -->
<read><file>path/to/file.py</file></read>

<!-- Read specific lines -->
<read><file>path/to/file.py</file><lines>10-50</lines></read>

<!-- Edit a file (find and replace) -->
<edit>
  <file>src/main.py</file>
  <find>print("hello")</find>
  <replace>print("world")</replace>
</edit>

<!-- Create a new file -->
<create>
  <file>src/new_module.py</file>
  <content>
"""New module."""
import logging

def new_function():
    pass
  </content>
</create>

<!-- Append to a file -->
<append>
  <file>src/utils.py</file>
  <content>

def additional_helper():
    pass
  </content>
</append>

<!-- Delete a file -->
<delete><file>old_module.py</file></delete>

Directory Operations

<!-- Create directory -->
<mkdir><path>src/new_package</path></mkdir>

<!-- Remove directory -->
<rmdir><path>old_package</path></rmdir>

Advanced File Operations

<!-- Insert after a pattern -->
<insert_after>
  <file>src/main.py</file>
  <pattern>class MyClass:</pattern>
  <content>
    """Class docstring."""
  </content>
</insert_after>

<!-- Insert before a pattern -->
<insert_before>
  <file>src/main.py</file>
  <pattern>def main():</pattern>
  <content>
# Entry point
  </content>
</insert_before>

<!-- Move/rename a file -->
<move>
  <from>old_name.py</from>
  <to>new_name.py</to>
</move>

<!-- Copy a file -->
<copy>
  <from>template.py</from>
  <to>new_module.py</to>
</copy>

<!-- Search file for pattern -->
<grep>
  <file>src/main.py</file>
  <pattern>def.*async</pattern>
</grep>

Available Tools Reference

XML Tag	Description	Inner Tags
`<terminal>`	Execute shell commands	(command text)
`<read>`	Read file contents	file, lines (optional)
`<edit>`	Find and replace in file	file, find, replace
`<create>`	Create new file	file, content
`<append>`	Append to file	file, content
`<delete>`	Delete file	file
`<move>`	Move/rename file	from, to
`<copy>`	Copy file	from, to
`<mkdir>`	Create directory	path
`<rmdir>`	Remove directory	path
`<grep>`	Search file for pattern	file, pattern
`<insert_after>`	Insert after pattern	file, pattern, content
`<insert_before>`	Insert before pattern	file, pattern, content

MCP Tool Calls

For MCP (Model Context Protocol) tools, use the <tool> tag with attributes:

<!-- Call an MCP tool with attributes -->
<tool name="search_files" path="./src" pattern="*.py"></tool>

<!-- Alternative: tool_call with JSON -->
<tool_call>{"name": "search_files", "arguments": {"path": "./src"}}</tool_call>

Safety Features

Feature	Description
Auto Backups	Backups are written to ~/.kollab/projects/<encoded-path>/backups/ before edits and deletions
Protected Paths	main.py and the application module are protected by default, along with .git/, venv/, .venv/, and node_modules/ trees
Syntax Validation	Python files are validated; automatic rollback on syntax errors
Shell Output Limits	Shell command output is capped at 10MB

Note: The <edit> tag replaces ALL matches of the find pattern. Use enough context in your find string to make the pattern unique.

Configuration File

Kollab uses a JSON configuration file located at:

~/.kollab/config.json

Settings are read with dot notation, for example kollabor.llm.max_history. Example configuration:

{
  "kollabor": {
    "llm": {
      "max_history": 999,
      "enable_streaming": true,
      "terminal_timeout": 120
    }
  },
  "plugins": {
    "hook_monitoring": {
      "enabled": true
    }
  }
}

Directory Structure

A local .kollab/ directory in your project is optional and holds project-specific agents and configuration overrides. User-wide data lives under ~/.kollab/:

.kollab/                     # Optional, per-project
├── config.json               # Project-specific overrides
└── agents/                   # Project-specific agents
    └── default/
        └── system_prompt.md

~/.kollab/                    # User-wide
├── config.json               # User configuration
├── agents/                   # Global agents
└── projects/
    └── <encoded-path>/       # One directory per project
        ├── conversations/    # Conversation history (JSONL)
        └── logs/
            └── kollabor.log  # Application logs

Environment Variables Reference

Variable	Description	Default
`KOLLAB_API_KEY`	API key for the active provider	-
`KOLLAB_<PROFILE>_API_KEY`	API key scoped to one profile, e.g. KOLLAB_CLAUDE_API_KEY	-
`KOLLAB_SYSTEM_PROMPT`	Direct system prompt string	-
`KOLLAB_SYSTEM_PROMPT_FILE`	Path to system prompt file	-