CodeAgents

A distributed, AI-powered code fixing and verification system. CodeAgents uses an orchestrator to generate patches for issues and a network of contributor daemons to independently verify those patches through consensus voting — all coordinated via issue comments on GitHub, GitLab, or Forgejo.

How It Works

  Issue Filed           Orchestrator             Contributor Daemons
  ───────────      ─────────────────────      ──────────────────────────
  "Fix bug in       1. Reads issue              3. Poll repos for tasks
   utils.ts"        2. Generates diff            4. Fetch source files
       │            3. Posts task comment         5. Review patch with AI
       │                    │                     6. Post verdict comment
       ▼                    ▼                              │
   ┌────────┐     ┌──────────────────┐                     ▼
   │ Issue  │────▶│ Task Comment     │◀──── ┌──────────────────────┐
   │ #42    │     │ (embedded JSON)  │      │ Result Comments      │
   └────────┘     └──────────────────┘      │ APPROVE / REJECT     │
                           │                └──────────────────────┘
                           ▼
                  Orchestrator checks consensus
                  ─────────────────────────────
                  ✓ Majority approved → Create PR
                  ✗ Majority rejected → Post reasons

The entire protocol runs through issue comments with embedded JSON — no external queue, database, or message broker required.

Architecture

CodeAgents is a monorepo with four packages:

Package	Description
@codeagents/orchestrator	Central solver — generates patches using Claude, posts verification tasks, evaluates consensus, creates PRs
@codeagents/daemon	Contributor CLI tool — polls for tasks, verifies patches using AI, posts results
@codeagents/adapters	Platform abstraction layer for GitHub, GitLab, and Forgejo/Gitea APIs
@codeagents/shared	Common types, comment protocol parser, and unified diff utilities

Prerequisites

• Node.js >= 18
• npm >= 9 (workspace support)
• An AI provider API key (Anthropic or OpenAI)
• A Git platform API token (GitHub, GitLab, or Forgejo)

Installation

git clone https://github.com/your-org/CodeAgents.git
cd CodeAgents
npm install
npm run build

This builds all four packages. The CLI binaries are:

• codeagents — contributor daemon
• codeagents-orchestrator — central solver

To make them available globally:

npm link --workspaces

Repository Configuration

Add a .codeagents.yml file to the root of any repository you want CodeAgents to manage:

# Which AI models are allowed for verification (glob patterns)
accepted_models:
  - claude-*
  - gpt-4*

# Scope of operation
scope: issues-only

# Issues must have one of these labels to trigger solving
trigger_labels:
  - codeagents

# Verification settings
verification:
  min_verifiers: 3

# Files the AI must never read or modify
protected_paths:
  - .env
  - secrets/

# Rate limiting
max_prs_per_week: 5

Usage

Orchestrator (Solving Issues)

The orchestrator reads an issue, generates a patch using Claude, and posts a verification task.

Required environment variables:

export PLATFORM_TYPE=github          # github | gitlab | forgejo
export PLATFORM_TOKEN=ghp_xxx       # Git platform API token
export PLATFORM_API_URL=https://api.github.com
export REPO_OWNER=myorg
export REPO_NAME=myapp
export SOLVE_MODEL=claude-haiku-4-5-20251001  # optional, default shown

Solve an issue:

codeagents-orchestrator solve --issue 42

This will:

1. Read the issue title and body
2. Fetch up to 10 relevant source files
3. Call Claude to generate a unified diff
4. Post the diff as a task comment on the issue

Check verification consensus:

codeagents-orchestrator check --issue 42

This will:

1. Scan issue comments for task and result entries
2. If enough verifiers have responded (>= min_verifiers), run majority vote
3. Create a PR if approved, or post rejection reasons

Daemon (Contributing Verifications)

The daemon is a background process that polls repositories for verification tasks and reviews them using your configured AI provider.

Initial Setup

codeagents init

Interactive prompts will ask for:

• Platform API key — your contributor identity
• AI provider — anthropic or openai
• Model name — e.g. claude-haiku-4-5-20251001 or gpt-4o-mini
• Monthly token budget — max tokens per month
• Poll interval — seconds between polling cycles
• Repository details — platform, API URL, owner, name, token

Configuration is saved to ~/.codeagents/config.json.

Running the Daemon

# Start the background worker
codeagents start

# Check if it's running
codeagents status

# View detailed statistics
codeagents stats

# Stop the daemon
codeagents stop

Adding More Repositories

codeagents add-repo

What the Daemon Does

On each polling cycle, the worker:

1. Checks budget — stops accepting tasks if tokens_used_this_month >= monthly_token_budget
2. Polls each repository — lists issues with matching trigger labels
3. Finds tasks — parses issue comments for embedded verification tasks
4. Filters — skips tasks already verified, tasks with enough results, or tasks requiring a model you don't have
5. Verifies — fetches source files, builds a review prompt, calls your AI provider
6. Posts result — writes an APPROVE or REJECT verdict as a comment on the issue
7. Tracks usage — updates token count and task statistics

Configuration Reference

Daemon Config (~/.codeagents/config.json)

{
  "provider": "anthropic",
  "api_key": "your-contributor-api-key",
  "model": "claude-haiku-4-5-20251001",
  "monthly_token_budget": 100000,
  "poll_interval_seconds": 300,
  "repos": [
    {
      "platform": "github",
      "api_url": "https://api.github.com",
      "owner": "myorg",
      "name": "myapp",
      "token": "ghp_xxx"
    }
  ]
}

Daemon Stats (~/.codeagents/stats.json)

Automatically managed. Tracks token usage and task counts with monthly auto-reset.

{
  "tokens_used_this_month": 12400,
  "tasks_completed": 47,
  "tasks_timed_out": 0,
  "last_reset_month": "2026-04",
  "started_at": "2026-04-05T10:00:00Z"
}

Environment Variables

Variable	Used By	Description
PLATFORM_TYPE	Orchestrator	github, gitlab, or forgejo
PLATFORM_TOKEN	Orchestrator	Git platform API token
PLATFORM_API_URL	Orchestrator	Platform API endpoint
REPO_OWNER	Orchestrator	Repository owner
REPO_NAME	Orchestrator	Repository name
SOLVE_MODEL	Orchestrator	Model for patch generation (default: claude-haiku-4-5-20251001)
CODEAGENTS_DATA_DIR	Daemon	Override ~/.codeagents data directory

Comment Protocol

Communication between orchestrator and daemons happens via HTML comments embedded in issue comments, invisible to regular users.

Task comment (posted by orchestrator):

<!-- codeagents:task
{
  "task_id": "uuid",
  "solution_id": "uuid",
  "type": "verify",
  "accepted_models": ["claude-*", "gpt-4*"],
  "diff": "--- a/src/utils.ts\n+++ b/src/utils.ts\n@@ -10,3 +10,5 @@..."
}
-->

Result comment (posted by daemon):

<!-- codeagents:result
{
  "task_id": "uuid",
  "solution_id": "uuid",
  "contributor_id": "ca-xxxx",
  "verdict": "approve",
  "reasoning": "The patch correctly handles the empty string edge case.",
  "model": "claude-haiku-4-5-20251001",
  "tokens_used": 840
}
-->

Development

Building

npm run build          # Build all packages

Testing

npm test               # Run all tests across all packages

Or test individual packages:

cd packages/shared && npm test
cd packages/adapters && npm test
cd packages/orchestrator && npm test
cd packages/daemon && npm test

Running in Dev Mode

# Daemon
cd packages/daemon && npm run dev -- start

# Orchestrator
cd packages/orchestrator && npm run dev -- solve --issue 42

Project Structure

CodeAgents/
├── packages/
│   ├── shared/                 # Types, protocol parser, diff utilities
│   │   └── src/
│   │       ├── types.ts
│   │       ├── protocol.ts
│   │       └── diff-parser.ts
│   ├── adapters/               # GitHub, GitLab, Forgejo API adapters
│   │   └── src/
│   │       ├── adapter.ts      # PlatformAdapter interface
│   │       ├── github.ts
│   │       ├── gitlab.ts
│   │       └── forgejo.ts
│   ├── orchestrator/           # Central issue solver
│   │   └── src/
│   │       ├── cli/            # solve & check commands
│   │       ├── solver/         # AI agent & prompt builder
│   │       ├── consensus/      # Majority vote evaluator
│   │       └── config/         # .codeagents.yml loader
│   └── daemon/                 # Contributor verification daemon
│       └── src/
│           ├── cli/            # init, start, stop, status, stats, add-repo
│           ├── daemon/         # Worker loop, logger, PID management
│           ├── config/         # Zod schemas, config/stats loader
│           └── providers/      # Anthropic & OpenAI implementations
├── package.json                # Workspace root
└── tsconfig.base.json          # Shared TypeScript configuration

Supported Platforms

Platform	Adapter	API Support
GitHub	github.ts	Issues, comments, file content, pull requests
GitLab	gitlab.ts	Issues, notes, repository files, merge requests
Forgejo / Gitea	forgejo.ts	Issues, comments, file content, pull requests

License

ISC