Kollab

A terminal AI workspace for people who want their agents, tools, providers, plugins, and workflows to share one inspectable runtime.

Getting Started · Providers · Models · Agents · Web UI · Plugins · Hub

Kollab is a terminal-native AI workspace for developers who want more than a single chat box. It brings interactive chat, slash commands, provider profiles, model loadouts, tool permissions, MCP servers, plugins, pipe mode, a local browser UI, and collaborating agents into one CLI.

The point is not to hide the machinery. Kollab gives you a fast daily AI terminal, but it also exposes the runtime underneath it: every meaningful stage is hookable. User input, LLM requests, streamed responses, message display, tool calls, and post-tool results all move through an event pipeline that plugins can observe, transform, or block.

That lets Kollab do things that are still unusual in a terminal AI app: multiple agents can discover each other without a central server, exchange hub messages, carry task ledgers across context compaction, keep vault-backed memory, receive scheduled prompts, search and load tools on demand, preserve oversized tool results as inspectable artifacts, and advertise identity, trust, and capabilities through an experimental Agent DNS layer.

Kollab is still beta, and some of the ambitious pieces are being hardened. But the shape is already there: a local, inspectable AI workspace that can grow from one chat session into a small team of coordinated agents.

What Kollab Does

• Chat with frontier, local, or OpenAI-compatible models from a fast terminal UI.
• Switch providers and model profiles without leaving the session.
• Browse the model registry and activate named loadouts for model, effort, sampling, and output-budget presets.
• Use a ChatGPT subscription through OpenAI OAuth, or bring API keys for other providers.
• Run one-shot prompts and shell pipelines with kollab -p.
• Switch the session workspace at runtime so later file and terminal tools target a different project directory.
• Connect MCP servers for filesystems, GitHub, databases, browsers, search, and custom tools.
• Use built-in web-search and web-fetch tools with smart content extraction and bounded results.
• Gate shell, file, and MCP tool use through risk-aware approvals.
• Search and load native or MCP tools on demand instead of injecting every schema into every request.
• Launch specialized agents from bundled, global, or project-local definitions.
• Coordinate multiple terminal agents through the hub: status, messages, task ledgers, vault memory, attach mode, and recurring prompts.
• Keep long-running tasks alive across compaction with checkpoints, QA review, and reminder snoozes.
• Resolve agents by identity, capability, and trust with the experimental Agent DNS layer.
• Start the local engine and assistant-ui browser client together with kollab --web-ui.
• Extend the runtime with Python plugins, slash commands, widgets, XML tool tags, and JSON config hooks.
• Save, resume, inspect, and compact conversations as work evolves.

Why People Notice It

Kollab feels familiar at first: open a terminal, ask for help, use tools, keep working. The difference shows up once the work gets bigger than one prompt.

You can start a coding agent in one terminal, a reviewer in another, and a coordinator in a third. They join a project-scoped mesh automatically through presence files and Unix sockets. You can message them from the TUI or from the shell, attach to their output, assign durable tasks, schedule recurring check-ins, and inspect the memory they carry forward.

The result is a local agent workspace instead of a black-box automation. You can see who is online, what they were asked to do, what they produced, which tools were approved, and which hooks or plugins changed the flow.

Feature Tour

Agent Hub

The hub is Kollab's agent collaboration layer. Agents launched in the same project can discover each other automatically, communicate over local sockets, and coordinate through a shared command surface.

Keep these three names separate:

• identity — the stable hub name or mailbox, such as lapis. It is what /hub status, /hub msg, and /hub capture address.
• bundle — the behavior package, such as coder or research: system prompt, prompt sections, allowed tools, and declared skills.
• provider profile/loadout — the model connection and tuning. A profile owns credentials; a loadout combines a profile with a model and parameters such as effort or output budget.

This launch runs the coder bundle under the lapis identity with the openai-oauth provider profile:

kollab --agent coder --as lapis --llm openai-oauth

kollab --agent coder --as lapis
kollab --agent technical-writer --as sapphire
kollab --hub status
kollab --hub msg lapis "review the latest diff"
kollab --hub capture lapis 100

Hub features include:

• Zero-config peer discovery for local agents in the same project.
• Optional fixed identities with --as (for example, --as lapis) when you want stable names instead of auto-assigned identities.
• Direct messages, broadcasts, live output capture, and interactive attach mode.
• Durable task ledgers with active -> done -> QA review -> closed workflows, including the task_snooze reminder control.
• Vault-backed memory with raw streams, rolling working memory, and crystallized long-term notes.
• Recurring hub messages through /hub cron.
• Optional Telegram forwarding for remote check-ins.
• Organization launch files for starting multi-agent teams.

An offline inbox is durable mail waiting for a known identity; it is not a live process. capture only works for an online peer or active orchestrator session, so agent 'lapis' not found means there is no capturable live runtime under that name. A direct message can still be queued for the identity and delivered when it reconnects.

research is normally a bundle name, not a hub identity. Capture the identity shown by /hub status instead.

Agent DNS

Agent DNS is experimental, but it is one of the more forward-looking pieces of Kollab. It adds a discovery, identity, and trust layer on top of the hub so agents can be addressed by more than a process name.

The local DNS registry stores agent records with an ARDP-style identity such as agent:lapis@kollabor.ai, socket or endpoint bindings, capabilities, public keys, approval state, trust score, and runtime state. Public domain discovery uses a separate signed descriptor cache with persistent origin/key pins. Discovering a domain does not import its keys into the messaging registry or authorize tools.

/hub dns resolve
/hub dns resolve lapis
/hub dns find review
/hub dns trust lapis
/hub dns leaderboard
/hub dns endorse lapis review
/hub dns keys lapis
/hub dns endpoint
/hub dns connect example.com

Today this is best understood as an emerging trust and routing layer for local agent meshes: resolve who is online, find agents by capability, inspect key material, and track reputation through task outcomes and endorsements.

An optional off-box endpoint (plugins.hub.endpoint_enabled) binds a TCP/TLS listener that shares the same Ed25519 handshake, so a remote agent on another machine can authenticate and deliver messages over the network. It is disabled by default, always requires the handshake, and refuses to bind a plaintext port without an explicit opt-in. This historical direct stream transport is separate from the WSS relay and the standard A2A workspace receiver. See the direct endpoint reference.

Connect agents across machines

/connect makes the agents on your other machines part of the same hub. A hub message to agent@device reaches that machine and wakes that agent; the rest of the network observes it, like the local hub. Start with the connect guide:

# on the machine that is already connected
/connect                        # the screen: an 8-character code, one device, five minutes
# on the new machine
/connect                        # type the code into the private form
# back on the first machine, the request shows up on the screen: press a, or
/connect accept home-server
# then, from any agent or a shell
kollab --hub msg ops@home-server "check the tunnel"

kollab service install in the joined folder keeps that machine's agent online across crashes and reboots (systemd on Linux, launchd on macOS); kollab there attaches to it.

Run your own directory on your own domain with one command, kollab relay serve --domain agents.example.com: it prints the DNS record and the proxy routes it still needs, and --install keeps it running as a systemd service (kollab relay run --config is the form for several workers). The agent network contract is the design; the public beacon contract covers the relay's routes, limits and key handling.

How the network works

Both machines dial out to the directory on port 443, so nothing needs an open port. The directory relays frames by device key and can't open them.

Every message rides five layers deep. The directory reads the outer two; only your two daemons can open the rest.

The join, step by step: a code, a sealed mailbox, one key press

The agent network architecture has the rest: what travels and what stays, keeping a device online, how /connect uses your domain's DNS record, and running your own directory.

Browser UI and Local Engine

The optional browser surface uses the same provider, tool, permission, MCP, and hub runtime as the terminal app. From a source checkout or installed workspace:

kollab --web-ui
# browser: http://127.0.0.1:8080
# engine:  http://127.0.0.1:7433

The flag starts the local engine when needed, launches kollabor-webui, reuses a healthy engine on port 7433, and cleans up child processes on exit. For separate development loops, see the engine README and web UI README.

The web UI's Settings dialog (Session, Configuration, Loadouts, Model, Setup, Network) does what the terminal's /config, /llm, /model, /setup and /connect screens do; see web settings panels.

Why It Exists

Most AI CLIs are either chat windows or opaque automations. Kollab aims for the middle ground: a terminal workspace you can actually steer, inspect, and rewire. It is useful as a day-to-day coding chat, but the interesting part is the runtime beneath it: hooks, plugins, agents, permissions, MCP, and durable conversation state all share the same pipeline.

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

That pipeline is how the hub, permissions, context compaction, MCP, terminal sessions, save/resume workflows, and plugin-provided tools layer onto the same core app.

Status

Kollab is beta software. The CLI, provider integrations, plugin APIs, and agent workflows are usable today, but some advanced runtime, engine, and integration paths are still being hardened. See CHANGELOG.md and docs/release-process.md for release notes and release gates.

Install

Recommended installer:

curl -sS https://raw.githubusercontent.com/kollaborai/kollab/main/install.sh | bash
kollab

Python package managers:

pipx install kollab

pipx is the recommended installer: it puts kollab in its own isolated virtualenv, which sidesteps a class of startup failure where obsolete stdlib-backport packages (typing, asyncio, dataclasses, pathlib, ...) left in a shared interpreter shadow the standard library and crash kollab on launch. uv tool install kollab isolates the same way.

pip install kollab also works, but installs into the active interpreter and so inherits whatever is already there:

pip install kollab

On an externally managed system Python (including Arch), use an isolated environment. If pipx and uv are unavailable, Python itself is sufficient:

python3 -m venv ~/.local/share/kollab/venv
~/.local/share/kollab/venv/bin/python -m pip install --upgrade kollab
~/.local/share/kollab/venv/bin/kollab --login openai

This uses the published package without changing system Python. To run kollab by name in the current shell, activate the environment with source ~/.local/share/kollab/venv/bin/activate. For OpenAI account login, use --login openai at launch or /login openai inside the app.

Homebrew packaging is prepared separately after a release wheel is published and the formula SHA is available. Maintainer notes live in homebrew-tap/README.md.

Quick Start

New here? Launch Kollab and run /setup — a guided wizard walks you through picking a provider, entering your API key, choosing a model, optionally testing the connection, and saving it as your active profile. No env vars or JSON required. (ChatGPT sign-in delegates to /login; Azure/advanced is configured in config.json — see docs/providers.md.)

Prefer environment variables? Kollab also auto-detects common provider vars:

export OPENAI_API_KEY="<your-openai-api-key>"
kollab

By default, Kollab starts with the koordinator agent and joins the local hub mesh, so a plain kollab session is ready for multi-agent coordination.

Provider-specific model env vars are also supported for auto-detected profiles:

export OPENROUTER_API_KEY="<your-openrouter-api-key>"
export OPENROUTER_MODEL="deepseek/deepseek-v3.2"
kollab

Anthropic-compatible gateways can use the Claude Code-style env names:

export ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic"
export ANTHROPIC_AUTH_TOKEN="<your-token>"
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-4.7"
kollab

Use /llm inside Kollab to switch models and presets. For more configuration options, see docs/configuration.md, docs/providers.md, and docs/reference/env-vars.md.

You can also define profiles directly from environment variables:

# Pattern: KOLLAB_{PROFILE}_{FIELD}
export KOLLAB_WORK_MODEL=claude-sonnet-5
export KOLLAB_WORK_PROVIDER=anthropic
export KOLLAB_WORK_API_KEY="<your-anthropic-api-key>"
export KOLLAB_WORK_BASE_URL="https://api.anthropic.com"
# Optional tuning fields (TEMPERATURE/TOP_P are ignored on models that
# reject sampling params -- see bundles/data/models.json supports_sampling)
export KOLLAB_WORK_MAX_TOKENS=4096
export KOLLAB_WORK_TEMPERATURE=0.3
export KOLLAB_WORK_TIMEOUT=30
export KOLLAB_WORK_TOP_P=0.95
export KOLLAB_WORK_EFFORT=high
export KOLLAB_WORK_STREAMING=true
export KOLLAB_WORK_SUPPORTS_TOOLS=true
export KOLLAB_WORK_DESCRIPTION="Claude profile for work tasks"
# EXTRA_HEADERS must be valid JSON
export KOLLAB_WORK_EXTRA_HEADERS='{"x-trace-id":"work-session"}'
kollab --llm work
# Persist this env-defined profile to config
kollab --llm work --save
# Persist and set as startup default profile
kollab --llm work --default
# Persist to project-local config instead of global
kollab --llm work --save --local
# Set project-local default profile
kollab --llm work --default --local

Common profile fields: MODEL, PROVIDER, API_KEY, BASE_URL, MAX_TOKENS, TEMPERATURE, TIMEOUT (seconds), TOP_P, EFFORT, STREAMING, SUPPORTS_TOOLS, DESCRIPTION, EXTRA_HEADERS (JSON string).

Resolution order is: KOLLAB_{PROFILE}_{FIELD} -> KOLLAB_{FIELD} -> config -> defaults. KOLLAB_{PROFILE}_MODEL is required to create a profile from env vars.

Common Workflows

Use ChatGPT OAuth

kollab --login openai

Kollab opens a browser for authorization, stores the token in local user runtime state, and uses the Responses API with the subscription quota.

Run Pipe Mode

kollab "What is the capital of France?"
echo "Explain this code" | kollab -p
cat document.txt | kollab "summarize this" -p
git diff | kollab "write a concise commit message" -p --timeout 30s

Launch Agents

kollab --agent coder --as lapis
kollab --agent technical-writer --as sapphire --skill readme-writing

Agents can be bundled with the project, installed globally, or defined inside a workspace under .kollab/agents/. --agent selects the bundle; --as selects the hub identity. See docs/features/agents.md.

Coordinate Agents With The Hub

kollab --agent coder --as lapis
kollab --hub status
kollab --hub msg lapis "review the latest diff"
kollab --hub capture lapis 100
kollab --hub org engineering "ship the billing flow"
kollab --org engineering
kollab --hub stop lapis

Hub capabilities include identities, project-scoped memory, task ledger workflows, recurring hub messages, optional Telegram forwarding, organization launch files, and experimental DNS-style identity and trust commands. Start with docs/guides/hub-quick-start.md.

Manage Tools And MCP

/permissions
/mcp                 open the MCP manager
/mcp setup           open the MCP manager
/mcp show            show MCP server status
/mcp status          show MCP server status (compatibility alias)
/mcp list            show MCP server status (alias)
/mcp servers         show MCP server status (alias)
/mcp tools [server]  list available MCP tools
/mcp test <server>   test one server connection
/mcp enable <server> enable a server in config
/mcp disable <server> disable a server in config
/mcp reload          reload config and reconnect enabled servers; report failures
aliases: /mcps, /servers

Inside /mcp, press g to toggle the global MCP subsystem. Use Space to toggle the selected server, a/d to add or delete a configured server, t to test, r to reload, / to filter, and Esc to exit.

See docs/reference/commands.md for the complete slash-command reference and docs/features/mcp.md for configuration details.

MCP tools run through the same approval system as native tools. See docs/features/permissions.md and docs/features/mcp.md.

The built-in tool-search and tool-load tools let an agent discover a tool by keyword and load its full schema only when needed. Large tool results remain available as managed .output artifacts while the model receives a bounded preview; see tool-output artifacts.

Extend Kollab

Plugins can register hooks, slash commands, startup info, config widgets, and tool handlers:

from kollabor_plugins import BasePlugin

class MyPlugin(BasePlugin):
    async def register_hooks(self):
        self.event_bus.register_hook("pre_api_request", self.inject_context)

Plugin entry points live under plugins/, and the plugin SDK lives in packages/kollabor-plugins. See docs/plugins/overview.md, docs/plugins/development.md, and docs/plugins/hooks-reference.md.

Slash Commands

Type / in the app to see the full command menu. Plugins can add more commands.

Common CLI-only or plugin surfaces:

kollab --help
kollab --doctor                 # first-run readiness check
kollab --updates                # recent changes
kollab --sub list               # agent orchestrator sessions
kollab --attach lapis           # interactively attach to a live identity
kollab service install          # keep this folder's agent running at boot/login and after a crash
kollab --hub status             # hub inspection without a TUI
kollab --web-ui                 # local engine + browser UI

Repository Layout

Kollab is a Python monorepo. The root package provides the kollab command and the kollabor/ orchestration layer; reusable runtime pieces live in workspace packages.

Development

git clone https://github.com/kollaborai/kollab.git
cd kollab
uv sync --all-packages --extra dev
uv run python main.py

Focused validation used by the current CI baseline:

uv run python -m pytest \
  tests/unit/test_openai_streaming_finish_reason.py \
  tests/unit/test_turn_runner_tool_loop.py \
  tests/unit/test_hub_project_scope.py \
  tests/unit/test_provider_models.py \
  tests/unit/test_provider_security.py \
  tests/unit/test_gemini_provider.py
uv run python -m ruff check --select E9,F63,F7,F82 kollabor packages plugins tests
uv run python -m py_compile kollabor/cli.py kollabor_cli_main.py plugins/hub/plugin.py

For contribution guidance, see CONTRIBUTING.md. For agent and architecture guidance, see AGENTS.md, CLAUDE.md, and docs/architecture/README.md.

Documentation

• Getting Started
• Configuration
• Provider Profiles
• Models and Loadouts
• Reasoning Effort
• Setup Wizard
• Agent System
• Voice Mode
• Hub Quick Start
• Tasks and Checkpoints
• Tool Calling
• Attach Mode
• Agent Network Architecture
• Command Reference
• Engine and Web UI
• Tool-output Artifacts
• Documentation Index
• Telegram Bridge Setup
• MCP
• Permissions
• Plugin Development
• Troubleshooting
• Release Process

Support and Security

• Questions and bug reports: GitHub Issues
• Support expectations: SUPPORT.md
• Vulnerability reporting: SECURITY.md

Do not post API keys, OAuth tokens, private conversation logs, raw transcripts, or local runtime data in public issues.

License

Kollab is licensed under the MIT License.