codeforge

README

codeforge.tomasgrasl.cz

Overview

CodeForge is a backend orchestrator for AI-powered code work over git repositories. A session is a stateful work unit over a repo: it clones, runs an AI CLI (Claude Code, Codex, Cursor), streams progress live, and keeps the workspace around for follow-ups, review, and PR creation. A React web UI is included.

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

Highlights

• Multi-turn sessions with native conversation resume (claude --resume), so follow-ups keep full context
• Live stream of tool calls, thinking, plan progress, and per-turn token/dollar cost (SSE)
• Human-in-the-loop: inspect the actual diff in the UI before a PR is ever opened; PRs only on explicit action
• Code review built in: review a session's changes, or let GitHub/GitLab webhooks trigger PR reviews automatically
• Session types for every job: code, plan, whole-repo review, PR review, and knowledge sessions that keep .codeforge/ docs fresh
• Blueprints: reusable session templates with parameters, runnable on demand or on a schedule, with built-ins like the Sentry fixer and repo review
• Schedules: recurring cron sessions with run history, overlap guard, and failure notifications, including scheduled repo reviews and knowledge updates
• Cost & usage tracking per session and per tenant, with quotas and a key pool (subscription mode)
• Multi-CLI (Claude Code, Codex, Cursor) selectable per session, plus MCP tool integration
• Ops-friendly: Redis queue with crash-safe recovery, Prometheus metrics, Slack/Discord/Teams notifications

Screenshots

Session with live stream, cost & diff	Recurring schedules

New session	Session list

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

Security model

Running a session means executing a repository's code, and letting the AI decide what to run, with approvals disabled. Repository content is attacker-controlled input, so it is worth being precise about what is and is not contained.

What it is today: the AI CLI runs in the same container as the server, dropped to a non-root user. That is a privilege boundary, not isolation. There is no per-session container, VM, or network policy.

What the server does contain:

• The CLI subprocess gets an allowlisted environment, not the server's. The encryption key protecting the credential registry, the operator token, webhook secrets and the Redis URL never enter a session.
• Git credentials are supplied through short-lived GIT_ASKPASS scripts that are removed before the CLI starts; tokens never reach the URL or .git/config.
• Fork PRs and comment commands (/review, /fix) require an author with write access. Off by default for everyone else — a valid webhook signature proves the event came from GitHub, not that its author is trusted.
• Opening a PR always requires an explicit action. This is a hard-coded invariant, not a configuration flag.

What it does not do yet: isolate sessions from each other, from the database on the shared filesystem, or from the network. Per-session sandboxing is the next step.

Because CodeForge is self-hosted, the remaining responsibility sits with whoever deploys it. Point it at repositories where you trust everyone with PR access, and treat the host as part of that trust domain. Repository-level controls — such as requiring approval before workflows run on fork PRs — are a useful additional layer, though note they gate CI workflows rather than webhook deliveries.

Details in Deployment and Configuration. Found something? Open a security advisory rather than a public issue.

Documentation

Document	Description
API Reference	Endpoints, request/response, session types, webhooks
Session Types	code, plan, review, pr_review, knowledge: behavior, output contracts, scheduling
Blueprints	Named session templates: parameters, built-in library, run API, scheduling
Architecture	System design, Redis schema, session lifecycle, streaming
Code Review	Session 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, session types

License

MIT | Tomas Grasl · tomasgrasl.cz