Overview

CodeForge is a backend orchestrator for AI-powered code work over git repositories. A task is a session over a repo — it clones, runs an AI CLI (Claude Code, Codex), streams progress via SSE, and supports multi-turn follow-ups, code review, PR creation, and webhook-triggered PR reviews.

Two modes: Server (queue + workers + API) or CI Action (self-contained GitHub Action / GitLab CI step for automated PR review).

Client ──▶ POST /tasks ──▶ Queue ──▶ Worker (clone → CLI → result)
       ◀── SSE stream ◀──────────────────────────────────────────┘
       ──▶ POST /tasks/{id}/instruct | review | create-pr

Quick Start

docker pull ghcr.io/freema/codeforge:latest

A ready-to-use compose file is at deployments/docker-compose.production.yaml. For development:

# Requires Docker + Task runner (https://taskfile.dev)
task dev

# Create a task
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "https://github.com/user/repo.git", "access_token": "ghp_...", "prompt": "Fix the failing tests"}'

See API Reference for all endpoints and examples.

CI Action (GitHub Actions / GitLab CI)

Add automated AI code review to any repository — 1 secret, 12 lines of YAML:

# .github/workflows/review.yml
name: Code Review
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: freema/codeforge@v1
        with:
          api_key: ${{ secrets.ANTHROPIC_API_KEY }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Task types: pr_review (default), code_review, knowledge_update, custom CLIs: Claude Code, Codex | Platforms: GitHub Actions, GitLab CI

See CI Action docs for full configuration.

Documentation

Document	Description
API Reference	Endpoints, request/response, task types, webhooks
Architecture	System design, Redis schema, task lifecycle, streaming
Code Review	Task review, PR review, webhook-triggered reviews
Configuration	Environment variables, YAML config, all options
Deployment	Docker, Kubernetes, monitoring
Development	Dev setup, testing, project structure, conventions
Manual E2E Testing	Manual lifecycle tests against real repos (Claude + Codex)
CI Action	GitHub Action / GitLab CI setup, inputs, task types

Roadmap

• Multi-step workflows (fetch → task → action)
• Multi-CLI support (Claude Code + Codex)
• Code review as action (POST /tasks/:id/review)
• Task types (code, plan, review, pr_review)
• Automated PR review (webhooks + comment posting)
• CI Action — self-contained GitHub Action / GitLab CI step (multi-CLI, tools, review posting)
• Cross-task memory (project context across tasks)
• Enhanced PR descriptions
• Multi-user auth + usage tracking

License

MIT | Tomas Grasl — tomasgrasl.cz