Architecture Overview

System Overview

klaw is built as a modular, distributed system inspired by Kubernetes. Each component has a clear responsibility and communicates through well-defined interfaces.

┌─────────────────────────────────────────────────────────────┐
│                        USER INTERFACES                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │   CLI    │  │   TUI    │  │  Slack   │  │   API    │    │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘    │
└───────┼─────────────┼─────────────┼─────────────┼───────────┘
        │             │             │             │
        └─────────────┴──────┬──────┴─────────────┘
                             │
                    ┌────────▼────────┐
                    │    CHANNELS     │
                    │  (Abstraction)  │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  ORCHESTRATOR   │
                    │  (Routing)      │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │     AGENT       │
                    │ (LLM + Tools)   │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
       ┌──────▼──────┐ ┌─────▼─────┐ ┌──────▼──────┐
       │  PROVIDER   │ │   TOOLS   │ │   MEMORY    │
       │  (LLM API)  │ │ (Actions) │ │ (Context)   │
       └─────────────┘ └───────────┘ └─────────────┘

Core Components

Channels

Channels are the communication interfaces—how users interact with agents.

Channel	Use Case	Features
Terminal	CLI interaction	Styled output, streaming
TUI	Rich terminal	Bubble Tea, syntax highlight
Slack	Team collaboration	Thread support, Socket Mode
API	Programmatic	REST, streaming

Interface:

type Channel interface {
    Start(ctx context.Context) error
    Send(ctx context.Context, msg Message) error
    Receive(ctx context.Context) (Message, error)
    Stop() error
    Name() string
}

Orchestrator

Routes messages to appropriate agents based on content, rules, or AI decision. Routing Modes:

Disabled: Single agent, no routing
Rules: Regex pattern matching
AI: LLM-based routing decisions
Hybrid: Rules first, AI fallback

Message → Rules Check → AI Router → Agent Selection → Dispatch

Agent

The core execution unit. Coordinates:

Conversation history management
LLM communication
Tool execution loop
Memory integration

Agent Loop:

┌─────────────────────────────────────────────────────────────┐
│                      AGENT LOOP                              │
│                                                              │
│  ┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐      │
│  │Receive │ → │  LLM   │ → │ Tools  │ → │ Result │ ─┐    │
│  │ Input  │    │Decision│    │Execute │    │Process │  │    │
│  └────────┘    └────────┘    └────────┘    └────────┘  │    │
│       ▲                                                 │    │
│       └─────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Provider

LLM abstraction layer supporting multiple backends.

Provider	Models	Features
Anthropic	Claude family	Native streaming
OpenRouter	100+ models	Gateway
each::labs	300+ models	Unified API

Interface:

type Provider interface {
    Chat(ctx context.Context, messages []Message) (string, error)
    Stream(ctx context.Context, messages []Message) (<-chan StreamEvent, error)
    Name() string
    Models() []string
}

Tools

Actions agents can perform. Built-in tools cover common operations.

Category	Tools
Execution	bash
File ops	read, write, edit, glob, grep
Web	web_fetch, web_search
Meta	agent_spawn, skill, cron

Memory

Persistent context system with workspace files.

~/.klaw/workspace/
├── SOUL.md      # Identity
├── AGENTS.md    # Registry
├── TOOLS.md     # Documentation
├── USER.md      # Preferences
└── MEMORY.md    # Learned patterns

Scheduler

Cron-based task scheduling for automated workflows.

type Job struct {
    Name     string
    Schedule string  // Cron expression
    Agent    string
    Task     string
    Enabled  bool
}

Deployment Modes

Single-Node

Everything runs on one machine:

┌─────────────────────────────────────────┐
│              SINGLE NODE                 │
│  ┌─────────────────────────────────┐    │
│  │  Channels → Orchestrator → Agents │    │
│  │  Scheduler → Tools → Memory       │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘

Commands: klaw chat, klaw start

Distributed

Controller manages multiple worker nodes:

┌─────────────────────────────────────────┐
│              CONTROLLER                  │
│  Agent Registry │ Task Dispatcher       │
│  State Manager  │ Node Manager          │
└─────────────────┬───────────────────────┘
                  │ TCP/JSON
    ┌─────────────┼─────────────┐
    ▼             ▼             ▼
┌─────────┐  ┌─────────┐  ┌─────────┐
│ NODE 1  │  │ NODE 2  │  │ NODE 3  │
│ Agents  │  │ Agents  │  │ Agents  │
└─────────┘  └─────────┘  └─────────┘

Commands: klaw controller start, klaw node join

Container

Agents run in isolated Podman containers:

┌─────────────────────────────────────────┐
│              HOST SYSTEM                 │
│  ┌─────────────┐  ┌─────────────┐       │
│  │  Container  │  │  Container  │       │
│  │  Agent A    │  │  Agent B    │       │
│  └─────────────┘  └─────────────┘       │
└─────────────────────────────────────────┘

Commands: klaw build, klaw run, klaw ps

Data Flow

Chat Flow

User types message in CLI
Terminal channel receives message
Message sent to agent
Agent adds to conversation history
Agent calls provider.Stream()
Provider sends to LLM API
LLM returns tool calls or text
If tool calls: execute tools, add results, goto 5
If text: stream to channel
Channel displays to user

Slack Flow

User @mentions bot in Slack
Slack channel receives via Socket Mode
Orchestrator routes to appropriate agent
Agent processes with tools
Response sent back to Slack thread

Task Dispatch Flow

CLI sends dispatch request
Controller finds agent on available node
Task sent to node via TCP
Node executes agent with task
Results streamed back to controller
Controller streams to CLI

State Management

Local State

Config: ~/.klaw/config.toml
Agents: ~/.klaw/agents/*.toml
Skills: ~/.klaw/skills/
Sessions: ~/.klaw/sessions/

Distributed State

Controller maintains:

Node registry (connected nodes)
Agent registry (available agents per node)
Task queue (pending/running/completed)

Optional etcd backend for HA:

klaw controller start --etcd-endpoints etcd1:2379

Extension Points

Extension	Mechanism
New channels	Implement Channel interface
New providers	Implement Provider interface
New tools	Implement Tool interface
New skills	TOML definition + optional Go code

Getting Started

Core Concepts

Guides

Configuration

Architecture

CLI Reference

Resources

Architecture Overview

System Overview

Core Components

Channels

Orchestrator

Agent

Provider

Tools

Memory

Scheduler

Deployment Modes

Single-Node

Distributed

Container

Data Flow

Chat Flow

Slack Flow

Task Dispatch Flow

State Management

Local State

Distributed State

Extension Points

Next Steps

Agent Loop

Distributed Mode

​System Overview

​Core Components

​Channels

​Orchestrator

​Agent

​Provider

​Tools

​Memory

​Scheduler

​Deployment Modes

​Single-Node

​Distributed

​Container

​Data Flow

​Chat Flow

​Slack Flow

​Task Dispatch Flow

​State Management

​Local State

​Distributed State

​Extension Points

​Next Steps

Agent Loop

Distributed Mode

System Overview

Core Components

Channels

Orchestrator

Agent

Provider

Tools

Memory

Scheduler

Deployment Modes

Single-Node

Distributed

Container

Data Flow

Chat Flow

Slack Flow

Task Dispatch Flow

State Management

Local State

Distributed State

Extension Points

Next Steps