Skip to content
This repository was archived by the owner on May 24, 2026. It is now read-only.

reecepm/orca

BranchesTags

Repository files navigation

Orca

Distributed task orchestration for AI agents. Local-first. Remote-ready. Client-agnostic.

Orca is a flexible task management system designed for AI coding agents. Run it locally with zero setup, sync across machines when needed, or deploy a hosted server for your team—all without changing your workflow.

Archive note: Orca was originally built primarily during January-February 2026, with follow-up maintenance in March 2026, and prepared as a public archive in May 2026.

Why Orca?

AI coding tools are evolving rapidly. Today's favorite CLI might be tomorrow's legacy software. Orca decouples task orchestration from the tools that consume it:

  • Any client works: Claude Code, OpenCode, Codex CLI, custom UIs, or your own agent
  • Any deployment works: Embedded in-process, remote server, or hybrid with sync
  • Any storage works: SQLite for local, PostgreSQL for teams, or build your own adapter

One task queue. Many consumers. Zero lock-in.

Architecture Overview

flowchart TB
    subgraph Clients["Any Client"]
        CC[Claude Code]
        OC[OpenCode]
        CX[Codex CLI]
        UI[Custom UI]
        AG[Your Agent]
    end

    subgraph Orca["Orca Core"]
        CLI[orca CLI]
        SDK[Go SDK]
        GRPC[gRPC API]
    end

    subgraph Modes["Deployment Mode"]
        EMB[Embedded<br/>In-Process]
        REM[Remote<br/>gRPC Server]
        HYB[Hybrid<br/>Local + Sync]
    end

    subgraph Storage["Pluggable Storage"]
        MEM[(Memory)]
        SQL[(SQLite)]
        PG[(PostgreSQL)]
        CUSTOM[(Your Backend)]
    end

    Clients --> Orca
    CLI --> Modes
    SDK --> Modes
    GRPC --> Modes
    Modes --> Storage
Loading

Deployment Modes

Orca adapts to your environment. Choose the mode that fits, switch when your needs change.

Embedded Mode

Everything runs in-process. No server, no network, no configuration.

flowchart LR
    subgraph Process["Single Process"]
        Client[Client] --> Server[Embedded Server]
        Server --> DB[(SQLite)]
    end
Loading 
# Just works. Data at ~/.orca/data/orca.db
orca task add "Implement feature X"
orca task claim

Best for: Local development, single-machine workflows, getting started.

Remote Mode

Connect to a standalone Orca server. Multiple machines, shared task queue.

flowchart LR
    subgraph Machine1["Machine A"]
        C1[Agent 1]
    end
    subgraph Machine2["Machine B"]
        C2[Agent 2]
    end
    subgraph Machine3["Machine C"]
        C3[Agent 3]
    end

    subgraph Server["Orca Server"]
        SRV[gRPC Server]
        SRV --> DB[(PostgreSQL)]
    end

    C1 -->|gRPC| SRV
    C2 -->|gRPC| SRV
    C3 -->|gRPC| SRV
Loading 
# ~/.orca/config.yaml
client:
  mode: remote
  server_address: orca.yourcompany.com:50051

Best for: Teams, CI/CD pipelines, multi-machine agent coordination.

Hybrid Mode

Local-first operation with background sync. Work offline, sync when connected.

flowchart TB
    subgraph Local["Your Machine"]
        Client[Client]
        Daemon[Orca Daemon]
        LocalDB[(Local SQLite)]

        Client --> Daemon
        Daemon --> LocalDB
    end

    subgraph Remote["Remote Server"]
        Server[Orca Server]
        RemoteDB[(PostgreSQL)]
        Server --> RemoteDB
    end

    Daemon <-->|Write-Through + Change Stream| Server
Loading 
client:
  mode: hybrid
  server_address: orca.yourcompany.com:50051
  sync_interval: 30s

Best for: Distributed agents, offline-capable workflows, edge computing.

How Sync Works

Hybrid mode uses a server-authoritative write-through architecture with change streaming. The server is the single source of truth — there is no merge logic or conflict resolution layer.

sequenceDiagram
    participant Client as Local Client
    participant Queue as Write Queue
    participant Server as Remote Server

    Note over Client,Server: Online Path
    Client->>Server: Write-through (gRPC)
    Server->>Client: Change stream update

    Note over Client,Server: Offline Path
    Client->>Queue: Enqueue write
    Queue->>Client: Optimistic local update
    Note over Queue,Server: On Reconnect
    Queue->>Server: Drain queued writes (FIFO)
    Server->>Client: Bootstrap + live change stream
Loading

Offline Writes

When disconnected, writes are queued locally in a persistent write queue (SQLite-backed). On reconnection, queued writes drain to the server in order. The server may reject writes that conflict with changes made by other agents while offline (e.g., a task already claimed by someone else).

Change Stream

The server pushes all entity changes to connected clients via a gRPC server-streaming endpoint. Clients maintain a local cache populated entirely by the change stream, ensuring all clients converge to the same state.

Client Agnosticism

Orca doesn't care what consumes tasks. The same interface works everywhere.

MCP Integration (Claude Code, etc.)

flowchart LR
    subgraph "AI Coding Tool"
        CC[Claude Code]
        MCP[MCP Server]
    end

    subgraph "Orca"
        SDK[Orca SDK]
        Core[Core]
    end

    CC --> MCP --> SDK --> Core
Loading

Any MCP-compatible tool can use Orca through the same interface.

Direct SDK Usage

c, err := client.NewClientAndStart(ctx, client.ClientConfig{
    Mode: client.ModeEmbedded,
})
if err != nil {
    log.Fatal(err)
}
defer c.Close()

// Create a task
task := &types.Task{
    Title:       "Implement authentication",
    Description: "Add JWT-based auth to the API",
    ProjectID:   projectID,
}
if err := c.CreateTask(ctx, task, ""); err != nil {
    log.Fatal(err)
}

// Claim and work
result, _ := c.ClaimTask(ctx, task.ID, agentID, client.ClaimOptions{})
// ... do work ...
c.CompleteTask(ctx, result.Task.ID, agentID, &types.Result{
    Output: "Implemented JWT auth",
})

CLI for Humans and Scripts

# Add tasks
orca task add "Fix login bug" --project myapp --priority 10

# Agents claim work
TASK=$(orca task claim --agent worker-1 --json | jq -r '.task.id')

# Complete when done
orca task complete $TASK --agent worker-1

Custom Interfaces

Build your own dashboard, Slack bot, or VS Code extension. The gRPC API exposes everything.

Pluggable Storage

Storage backends implement a contract. Swap them via configuration.

flowchart TB
    Server[Orca Server]

    subgraph Adapters["Storage Adapters"]
        MEM[Memory Adapter]
        SQL[SQLite Adapter]
        PG[PostgreSQL Adapter]
        YOUR[Your Adapter]
    end

    subgraph Contract["Storage Contract"]
        TS[TaskStore]
        WS[WorkspaceStore]
        PS[ProjectStore]
        LS[LeaseStore]
    end

    Server --> MEM & SQL & PG & YOUR
    MEM & SQL & PG & YOUR --> Contract
Loading

Configuration

# SQLite (default, local)
storage:
  type: sqlite
  sqlite_path: ~/.orca/data/orca.db

# PostgreSQL (teams, production)
storage:
  type: postgres
  postgres_url: postgres://user:pass@host:5432/orca

Adding a New Backend

Implement the StorageAdapter interface:

type StorageAdapter interface {
    TaskStore() TaskStore
    WorkspaceStore() WorkspaceStore
    ProjectStore() ProjectStore
    LeaseStore() LeaseStore
    // ... other stores
}

Run the contract tests to verify correctness. All backends must pass the same test suite.

Core Concepts

Entity Hierarchy

flowchart TB
    W[Workspace] --> P1[Project A]
    W --> P2[Project B]

    P1 --> T1[Task 1]
    P1 --> T2[Task 2]

    T1 --> A1[Attempt 1<br/>failed]
    T1 --> A2[Attempt 2<br/>completed]
Loading
  • Workspace: Top-level container (team, organization)
  • Project: A codebase or logical grouping of work
  • Task: A unit of work with status, dependencies, and metadata
  • Attempt: A record of an agent working on a task

Task Lifecycle

stateDiagram-v2
    [*] --> draft: create (draft)
    draft --> pending: publish
    [*] --> pending: create
    pending --> ready: dependencies met
    ready --> claimed: agent claims
    claimed --> completed: success
    claimed --> failed: error
    claimed --> blocked: needs input
    blocked --> ready: unblock
    failed --> ready: retry
Loading

Leases

When an agent claims a task, it receives a lease—an exclusive lock with a TTL.

sequenceDiagram
    participant Agent
    participant Orca

    Agent->>Orca: ClaimTask(task_id)
    Orca->>Agent: Lease (TTL: 5m)

    loop Every 2 minutes
        Agent->>Orca: RenewLease()
        Orca->>Agent: Lease extended
    end

    Agent->>Orca: CompleteTask()
    Orca->>Agent: Lease released
Loading

If an agent crashes, the lease expires and the task returns to ready for another agent.

Note: Leases may become optional in a future release for simpler single-agent workflows.

Dependencies

Tasks can depend on other tasks. Orca automatically manages the ready state.

flowchart LR
    A[Design API<br/>completed] --> C[Implement API<br/>ready]
    B[Set up DB<br/>completed] --> C
    C --> D[Write tests<br/>pending]
Loading

When all dependencies complete, dependent tasks transition to ready automatically.

Push-Based Task Distribution

Orca supports push-based workflows where the server distributes tasks to agents.

Event Subscriptions

// Subscribe to all events after sequence 100
events := client.Subscribe(ctx, 100)
for event := range events {
    switch event.Pattern {
    case "task.created":
        // New task available
    case "task.claimed":
        // Someone claimed a task
    }
}

Server-Side Filtering

Agents can register with tags. Tasks can require specific tags.

# Agent registers with capabilities
agent:
  tags: ["backend", "go", "postgres"]

# Task requires specific agent
task:
  agent_tags: ["backend", "go"]  # Only matching agents can claim

Quick Start

Installation

go install github.com/reecepm/orca/cmd/orca@latest

Local Usage (Embedded Mode)

# Create a workspace and project
orca workspace create "my-workspace"
orca project create "my-project" --workspace my-workspace

# Add tasks
orca task add "Implement user authentication" --project my-project
orca task add "Write API documentation" --project my-project

# List and claim
orca task list --project my-project
orca task claim --agent my-agent

# Complete
orca task complete <task-id> --agent my-agent

Team Usage (Remote Mode)

# Start the server
orca server start --storage postgres --postgres-url "postgres://..."

# Configure clients
cat > ~/.orca/config.yaml << EOF
client:
  mode: remote
  server_address: localhost:50051
EOF

# Use normally—operations go to server
orca task add "Shared task"

Distributed Agents (Hybrid Mode)

# Configure hybrid mode
cat > ~/.orca/config.yaml << EOF
client:
  mode: hybrid
  server_address: orca.company.com:50051
daemon:
  auto_spawn: true
EOF

# Work offline or online—sync happens automatically
orca task add "Works offline"
orca task claim --agent local-agent

Configuration Reference

# ~/.orca/config.yaml

server:
  grpc_port: 50051
  http_port: 8080

client:
  mode: embedded | remote | hybrid
  server_address: localhost:50051
  sync_interval: 30s

storage:
  type: sqlite | postgres
  sqlite_path: ~/.orca/data/orca.db
  postgres_url: postgres://user:pass@host:5432/orca

defaults:
  workspace: default
  project: default
  lease_ttl: 5m
  disable_leases: false  # true = claims never expire

daemon:
  auto_spawn: true
  idle_timeout: 0  # 0 = never stop

logging:
  level: info
  format: text | json

Use Cases

Scenario Mode Storage Why
Solo developer Embedded SQLite Zero setup, local-first
Small team Remote PostgreSQL Shared visibility
Distributed agents Hybrid SQLite + PostgreSQL Offline-capable, synced
CI/CD pipeline Remote PostgreSQL Centralized coordination
Custom dashboard Remote (gRPC) Any Full API access

Roadmap

  • WebSocket transport for browser clients
  • Task templates and workflows
  • Metrics and observability hooks
  • Additional storage backends (DynamoDB, Firestore)

License

MIT. See LICENSE.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages