ccswarm Architecture Documentation

System Architecture Overview

ccswarm follows a microkernel architecture with pluggable providers and a central orchestration layer.

Workspace Structure

ccswarm uses a Cargo workspace to organize the codebase into multiple crates:

ccswarm/
├── Cargo.toml                    # Workspace root configuration
├── crates/
│   ├── ccswarm/                  # Main ccswarm application
│   │   ├── Cargo.toml
│   │   └── src/                  # Core ccswarm modules
│   └── ai-session/               # Native AI session management
│       ├── Cargo.toml
│       └── src/                  # Session management implementation

The workspace configuration enables:

Shared dependencies across crates
Parallel development of ccswarm and ai-session
Cleaner separation of concerns
Easier testing and benchmarking

┌─────────────────────────────────────────────────────────────┐
│                    Master Claude (Orchestrator)              │
│  - Task analysis and delegation                              │
│  - Quality review coordination                               │
│  - Sangha consensus management                               │
└─────────────────────┬───────────────────────────────────────┘
                      │
        ┌─────────────┴─────────────┬─────────────┬────────────┬────────────┐
        │                           │             │            │            │
┌───────▼────────┐  ┌──────────────▼──┐  ┌──────▼─────┐  ┌───▼────┐  ┌────▼────┐
│Frontend Agent  │  │Backend Agent    │  │DevOps Agent│  │QA Agent│  │Search   │
│- React/Vue     │  │- APIs/Database  │  │- Docker    │  │- Tests │  │Agent    │
│- UI/UX         │  │- Business Logic │  │- CI/CD     │  │- QA    │  │- Gemini │
└────────────────┘  └─────────────────┘  └────────────┘  └────────┘  └─────────┘
        │                           │             │            │            │
        └─────────────┬─────────────┴─────────────┴────────────┴────────────┘
                      │
┌─────────────────────▼───────────────────────────────────────┐
│                    AI-Session Management Layer               │
│  - True parallel execution via MultiAgentExecutor            │
│  - Message bus for inter-agent communication                 │
│  - Resource manager for file locking                         │
│  - Session persistence and recovery                          │
│  See: crates/ai-session/README.md                           │
└─────────────────────────────────────────────────────────────┘

Core Components

1. Orchestrator (`crates/ccswarm/src/orchestrator/`)

The brain of the system that coordinates all agent activities.

Master Claude (`master_claude.rs`)

Analyzes incoming tasks
Determines optimal agent assignment
Monitors task progress
Handles cross-agent dependencies

Quality Judge (`llm_quality_judge.rs`)

Evaluates code on 8 dimensions
Generates remediation tasks for failures
Runs every 30 seconds on completed tasks
Confidence scoring 0.0-1.0

2. Agent System (`crates/ccswarm/src/agent/`)

Specialized AI agents with strict role boundaries.

Agent Types

Simple Agent: Basic task execution
Persistent Agent: Maintains context across tasks
Pool Agent: Load-balanced agent groups
Search Agent: Web search and information gathering

Specialized Agents

Frontend Agent: React, Vue, UI/UX development
Backend Agent: APIs, databases, server logic
DevOps Agent: Docker, CI/CD, infrastructure
QA Agent: Testing, quality assurance
Search Agent: Web search via Gemini CLI, research, Sangha participation

Identity System (`crates/ccswarm/src/identity/`)

Enforces strict role boundaries
Prevents scope creep
Monitors agent responses for violations

3. AI-Session Integration (`crates/ccswarm/src/session/`)

Revolutionary session management powered by the ai-session crate, replacing tmux entirely.

AI-Session Adapter (`ai_session_adapter.rs`)

Bridge Layer: Connects ccswarm orchestrator with ai-session crate (located in crates/ai-session/)
Session Lifecycle: Creates, manages, and terminates ai-session instances for each agent
Context Management: Token-efficient conversation history management
Cross-Platform PTY: Uses ai-session's native PTY implementation
Message Bus Integration: Coordinates multi-agent communication via ai-session's coordination layer

AI-Session Features Used by ccswarm

Token-Efficient Context: Context window management with FIFO eviction
Semantic Output Parsing: Intelligent analysis of build results, test outputs, and error messages
Multi-Agent Coordination: Message bus architecture for agent-to-agent communication
Session Persistence: Automatic crash recovery and state restoration
MCP Protocol Support: HTTP API server for external tool integration
Performance Monitoring: Real-time metrics and token usage tracking

3.1 Parallel Execution (`crates/ccswarm/src/subagent/parallel_executor.rs`)

True multi-agent parallel execution using ai-session's coordination layer.

MultiAgentExecutor

// Create executor with ai-session integration
let executor = MultiAgentExecutor::new(ParallelConfig::default());

// Execute tasks in parallel with message bus access
executor.execute_parallel(tasks, |task, message_bus, resource_manager| async move {
    // Agents can communicate through message_bus
    // Resource conflicts handled by resource_manager
    execute_task(task).await
}).await?;

Key Features

True Parallel Execution: Multiple Claude CLI sessions run concurrently
Message Bus Communication: Agents can communicate during execution
Resource Locking: File locking prevents conflicts on shared resources
Semaphore-Based Concurrency: Configurable max concurrent executions
Result Aggregation: Collect, merge, or select from parallel results

Session Types in ccswarm

Agent Session: Specialized ai-session instance per agent (frontend, backend, devops, qa)
Worktree Session: Git worktree integration with ai-session persistence
Persistent Session: Long-running contexts with ai-session state management
Pool Session: Load-balanced ai-session instances for high-throughput scenarios

Integration Architecture

// ccswarm creates specialized ai-session configurations
let session_config = SessionConfig {
    enable_ai_features: true,
    agent_role: AgentRole::Frontend,
    context_config: ContextConfig {
        max_tokens: 4096,
        compression_threshold: 0.8,
    },
    coordination_config: CoordinationConfig {
        enable_message_bus: true,
        agent_id: "frontend-specialist".to_string(),
    },
};

// ai-session handles the low-level terminal management
let ai_session = ai_session::SessionManager::new()
    .create_session_with_config(session_config).await?;

4. Coordination Layer (`crates/ccswarm/src/coordination/`)

Inter-agent communication and task management.

Components

Task Queue: Async task distribution
Message Bus: Agent communication
Dialogue System: Structured conversations

5. Extension Framework (`crates/ccswarm/src/extension/`)

Self-improvement and capability expansion.

Autonomous Extension (`autonomous_agent_extension.rs`)

Analyzes agent experiences
Identifies capability gaps
Proposes improvements via Sangha

Search Integration (`agent_extension.rs`)

GitHub API for code patterns
MDN for web standards
Stack Overflow for solutions

6. Sangha System (`crates/ccswarm/src/sangha/`)

Democratic decision-making inspired by Buddhist principles.

Consensus Algorithms

Simple Majority: 51% approval
Byzantine Fault Tolerant: 67% approval
Proof of Stake: Weighted by contribution

Data Flow

Task Execution Flow

User Input → CLI Parser → Task Queue → Master Claude Analysis
    ↓
Agent Assignment → Session Creation → Task Execution
    ↓
Output Streaming → Quality Review → Task Completion
    ↓
Session Persistence → Knowledge Base Update

Extension Proposal Flow

Agent Experience Analysis → Capability Assessment
    ↓
Need Identification → Proposal Generation
    ↓
Sangha Submission → Democratic Voting
    ↓
Consensus Achievement → Implementation

Search Agent Message Flow

Agent/Master Claude → Search Request → Coordination Bus
    ↓
Search Agent Receives → Query Validation → Filter Application
    ↓
Gemini CLI Execution → Result Parsing → Relevance Scoring
    ↓
Response Generation → Coordination Bus → Requesting Agent

Search Agent Sangha Participation

Proposal Detection → Key Term Extraction → Query Generation
    ↓
Web Search Execution → Result Analysis → Evidence Generation
    ↓
Opinion Formation → Vote Calculation → Informed Voting
    ↓
Knowledge Gap Detection → Initiative Proposal → Sangha Submission

Module Dependencies

Core Dependencies

tokio: Async runtime
serde: Serialization
portable-pty: Cross-platform PTY
ai-session: Advanced AI-optimized session management (workspace crate at crates/ai-session/)
- Provides 93% token reduction through intelligent context compression
- Native cross-platform PTY implementation
- Multi-agent coordination and message bus architecture
- Can be used independently as a standalone library or CLI tool

Provider Dependencies

claude_code: Anthropic integration
aider: Aider tool integration
codex: OpenAI integration
custom: Custom tool support

Workspace Dependencies and Integration

The workspace structure enables tight integration between ccswarm and ai-session:

# In crates/ccswarm/Cargo.toml
[dependencies]
ai-session = { path = "../ai-session" }

# ai-session can also be used independently:
# ai-session = "0.1"  # When published to crates.io

Integration Benefits

Shared Development: Both crates evolve together in the same repository
Consistent APIs: Breaking changes are coordinated across both crates
Performance Optimization: Direct memory sharing without serialization overhead
Unified Documentation: Single source of truth for the entire system
Simplified Testing: Integration tests can test both crates together

Dependency Flow

ccswarm (orchestration)
    ↓ depends on
ai-session (terminal management)
    ↓ depends on
portable-pty, tokio, serde, etc.

Standalone Usage

Developers can use ai-session independently without ccswarm:

# Install just ai-session
cargo install --path crates/ai-session

# Use for any AI terminal workflow
ai-session create --name myproject --ai-context
ai-session exec myproject "python train.py" --capture

Security Architecture

Agent Isolation

Git worktree isolation per agent
No cross-agent file access
Sandboxed execution environment

Risk Assessment

Auto-accept patterns with risk scoring
Protected file patterns
Emergency stop capability

Security Agent Integration

OWASP vulnerability scanning
Real-time security monitoring
Automated remediation

Performance Optimizations

Session Reuse

93% token reduction through context caching
Intelligent session pooling
Automatic garbage collection

Memory Management

Context compression with zstd
Sliding window for history
Lazy loading of agent contexts

Concurrency

Async/await throughout
Lock-free data structures where possible
Work-stealing task scheduler

Testing Strategy

Unit Tests

267 core tests
Module-level isolation
Mocked dependencies

Integration Tests

End-to-end workflows
Multi-agent scenarios
Session persistence verification

Ignored Tests

Tests that may fail in CI due to timing or environment:

Concurrent agent operations
Message persistence timing
Complex integration workflows

Extension Points

Adding New Providers

Implement Provider trait in crates/ccswarm/src/providers/
Add to ProviderType enum
Update configuration schema
Add integration tests in crates/ccswarm/tests/

Adding New Agent Roles

Define role in AgentRole enum in crates/ccswarm/src/agent/
Create identity constraints in crates/ccswarm/src/identity/
Add CLAUDE.md template in crates/ccswarm/templates/
Update delegation logic in crates/ccswarm/src/orchestrator/

Custom Extensions

Implement extension trait in crates/ccswarm/src/extension/
Register with Sangha in crates/ccswarm/src/sangha/
Define consensus requirements
Add migration logic

AI-Session Crate Structure and Integration

The ai-session crate (crates/ai-session/) provides the foundational terminal management capabilities:

Core Modules Used by ccswarm

Core Session Management (crates/ai-session/src/core/)
- Native PTY implementation with cross-platform support
- Session lifecycle management and resource cleanup
- Process management and terminal emulation
Context Management (crates/ai-session/src/context/)
- Token-efficient conversation history (93% savings)
- Intelligent compression using zstd algorithm
- AI-optimized context preservation and retrieval
Multi-Agent Coordination (crates/ai-session/src/coordination/)
- Message bus architecture for agent communication
- Task distribution and result aggregation
- Cross-agent knowledge sharing
Output Processing (crates/ai-session/src/output/)
- Semantic parsing of command outputs
- Structured analysis of build results, tests, and logs
- Pattern recognition for error detection
Session Persistence (crates/ai-session/src/persistence/)
- Automatic state snapshots and recovery
- Compressed storage of session history
- Cross-platform file system integration
MCP Protocol Server (crates/ai-session/src/mcp/)
- HTTP API server for external integrations
- JSON-RPC 2.0 implementation
- Tool discovery and capability registration

Standalone vs Integrated Usage

Standalone ai-session usage:

// Independent of ccswarm
use ai_session::{SessionManager, SessionConfig};

let manager = SessionManager::new();
let session = manager.create_session_with_ai_features().await?;

ccswarm integration:

// ccswarm wraps ai-session with orchestration logic
use crate::session::ai_session_adapter::AISessionAdapter;

let adapter = AISessionAdapter::new(agent_config);
let session = adapter.create_specialized_session().await?;

Documentation

AI-Session README - Overview and API reference

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History