Skip to content
BranchesTags

Repository files navigation

Agent Manager

A real-time agent management platform for orchestrating AI coding agents running in Docker containers. Features a WebSocket-based gateway for streaming Claude Code CLI output, Convex for persistence and real-time subscriptions, and Tailscale for secure container networking.

Features

  • Agent Containers: Docker containers with Claude Code CLI, connected via Tailscale mesh network
  • Agent Gateway: WebSocket server that orchestrates container connections and streams CLI output
  • Project Management: Create and manage software projects with specifications and task breakdown
  • Task Tracking: Kanban-style task management with dependencies, acceptance criteria, and test tracking
  • Task Phase System: Formal lifecycle management with configurable AI agents per phase
  • Remediation Cycles: Automated issue fixing with AI review validation loops
  • Real-time Streaming: Stream Claude Code CLI output in real-time via WebSocket protocol
  • Infrastructure Monitoring: Server and container management with real-time metrics
  • Pull Request Management: Track PRs, code reviews, issues, and CI/CD status

Tech Stack

Layer Technology
Runtime Bun
Frontend React 19, TypeScript, Tailwind CSS
UI Components shadcn/ui (Radix primitives)
Backend Convex (serverless database + functions)
Gateway Bun WebSocket server with Convex sync
Containers Docker + Tailscale SSH
Icons Lucide React

Quick Start

Prerequisites

  • Bun v1.3.4 or later
  • Docker for running agent containers
  • A Convex account (free tier available)
  • A Tailscale account for container networking

Installation

# Install dependencies
bun install

# Start all development servers (Convex must run separately)
bunx convex dev  # In a separate terminal
bun dev          # Starts frontend, backend, and agent-gateway

The application will be available at:

  • Frontend: http://localhost:3000
  • Agent Gateway: http://localhost:3100 (WebSocket + HTTP API)

Environment Variables

Create .env files as needed:

Root .env (for frontend and agent-gateway):

# Frontend (Vite)
VITE_CONVEX_URL=https://your-deployment.convex.cloud

# Agent Gateway (required for container creation and secret fetching)
CONVEX_URL=https://your-deployment.convex.cloud

Project Structure

agent-manager/
├── packages/
│   ├── frontend/              # React 19 frontend application
│   │   ├── src/
│   │   │   ├── components/    # React components
│   │   │   │   ├── ui/        # shadcn/ui components
│   │   │   │   ├── projects/  # Project views
│   │   │   │   ├── tasks/     # Task views
│   │   │   │   ├── servers/   # Server views
│   │   │   │   └── containers/# Container views
│   │   │   ├── types/         # TypeScript types
│   │   │   └── lib/           # Utilities
│   │   └── package.json
│   │
│   ├── backend/               # Bun HTTP server for frontend
│   │   └── package.json
│   │
│   ├── convex/                # Convex serverless backend
│   │   ├── schema.ts          # Database schema
│   │   ├── http.ts            # HTTP webhook endpoints
│   │   ├── projects.ts        # Project API
│   │   ├── tasks.ts           # Task API
│   │   ├── agentSessions.ts   # Agent session tracking
│   │   ├── agentMessages.ts   # CLI output storage
│   │   └── package.json
│   │
│   ├── agent-gateway/         # WebSocket server for containers
│   │   ├── src/
│   │   │   ├── index.ts       # Gateway server
│   │   │   ├── connections.ts # Connection manager
│   │   │   └── convex-sync.ts # Convex integration
│   │   └── package.json
│   │
│   ├── container-daemon/      # Daemon running inside containers
│   │   ├── src/
│   │   │   ├── index.ts       # Daemon entry point
│   │   │   ├── process-manager.ts  # Claude CLI process manager
│   │   │   ├── convex-integration.ts # Convex connection & commands
│   │   │   └── auth-manager.ts # OAuth flow handling
│   │   └── package.json
│   │
│   └── agent-shared/          # Shared protocol types
│       ├── src/
│       │   └── index.ts       # WebSocket message types
│       └── package.json
│
├── docs/                      # Documentation
│   ├── ARCHITECTURE.md        # Backend architecture
│   └── AGENTS.md              # Agent system design
│
├── package.json               # Root workspace config
├── turbo.json                 # Turbo build config
└── CLAUDE.md                  # AI assistant instructions

Development

Running the Development Servers

# Start Convex backend (watches for changes)
bunx convex dev

# In another terminal, start all services (frontend, backend, gateway)
bun dev

Available Scripts

Command Description
bun dev Start frontend, backend, and agent-gateway (via Turbo)
bun run dev:frontend Start only the frontend
bun run dev:backend Start only the backend
bun run dev:gateway Start only the agent-gateway
bun run dev:convex Start Convex dev server
bun run start Start production backend
bun run start:gateway Start production gateway
bunx convex dev Start Convex development server
bunx convex deploy Deploy Convex to production

Creating Agent Containers

Agent containers are created through the Convex-driven flow:

  1. Via Frontend: Use the UI to create containers from the Containers page
  2. Via API: POST to /containers/create on the gateway
  3. Via Convex: Create a serverCommands.createContainer entry

The gateway automatically:

  1. Generates a unique container name (e.g., proud-blue-falcon)
  2. Fetches Tailscale config from Convex and generates an ephemeral auth key
  3. Fetches GitHub credentials from Convex secrets
  4. Builds and starts the container with proper environment variables
  5. Registers the container in the containerPool for task assignment

Database Management

Access the Convex dashboard to manage your database:

bunx convex dashboard

API Overview

Agent Gateway API

The agent-gateway provides HTTP endpoints and WebSocket connections for container orchestration:

HTTP Endpoints (port 3100)

Endpoint Method Purpose
/health GET Gateway health check with stats
/containers GET List connected containers
/containers/:id GET Get specific container info
/containers/create POST Create new agent container
/containers/:id/auth POST Push auth token to container
/exec POST Start execution on a container
/exec/:id/abort POST Abort running execution

WebSocket Protocol

Containers connect to ws://gateway:3100 and communicate using JSON messages:

// Message structure
{
  id: string;          // Unique message ID
  type: MessageType;   // Message type (connect, exec:start, exec:stream, etc.)
  payload: T;          // Type-specific payload
  timestamp: number;   // Unix timestamp
  correlationId?: string; // For request/response tracking
}

Key message types:

  • connect / connected - Container registration
  • exec:start / exec:stream / exec:complete - CLI execution
  • heartbeat - Keep-alive ping/pong
  • status:health - Container health updates

Convex Functions

Projects & Tasks

  • projects.list / get / create / update - Project management
  • tasks.listByProject / get / create / update - Task management
  • tasks.updateCategory - Move task between columns

Agent Sessions

  • agentSessions.create - Create new CLI session
  • agentSessions.updateStatus - Update session status
  • agentSessions.listByContainer - List sessions for a container

Agent Messages

  • agentMessages.create - Store CLI output message
  • agentMessages.listBySession - Get messages for a session

Infrastructure

  • servers.list / get / create / update - Server management
  • containers.list / updateAgentStatus - Container tracking

Convex Webhook Endpoints

Endpoint Method Purpose
/webhooks/github POST GitHub PR/push events
/webhooks/cicd POST CI/CD status updates
/api/metrics/server POST Server metrics ingestion
/health GET Health check

Architecture

See docs/ARCHITECTURE.md for detailed documentation on:

  • Why Convex was chosen as the backend
  • Database schema design with agent tables
  • Real-time subscription patterns
  • Agent Gateway architecture
  • Container-to-Gateway communication

Task Phase System

Tasks progress through a formal lifecycle with AI agents handling each phase:

┌─────────────┐    ┌──────────┐    ┌────────────────┐    ┌───────────┐
│ Requirements│───▶│ Planning │───▶│ Implementation │───▶│ AI Review │
└─────────────┘    └──────────┘    └────────────────┘    └───────────┘
                                                               │
                         ┌─────────────────────────────────────┤
                         │                                     │
                         ▼                                     ▼
                  ┌─────────────┐                      ┌──────────────┐
             ┌───▶│ Remediation │◀────────────────────│ Human Review │
             │    └─────────────┘                      └──────────────┘
             │           │                                    │
             │           │ (validation)                       │
             │           ▼                                    │
             │    ┌───────────┐                               │
             └────│ AI Review │                               │
                  └───────────┘                               │
                         │                                    │
                         │ (approved)                         │
                         ▼                                    ▼
                  ┌──────────────┐                     ┌───────────┐
                  │ Human Review │────────────────────▶│   Merge   │
                  └──────────────┘     (approved)      └───────────┘

Phase Descriptions

Phase Agent Description
Requirements - User defines task title, description, and initial specifications
Planning Planning Agent Generates acceptance criteria, implementation prompt, and test cases
Implementation Implementation Agent Writes code, creates feature branch, opens pull request
AI Review Review Agent Reviews PR for quality, security, correctness. Approves or requests changes
Remediation Remediation Agent Fixes issues identified by AI or Human review
Human Review Assistant Agent Helps human reviewer test preview deployment and evaluate changes
Merge Merge Agent Resolves conflicts and merges approved PR to main branch

Remediation Cycles

When AI Review or Human Review finds issues, the task enters a remediation loop:

  1. AI Review triggers remediation automatically when it finds issues
  2. Human Review triggers remediation when user clicks "Request Changes" with feedback
  3. Remediation agent fixes the issues in a fresh container
  4. AI Review validates the fixes before returning to Human Review
  5. Cycle limit (configurable, default: 3) prevents infinite loops

Each remediation cycle is tracked with:

  • Trigger source (AI or Human review)
  • Human feedback text (when triggered by human)
  • Agent session output and cost
  • Duration and turn count

Phase Configuration

Each phase can be configured globally or per-task:

  • Provider/Model: Choose AI model (e.g., Claude Sonnet, Opus)
  • Permission Mode: Control agent's file system access (plan, accept_edits, full_auto)
  • Prompt Template: Customize agent instructions with variables
  • Max Budget: Optional cost limit per phase

See docs/ARCHITECTURE.md for database schema details and docs/AGENTS.md for agent workflow documentation.

Agent System

See docs/AGENTS.md for documentation on:

  • Agent Gateway WebSocket server
  • Container API and Claude CLI integration
  • WebSocket protocol specification
  • Container lifecycle management
  • Convex integration for persistence

License

MIT

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages