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 |
|---|
| |
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
