Configuration

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

Environment Variables

All configuration can be controlled via environment variables, which take precedence over config files.

API Configuration

# API endpoint URL
KOLLABOR_API_ENDPOINT=https://api.openai.com/v1/chat/completions

# API authentication token (also accepts KOLLABOR_API_KEY)
KOLLABOR_API_TOKEN=your-api-token-here

# Model name
KOLLABOR_API_MODEL=gpt-4o

# Maximum tokens for responses
KOLLABOR_API_MAX_TOKENS=4096

# Temperature (0.0-2.0)
KOLLABOR_API_TEMPERATURE=0.7

# Request timeout in milliseconds
KOLLABOR_API_TIMEOUT=30000

System Prompt Configuration

# Option 1: Direct string (highest priority)
KOLLABOR_SYSTEM_PROMPT="You are a helpful coding assistant."

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

Priority Order: KOLLABOR_SYSTEM_PROMPT > KOLLABOR_SYSTEM_PROMPT_FILE > local .kollabor-cli/system_prompt/default.md > global ~/.kollabor-cli/system_prompt/default.md

Using .env Files

# Create .env file
KOLLABOR_API_ENDPOINT=https://api.openai.com/v1/chat/completions
KOLLABOR_API_TOKEN=your-token-here
KOLLABOR_API_MODEL=gpt-4o
KOLLABOR_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 stored in the .kollabor-cli/agents/ directory.

Agent Directory Structure

.kollabor-cli/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",
  "default_skills": ["create-tasks", "fix-file"]
}

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

Using Agents

# Switch to an agent

/agent lint-editor

# List available agents

/agents

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

/skill -u fix-file

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

Tools

Kollabor 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.), Kollabor 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, Kollabor 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	.bak files created before edits, .deleted before deletions
Protected Paths	core/, main.py, .git/, venv/ are protected by default
Syntax Validation	Python files are validated; automatic rollback on syntax errors
File Size Limits	10MB for edits, 5MB for creates

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

Kollabor uses a JSON configuration file located at:

~/.kollabor-cli/config.json

Example configuration:

{
  "core": {
    "llm": {
      "api_endpoint": "https://api.openai.com/v1/chat/completions",
      "model": "gpt-4o",
      "temperature": 0.7,
      "max_tokens": 4096
    }
  },
  "terminal": {
    "theme": "dark",
    "status_bar": true
  },
  "plugins": {
    "hook_monitoring": {
      "enabled": true,
      "enable_plugin_discovery": true
    }
  }
}

Directory Structure

On first run, Kollabor creates a .kollabor-cli directory in your current working directory:

.kollabor-cli/
├── config.json               # User configuration
├── system_prompt/            # System prompt templates
│   └── default.md
├── agents/                   # Custom agents
│   └── default/
│       └── system_prompt.md
├── logs/                     # Application logs
│   └── kollabor.log
└── state.db                  # Persistent state

Environment Variables Reference

Variable	Description	Default
`KOLLABOR_API_ENDPOINT`	LLM API endpoint URL	OpenAI
`KOLLABOR_API_TOKEN`	API authentication token	-
`KOLLABOR_API_KEY`	Alias for KOLLABOR_API_TOKEN	-
`KOLLABOR_API_MODEL`	Model name/ID	gpt-4o
`KOLLABOR_API_MAX_TOKENS`	Maximum response tokens	4096
`KOLLABOR_API_TEMPERATURE`	Response randomness (0-2)	0.7
`KOLLABOR_API_TIMEOUT`	Request timeout (ms)	30000
`KOLLABOR_SYSTEM_PROMPT`	Direct system prompt string	-
`KOLLABOR_SYSTEM_PROMPT_FILE`	Path to system prompt file	-