Core Components

Architecture Deep Dive

Jetpack is an 8-package monorepo with a durable DataLayer, decentralized SwarmCoordinator, and model-agnostic agent execution. All coordination state persists to the database, making the swarm crash-resilient.

System Overview

┌─────────────────────────────────────────────────────────────┐
│                    SWARM COORDINATOR                         │
│       Agent lifecycle · Work distribution · Health checks    │
│   Claim strategies: first-fit | best-fit | round-robin      │
│                  load-balanced | graph-prioritized           │
└───────┬─────────────────┬─────────────────┬─────────────────┘
        │                 │                 │
┌───────▼───────┐ ┌───────▼───────┐ ┌───────▼───────┐
│  TASK QUEUE   │ │  AGENT MAIL   │ │   MEMORIES    │
│  + TaskGraph  │ │  Reservations │ │ Vector Search │
│  Hierarchical │ │  + Threading  │ │  memoryType   │
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
        │                 │                 │
┌───────▼─────────────────▼─────────────────▼───────┐
│                    DATA LAYER                      │
│         Turso (cloud) / SQLite (local)             │
│   Embedded replicas · Offline sync · Vectors       │
└───────────────────────┬───────────────────────────┘
                        │
            ┌───────────▼───────────┐
            │     AGENT HARNESS     │
            │  (1-N model-agnostic  │
            │    worker agents)     │
            └───────────────────────┘

Core Components

DataLayer (Turso/SQLite)

The single source of truth. Defines all persistent operations — tasks, agents, messages, reservations, memories, plans. TursoDataLayer for cloud, TursoNativeDataLayer adds vector search and embedded replicas.

Storage: Turso cloud / .jetpack/jetpack.db

Task Queue + TaskGraph

Hierarchical task queue with dependency tracking. Only leaf tasks (no children) are claimable. TaskGraph provides critical path, fan-out (dependent count), and depth analysis for prioritization.

Storage: DataLayer tasks table

Agent Mail

Advisory file reservations, message threading, and intent broadcasting. Multiple agents can reserve the same file — conflicts surface as data, not errors. Pre-commit Git hook for optional enforcement.

Storage: DataLayer messages + file_reservations tables

Memory System

Vector-backed memories table with arbitrary memoryType strings. Common types: agent_learning, solution_pattern, codebase_knowledge. Vector search for semantic retrieval.

Storage: DataLayer memories table

SwarmCoordinator + AgentHarness

SwarmCoordinator manages agent lifecycle, work distribution, and health monitoring. AgentHarness is a model-agnostic execution wrapper — supports Claude Code, Codex, Gemini, browser agents, or custom models. 5 claim strategies (default: best-fit). Both advisory file reservations and hard leases for coordination.

Storage: In-memory with heartbeat signals (30s)

Package Structure

jetpack/
├── packages/
│   ├── data/              # DataLayer interface + Turso/SQLite implementations
│   ├── coordinator/       # SwarmCoordinator — lifecycle, distribution, strategies
│   ├── agent-harness/     # Model-agnostic agent execution wrapper
│   ├── plan-loader/       # Markdown/JSON plan parsing → hierarchical tasks
│   ├── swarm-cli/         # CLI entry point (jetpack start, agent, load, etc.)
│   ├── quality/           # Quality metrics + regression detection
│   ├── dashboard/         # Dashboard data provider API
│   └── jetpack-cli/       # Distributed CLI wrapper
├── apps/
│   └── web/               # Next.js 15 web dashboard (REST API)
└── .jetpack/              # Local config + jetpack.db
    .tasks/                # Task graph + execution log
    .memories/             # Memory database (vector-enabled)
    .turso/                # Embedded replica + sync metadata

Data Flow

Task Lifecycle

Plan (markdown/JSON) → PlanLoader → DataLayer (create tasks)
              ↓
  SwarmCoordinator (claim strategy selects task)
              ↓
  AgentHarness (claim task atomically)
              ↓
  Memory System (retrieve relevant memories for context)
              ↓
  Agent Mail (broadcast intent: files I'll touch)
              ↓
  Execute via model (Claude Code / Codex / custom)
              ↓
  DataLayer (update task status) + Memory System (store learnings)
              ↓
  Agent Mail (broadcast completion + release reservations)

Multi-Agent Coordination

Agent A: Intent broadcast → Reserve files (advisory)
Agent B: See reservation → Check conflicts → Coordinate
Agent C: Heartbeat (30s) → Stale detection → Auto-recovery
All: Learn from memories via vector search