Forge

The open-source AI-powered software lifecycle platform. Manage software from build through maintain — powered by Claude Code on devices you control.

Status: alpha — not production-ready. Expect breaking changes across v0.x.

What it is

Forge is an open-source AI-powered software lifecycle platform. You keep using claude on your own machine with your own Claude Pro/Max subscription. Forge adds the layer around it: a web dashboard to manage projects from build through maintenance, a configurable pipeline that routes issues through stages, and a full audit trail of every job. The server never holds your Claude credentials.

• Devices pair into your account. Your laptop, desktop, or CI box runs the Forge agent, which spawns claude locally. The server never holds Claude credentials.
• Issues flow in from anywhere. GitHub webhooks, Sentry alerts, Stripe events, your own API — point a webhook at Forge, it becomes an issue.
• A configurable pipeline routes work. Default flow: triage → clarify → plan → code → review → test → release. Per stage: auto-run or human gate. Shorten, extend, or replace it per project.
• Every job is captured. stdout, stderr, tool calls, diffs, token usage — streamed to the dashboard in real time, resumable on disconnect, replayable later.
• Extensible. Author your own skills, define your own pipeline stages, bring your own runner.
• Multi-project, multi-device. One Forge instance coordinates many projects. Each project binds to devices from a pool; one active at a time.

Think GitHub Actions self-hosted runners, for Claude Code. Devices yours. Compute yours. Orchestration open-source.

What it is NOT

• Not a Claude Code replacement — we orchestrate the CLI, we don't reimplement.
• Not a chat UI — the primary surface is a pipeline dashboard.
• Not a tool that uses the Anthropic API — we never hold Claude credentials.
• Not enterprise PM — no complex RBAC in v0.x.

Quickstart

git clone https://github.com/SidCorp-co/forge.git
cd forge
cp .env.example .env
docker compose up -d

• Core API: http://localhost:8080
• Web dashboard: http://localhost:3000

Install the desktop agent (spawns claude on your machine) from Releases, or run forged pair <code> once the CLI daemon ships.

Full walkthrough: docs/quickstart.md.

Architecture

  Your browser / phone                 Your machine(s)
  ┌──────────────┐                     ┌──────────────────────┐
  │ web (Next.js)│                     │ Device agent         │
  │ dashboard    │                     │ - Tauri GUI (dev), or│
  │              │                     │ - CLI daemon (forged)│
  └──────┬───────┘                     │                      │
         │ REST + WebSocket            │ runs `claude` locally│
         ▼                             │ in a git worktree    │
  ┌────────────────────────────────────┐└────────┬─────────────┘
  │  Control plane (packages/core)     │         │
  │  Hono + Drizzle + pg-boss + ws     │ WebSocket (events, jobs)
  │  + MCP                             │◄────────┘
  │  Pipeline engine, job dispatcher   │
  │  NEVER holds Claude credentials    │
  └──────────┬─────────────────────────┘
             ▼
       ┌──────────────────────┐
       │ Postgres             │
       │ state + jobs + vectors│
       └──────────────────────┘

Two key boundaries:

1. Control plane vs. runtime. The server queues jobs and streams events. Devices run Claude Code. A server compromise never leaks Claude credentials — they live on your machines.
2. Dual-principal auth. A user (JWT) and a device (long-lived revocable token) are two separate principals. Shared policy layer enforces every access.

See docs/architecture/system-overview.md and RFC 0001.

Packages

Package	Role	Dev
packages/core/	Control plane: Hono + Drizzle + pg-boss + WebSocket + MCP	pnpm dev
packages/web/	Next.js dashboard: kanban, replay, pipeline health, devices	pnpm dev
packages/dev/	Tauri desktop device agent (GUI form factor)	pnpm tauri dev
packages/forged/	CLI daemon device agent (headless) — coming soon	—
packages/widget/	Embeddable chat widget	pnpm dev
packages/contracts/	Shared TypeScript contracts	—

Mobile app (packages/app/) paused for v0.x per ADR 0009.

How it works

1. Pair a device. Account → Devices → "Add device" generates a pairing code. Run forged pair F9-3K7T-92XA on your machine (or paste into the Tauri app). Token stored in the OS keychain. Device appears online in the dashboard.
2. Bind a project to a device. Project → Settings → Runtime → pick a device from your pool. First bind prompts for the repo's local path and runs git clone if needed. One device active at a time per project.
3. An issue arrives. Via webhook or created in the dashboard. Pipeline enqueues the first stage (forge-triage) as a job.
4. The dispatcher picks a device. Job pushed over WebSocket to the project's active device. Device spawns claude locally, streams stdout / tool calls / diffs back to the server.
5. You watch and gate. Dashboard streams events real-time. Approve the plan, reject the diff, move it along. Finished jobs advance the pipeline.
6. The server keeps receipts. Every job has a full event log retained 30 days after termination. Issues persist.

Extending

• Skills — author your own in .claude/skills/ and register with a pipeline stage.
• Pipeline stages — modify the 14-status state machine for domain flows (RFC required for public releases).
• Runners — the device-agent runner is pluggable. Default runs claude CLI; future runners can be anything that emits the Forge event protocol.

Roadmap

See docs/VISION.md §8.

Current focus: v0.1 — device-runner architecture, job pipeline, session replay, webhook ingestion.

Documentation

• Vision — concept, audience, non-goals, horizons
• Quickstart
• Architecture
• RFC 0001: Device-runner architecture
• Decisions (ADRs)
• Modules

Contributing

See CONTRIBUTING.md. The repo follows Trunk-Based Development — single main, no develop, branches live <1 day, feature flags absorb in-flight work. Rationale + rules: ADR 0014.

First-time? Look for good-first-issue.

Significant changes require an RFC — see docs/rfcs/ for format.

Security vulnerabilities: do not open public issues — see SECURITY.md.

License

Apache-2.0 © Forge contributors.