Kollaborate Multi-Agent Framework

Kollaborate orchestrates multiple AI agents working in parallel on complex software projects. It's a general-purpose LLM CLI management framework designed for massive parallelization and autonomous operations.

Overview

The Kollaborate framework provides:

Massive Parallelization - run multiple agents simultaneously for exponential speedup
Autonomous Operations - agents work independently without constant human supervision
Multi-LLM Support - switch between Claude, Gemini, Crush, Codex, and more
Quality Assurance - built-in validation and review processes

Installation

Remote Installation (Recommended)

curl -fsSL https://raw.githubusercontent.com/maarco/kollaborate/main/install.sh | zsh
source ~/.zshrc

Automatically installs to ~/.kollaborate with global CLI access

Local Installation

git clone https://github.com/maarco/kollaborate.git
cd kollaborate
./install.sh
source ~/.zshrc

Clone repository first, then run installer

Quick start in your project:

# Initialize kollaborate in your project
cd your-project
kollaborate init

# Start with 3 task agents and 2 spec agents
kollaborate start 3 2

Task Tracking Format

Kollaborate uses a standardized TASK_TRACKING.md file to manage task states:

# Your Project Development Log

## Current Goal
Build a modern web application with React frontend and Node.js backend

## Build & Development Commands
```bash
npm run dev
npm run test
npm run build
```

## Development Log
NEW: F1 - Setup project structure and package.json files (file: package.json)
NEW: R2 - Create Express.js backend with basic routing (file: src/backend/app.js)
WORKING: T3 - Add integration tests (file: tests/api.test.js)
DONE: B4 - Fix memory leak in connection pool (file: src/pool.js)
QA: D5 - Document API endpoints (file: docs/api.md)

State	Description
`NEW:`	Pending tasks waiting for agent assignment
`WORKING:`	Active development by assigned agent
`DONE:`	Completed tasks ready for review
`QA:`	Awaiting quality assurance review
`BLOCKED:`	Tasks blocked by dependencies or issues

17 Task Types

Kollaborate uses typed task prefixes to apply specialized prompts and templates:

F## - Feature

New functionality implementation and additions

R## - Refactor

Code quality improvements and restructuring

B## - Bug Fix

Fixes and corrections for existing code

T## - Test

Test coverage and test improvements

D## - Documentation

Documentation, API docs, and comments

P## - Performance

Performance optimization and profiling

A## - Architecture

Architecture, design patterns, and setup

S## - Security

Security hardening and vulnerability fixes

H## - Hotfix

URGENT production fixes only

M## - Migration

Database migrations and data transformations

I## - Integration

Third-party service integrations

C## - Chore

Dependency updates and maintenance tasks

E## - Experiment

POC/spike work and research experiments

U## - UX

User experience and accessibility improvements

V## - Validation

Input validation and schema enforcement

W## - Workflow

CI/CD and automation pipelines

X## - Exploration

Research, analysis, and investigation

Add tasks with specific types to apply optimized prompts and specifications:

kollaborate add feature "User authentication" src/auth.js
kollaborate add test "API integration tests" tests/api.test.js
kollaborate add bug "Fix memory leak" src/pool.js

Agent Lifecycle

Kollaborate manages agents through a complete lifecycle from spawn to cleanup:

Spawn

NEW tasks trigger specification agent creation. Spec agents generate detailed requirements (minimum 50 lines) before task agents spawn.

Monitor

Activity monitoring tracks agent progress via output hashing every 60 seconds. Agents must show progress or receive warnings.

Idle Detection

3-strike warning system: agents showing no output changes receive warnings. After 3 warnings, agent is recycled and task returns to NEW state.

Recycle

When tasks complete or agents go idle, cleanup occurs automatically. Agent sessions terminate and resources are freed for new tasks.

Task state machine:

NEW -> WORKING -> DONE/QA
 |         |
 v         v
BLOCKED <- (recycled if agent goes idle)

Specification Generation

Before task agents spawn, specification agents create detailed requirements documents:

Minimum 50 lines - placeholder specs are rejected and regenerated
Type-specific templates - each task type has optimized spec format
5-minute timeout - spec agents have 300 seconds to complete
Stored in docs/specs/ - organized by task ID (F01-task-name.md)

Example specification structure:

# Specification for F123: User Authentication

## Overview
Clear, concise description of what needs to be built

## Requirements
- Functional requirement 1
- Functional requirement 2
- Technical requirement 1
- Performance requirement 1

## Architecture
How this integrates with existing codebase
Key design decisions and rationale

## Implementation Plan
1. Step 1 with file paths and code examples
2. Step 2 with file paths and code examples
3. Additional steps as needed

## File Structure
Explicit file structure showing new and modified files

## Integration Points
How this connects to existing components
API endpoints, database changes, UI integration

## Testing Requirements
Unit tests needed
Integration tests needed
Manual QA steps

## Acceptance Criteria
- [ ] Specific, measurable criteria
- [ ] Performance benchmarks
- [ ] Code quality standards

Daemon Configuration

Configure the agent watcher daemon by editing kollaborate.sh or passing arguments:

Setting	Default	Description
`MAX_AGENTS`	3	Maximum concurrent task agents
`MAX_SPEC_AGENTS`	2	Maximum specification agents
`CHECK_INTERVAL`	60s	Monitoring cycle frequency
`NEW_TASK_REQUIRED`	5	Minimum task queue size
`SPEC_TIMEOUT`	300s	Spec generation timeout
`SPEC_MIN_LINES`	50	Minimum spec line count

Start daemon with custom settings:

# Start with 5 task agents and 3 spec agents
kollaborate start 5 3

# Default settings (3 task agents, 2 spec agents)
kollaborate start

TMUX Agent Commands

Kollaborate uses TMUX-based orchestration with kmux.sh wrapper commands:

kglm agentName "task"

Launch new agent with specific task prompt in TMUX session

klist

List all active agent TMUX sessions

kcapture agentName [lines]

View agent output from TMUX session (optional line limit)

kmsg agentName "message"

Send message to specific agent session

kstop agentName

Stop specific agent and terminate TMUX session

Example usage:

# List all running agents
klist

# View output from agent TASK-F12
kcapture TASK-F12 50

# Send message to agent
kmsg TASK-F12 "Please add error handling"

# Stop agent
kstop TASK-F12

Multi-LLM Backend Support

Kollaborate supports multiple LLM CLI tools through the unified glm wrapper:

Backend	CLI	Auto-Accept Flag
Claude	`claude`	`--dangerously-skip-permissions`
Gemini	`gemini`	`--yolo`
Crush	`crush`	`--yolo`
Codex	`codex`	`--sandbox danger-full-access`
OpenCode	`opencode`	(none)
Cursor	`cursor`	(generic)

Switch backends anytime:

# Show current backend
kollaborate use

# Switch to Gemini
kollaborate use gemini

# Switch to Claude
kollaborate use claude

# Use current backend
glm "your prompt"

Agent Quality Constraints

Kollaborate enforces strict quality standards for agent work:

60-Second Rule

Agents must begin work within 60 seconds of spawning. No delays, no planning - immediate execution required.

No Stubs or TODOs

Full implementations only. No placeholder code, empty method bodies, dummy returns, or TODO comments allowed.

Zero Errors

Build/check must pass before completion. All linting, type checking, and compilation errors must be resolved.

Parameter Usage

All function parameters must be meaningfully used. No underscore prefixes to silence warnings.

No AI Attribution

Clean commit messages without AI credits or "Co-Authored-By" footers.

These constraints ensure production-ready code from every agent task.