An agentic-based coding orchestrator for both on-prem and off-prem development.

AgentiCorp is a lightweight AI coding agent orchestration system that manages workflows, handles agent lifecycle, and provides real-time event streaming for monitoring and coordination.

Start here: MANUAL.md - Complete system manual with quick start guide

Then explore:

• User Guide - Getting started and operational workflows
• Architecture - System design and components
• Entities Reference - All data structures explained
• Temporal DSL Guide - Workflow language for agents
• Developer Guide - For contributors and custom agents

• 🤖 Agent Orchestration: Spawn and manage AI agents with different personas
• 🔄 Workflow Management: Temporal-based workflow orchestration for reliable task execution
• 📊 Work Graph: Track dependencies and relationships between work items (beads)
• 🔐 Decision Framework: Approval workflows for agent decisions
• 📡 Real-time Events: Server-Sent Events (SSE) for live status updates
• 🎯 Smart Routing: Intelligent task assignment and agent coordination
• 🔒 Secure: Encrypted secret storage and secure credential management

Default personas are available under ./personas/:

• personas/agenticorp — AgentiCorp-specific system persona(s)
• personas/default/ceo — Human CEO decision maker (tie-breaks / approvals)
• personas/default/project-manager — Plans work, files beads, drives delivery
• personas/default/product-manager — Identifies feature gaps and writes PRDs for epics
• personas/default/engineering-manager — Reviews technical direction and feasibility
• personas/default/code-reviewer — Reviews patches for correctness and quality
• personas/default/qa-engineer — Testing strategy and verification
• personas/default/devops-engineer — Deployment/ops and infrastructure guidance
• personas/default/documentation-manager — Keeps docs accurate per doc policy
• personas/default/decision-maker — Resolves routine decisions (non-CEO)
• personas/default/web-designer — UX/UI guidance
• personas/default/web-designer-engineer — UX/UI + implementation guidance
• personas/default/public-relations-manager — Messaging/launch communication support
• personas/default/housekeeping-bot — Cleanup and hygiene tasks

The initial user guide is available in docs/USER_GUIDE.md.

Projects are registered via config.yaml under projects: (and persisted in the configuration DB when enabled).

Required fields:

• id, name, git_repo, branch, beads_path

Optional fields:

• is_perpetual (never closes)
• context (recommended: build/test/lint commands and other agent-relevant context)

Example:

projects:
  - id: agenticorp
    name: AgentiCorp
    git_repo: https://github.com/jordanhubbard/agenticorp
    branch: main
    beads_path: .beads
    is_perpetual: true
    context:
      test: go test ./...
      vet: go vet ./...

AgentiCorp “dogfoods” itself by registering this repo as a project and loading beads from the project’s .beads/ directory.

AgentiCorp is built with the following principles:

• Go-First Implementation: All primary functionality is implemented in Go for performance and maintainability
• Containerized Everything: Every component runs in containers for consistency across environments
• Temporal Workflows: Reliable, durable workflow orchestration using Temporal
• Event-Driven: Real-time event bus for agent communication and UI updates

• Docker (20.10+)
• Docker Compose (1.29+)
• Go 1.24+ (for local development only)
• Make (optional, for convenience commands)

The Docker setup includes:

• AgentiCorp application server (port 8080)
• Temporal server (port 7233)
• Temporal UI (port 8088)
• PostgreSQL database for Temporal

# Build and run all services using docker compose
docker compose up -d

# View logs
docker compose logs -f agenticorp

# View Temporal UI
open http://localhost:8088

# Stop all services
docker compose down

# Build and run
make docker-run

# Build Docker image
make docker-build

# Stop services
make docker-stop

# Clean Docker resources
make docker-clean

AgentiCorp uses Temporal for reliable workflow orchestration. Temporal provides:

• Durable Execution: Workflows survive crashes and restarts
• Event History: Complete audit trail of all workflow executions
• Signals & Queries: Real-time workflow interaction
• Timeout Management: Automatic handling of long-running operations

The system includes:

1. Temporal Server: Core workflow engine (port 7233)

2. Temporal UI: Web interface for monitoring workflows (port 8088)

3. PostgreSQL: Persistence layer for workflow state

4. Temporal Worker: Executes workflow and activity code

5. Ensure all code follows the architecture principles above

6. All new features must be containerized

7. File a bead for your work - See BEADS_WORKFLOW.md

8. Update documentation for any new features or changes

9. Run tests and linters before submitting changes

For detailed contribution guidelines, see CONTRIBUTING.md. An AI Coding Agent Orchestrator for both on-prem and off-prem development.

AgentiCorp implements several key workflows:

Manages the complete lifecycle of an agent from spawn to shutdown:

• Tracks agent status (spawned, working, idle, shutdown)
• Handles bead assignments
• Responds to queries for current status
• Gracefully shuts down on signal

Manages work item (bead) lifecycle:

• Tracks status transitions (open, in_progress, blocked, closed)
• Handles agent assignments
• Manages dependencies and blockers
• Provides status queries

Handles approval workflows with timeout:

• Creates decision points for agent questions
• Waits for human or agent approval
• 48-hour default timeout
• Unblocks dependent work on resolution

The Temporal-based event bus provides real-time updates:

Event Types:
- agent.spawned        - New agent created
- agent.status_change  - Agent status updated
- agent.completed      - Agent finished work
- bead.created         - New work item created
- bead.assigned        - Work assigned to agent
- bead.status_change   - Work status updated
- bead.completed       - Work item finished
- decision.created     - Decision point created
- decision.resolved    - Decision made
- log.message          - System log message

# Health check
GET /api/v1/health

# Agents
GET    /api/v1/agents
POST   /api/v1/agents
GET    /api/v1/agents/{id}

# Beads (work items)
GET    /api/v1/beads
POST   /api/v1/beads
GET    /api/v1/beads/{id}
PUT    /api/v1/beads/{id}

# Decisions
GET    /api/v1/decisions
POST   /api/v1/decisions
PUT    /api/v1/decisions/{id}

# Projects
GET    /api/v1/projects
GET    /api/v1/projects/{id}

# Work Graph
GET    /api/v1/work-graph?project_id={id}

Real-time event streaming via Server-Sent Events:

# Stream all events
GET /api/v1/events/stream

# Stream events for specific project
GET /api/v1/events/stream?project_id=example-project

# Stream specific event types
GET /api/v1/events/stream?type=agent.spawned

# Get event statistics
GET /api/v1/events/stats

Example: Subscribe to events using curl:

curl -N http://localhost:8080/api/v1/events/stream

Example: Subscribe to events using JavaScript:

const eventSource = new EventSource('http://localhost:8080/api/v1/events/stream?project_id=my-project');

eventSource.addEventListener('agent.spawned', (e) => {
  const data = JSON.parse(e.data);
  console.log('Agent spawned:', data);
});

eventSource.addEventListener('bead.created', (e) => {
  const data = JSON.parse(e.data);
  console.log('Bead created:', data);
});

Configuration is managed via config.yaml:

server:
  http_port: 8080
  enable_http: true

temporal:
  host: localhost:7233              # Temporal server address
  namespace: agenticorp-default        # Temporal namespace
  task_queue: agenticorp-tasks         # Task queue name
  workflow_execution_timeout: 24h   # Max workflow duration
  workflow_task_timeout: 10s        # Workflow task timeout
  enable_event_bus: true            # Enable event bus
  event_buffer_size: 1000           # Event buffer size

agents:
  max_concurrent: 10
  default_persona_path: ./personas
  heartbeat_interval: 30s
  file_lock_timeout: 10m

## Completed Features

- [x] Project state management (open, closed, reopened)
- [x] Project comments and closure workflow
- [x] AgentiCorp persona for self-improvement
- [x] Perpetual projects that never close
- [x] Provider registration and health checking
- [x] Agent orchestration with personas
- [x] Work item (bead) management with dependencies
- [x] Decision approval workflows
- [x] Real-time event streaming (SSE)
- [x] Temporal workflow orchestration
- [x] Database state persistence (SQLite)
- [x] Web UI for monitoring and control
- [x] Provider status detection and activation
- [x] Master heartbeat and dispatcher workflows
- [x] Temporal DSL for agent workflow requests
- [x] Complete documentation and user manual

## Planned Features

- [ ] Implement HTTP response streaming for real-time provider output
- [ ] Add analytics and request/response logging
- [ ] Implement provider pooling and load balancing
- [ ] Add per-provider rate limiting and quotas
- [ ] Support custom provider plugins
- [ ] Add caching layer for frequently used models
- [ ] Implement multi-region provider failover
- [ ] Add authentication and authorization for AgentiCorp API
- [ ] Support for custom authentication to providers
- [ ] Metrics and monitoring endpoints (Prometheus compatible)

## Project State Management

AgentiCorp supports sophisticated project lifecycle management:

### Project States
- **Open**: Active project with ongoing work
- **Closed**: Completed project with no remaining work
- **Reopened**: Previously closed project that has been reopened

### Features
- **Comments**: Add timestamped comments to track project decisions
- **Closure Workflow**: Close projects only when no open work remains
- **Agent Consensus**: If open work exists, requires agent agreement to close
- **Perpetual Projects**: Mark projects (like AgentiCorp itself) that never close

### API Endpoints

```bash
# Close a project
POST /api/v1/projects/{id}/close
{
  "author_id": "agent-123",
  "comment": "All features complete, tests passing"
}

# Reopen a project
POST /api/v1/projects/{id}/reopen
{
  "author_id": "agent-456",
  "comment": "New requirements discovered"
}

# Add a comment
POST /api/v1/projects/{id}/comments
{
  "author_id": "agent-789",
  "comment": "Architecture review complete"
}

# Get project state
GET /api/v1/projects/{id}/state

The AgentiCorp system includes a special agenticorp persona that works on improving the AgentiCorp platform itself:

• Self-Improving: Continuously enhances the platform
• Collaborative: Works with UX, Engineering, PM, and Product personas
• Perpetual: The agenticorp project never closes
• Meta-Circular: An AI orchestrator that orchestrates its own improvement

See personas/agenticorp/ for the complete persona definition.

# Install dependencies
go mod download

# Build the binary
go build -o agenticorp ./cmd/agenticorp

# Run the application
./agenticorp

# Run all tests
go test ./...

# Run tests with coverage
go test -v -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

# Run specific package tests
go test ./internal/temporal/...

For local development with Temporal:

1. Start Temporal server:

docker compose up -d temporal temporal-postgresql temporal-ui

2. Build and run agenticorp locally:

go build -o agenticorp ./cmd/agenticorp
./agenticorp

3. Access Temporal UI:

open http://localhost:8088

agenticorp/
├── cmd/agenticorp/              # Main application entry point
│   └── main.go
├── internal/
│   ├── agent/               # Agent management
│   ├── agenticorp/             # Core orchestrator
│   ├── beads/               # Work item management
│   ├── decision/            # Decision framework
│   ├── temporal/            # Temporal integration
│   │   ├── client/          # Temporal client wrapper
│   │   ├── workflows/       # Workflow definitions
│   │   ├── activities/      # Activity implementations
│   │   ├── eventbus/        # Event bus implementation
│   │   └── manager.go       # Temporal manager
│   ├── api/                 # HTTP API handlers
│   └── models/              # Data models
├── pkg/
│   ├── config/              # Configuration management
│   └── models/              # Shared models
├── config/
│   └── temporal/            # Temporal configuration
├── docker-compose.yml       # Container orchestration
├── Dockerfile              # Multi-stage Docker build
├── config.yaml.example     # Example configuration
└── README.md              # This file

Access the Temporal UI at http://localhost:8088 to:

• View workflow executions
• Inspect workflow history
• Monitor active workflows
• Debug workflow failures
• Query workflow state

Monitor real-time events:

# Watch all events
curl -N http://localhost:8080/api/v1/events/stream

# Monitor specific project
curl -N "http://localhost:8080/api/v1/events/stream?project_id=my-project"

View service logs:

# All services
docker compose logs -f

# Specific service
docker compose logs -f agenticorp
docker compose logs -f temporal

If agenticorp can't connect to Temporal:

1. Check Temporal is running:

docker compose ps temporal

2. Check Temporal logs:

docker compose logs temporal

3. Verify connectivity:

docker exec agenticorp nc -zv temporal 7233

If workflows aren't starting:

1. Check worker is running:

docker compose logs agenticorp | grep "Temporal worker"

2. Verify task queue in Temporal UI
3. Check workflow registration in logs

If event stream endpoint returns errors:

1. Verify Temporal is enabled in config
2. Check event bus initialization:

docker compose logs agenticorp | grep "event bus"

1. Primary Language: Implement all core functionality in Go
2. Containerization: All services must run in containers
3. Workflows: Use Temporal workflows for long-running operations
4. Events: Publish events for all state changes
5. Testing: Write tests for workflows and activities
6. Documentation: Update docs for new features

When contributing to this project:

1. Ensure all code follows the architecture principles
2. All new features must be containerized
3. Write Temporal workflows for async operations
4. Add appropriate event publishing
5. Update documentation
6. Run tests and linters before submitting

See LICENSE file for details.