What is ForgeAI

ForgeAI is an intelligent project cockpit for AI-driven software development. It gives your team a structured, visible way to go from an idea to shipped code: methodology-guided workflows produce planning artifacts, those artifacts turn into grouped tasks with dependencies, and AI coding agents execute the tasks on your own machine while you watch them work on a live Kanban board.

ForgeAI is made of two halves that are designed to work together.

The cockpit

The cockpit is the web app — the beta instance runs at https://forgeai-production-382c.up.railway.app. It is where your team:

• Manages organizations, members, and roles
• Creates projects, optionally linked to a GitHub repository
• Runs BMAD workflows in a guided wizard, chatting with an agent step by step and approving deliverables
• Watches agents execute tasks on the live board, with AI sessions streaming in real time
• Ships finished work through releases and merge-back

Workflow conversations are encrypted at rest with a per-workflow AES-256-GCM key — see Security for details.

The CLI

The forge CLI is the execution engine that runs on your machine. It is published on npm under the Apache-2.0 license. It:

• Authenticates to the cockpit with an OAuth device flow (forge auth login) — see Authenticating the CLI
• Registers itself as a CLI device in your organization and holds a persistent WebSocket connection
• Spawns AI coding agents (Claude Code, Codex, OpenCode, or Kilo) inside local Docker containers when the cockpit dispatches work
• Manages the git lifecycle for you: workflow branches, task branches, pushes, and merges
• Opens any task, workflow, or release branch locally with a single command (forge task open <taskId>, forge workflow open <workflowId>, forge release open <releaseId>)

Install it with npm install -g @getforgeai/cli@beta — see Installing the CLI for the details, and the CLI command reference for every command.

How the two halves communicate

The CLI and the cockpit talk over two channels:

Channel	Used for
WebSocket (Socket.io)	Real-time dispatch of tasks and workflow steps to the CLI, heartbeats (every 30 seconds), live streaming of agent output back to the board and wizard
REST (/api/cli/*)	Device registration, task status updates, resync after a disconnect, and one-off connectivity checks (used by forge auth status)

Your browser also holds a WebSocket connection to the cockpit, which is how the board and the workflow wizard update live for every viewer.

The CLI is resilient to disconnects: events that occur while the WebSocket is down are journaled locally as NDJSON files under ~/.forgeai/events and replayed to the cockpit over REST when the connection comes back.

The BMAD methodology

BMAD is the built-in methodology that structures a project's lifecycle from analysis to implementation. A BMAD workflow walks you through a sequence of steps in a wizard — an agent drafts each deliverable (for example a brief, a PRD, or an architecture document), you review it, request changes or approve, and the workflow advances. Workflows distinguish greenfield projects from brownfield changes (major, minor, or patch), which determines the git branch naming and which workflow templates apply. When a workflow completes, it can generate grouped tasks with dependencies that agents then execute. See BMAD workflows for the full walkthrough.

Your machine, your AI tokens

ForgeAI does not run AI models in the cloud. Agents run in Docker containers on the machine where you run forge connect, authenticated with your own AI credentials:

• You store the credentials once — forge auth setup-claude, setup-codex, setup-opencode, or setup-kilo depending on the agent engine you pick; the CLI keeps them in the macOS Keychain (or an encrypted file on other platforms) and configures each agent container at spawn time.
• Agents use your existing subscription or API key (Claude, ChatGPT/OpenAI, the provider behind OpenCode, or your Kilo account) — ForgeAI adds no per-token AI cost on top.
• Your repository is cloned inside the container on your machine; the cockpit stores task metadata, conversations, and artifact records, not your working tree.

This is why creating a workflow requires at least one registered CLI device: the AI work physically happens on your hardware. If the registered CLI is offline, the workflow is still created and branch creation is deferred until a CLI connects. Docker is therefore a hard requirement — see Prerequisites.

What the beta includes

The current beta (v0.1.0-beta) includes:

• BMAD workflows with the step-by-step wizard, artifact review, and encrypted conversations
• Automatic task generation from completed workflows, with task groups and dependencies
• The live Kanban board with real-time agent streaming and human-in-the-loop reviews
• The release system: merge-back of workflow branches and versioned releases executed by agents
• Organizations with built-in and custom roles, invitations, and per-device CLI management

The beta moves quickly — follow the changelog to track what changes between releases.

Known beta limitations:

• Billing is inactive — everything is free while plans and pricing are finalized; see Plans & billing
• File uploads are disabled — artifact contents live in the database for now
• Single region, single instance — the platform runs on one node during the beta
• CLI is a prerelease — published under the beta npm tag, so install it as @getforgeai/cli@beta; see Installing the CLI
• Claude Code is the most battle-tested engine — Codex, OpenCode and Kilo support is newer; report anything odd
• Apple Silicon first — the agent Docker image is built for ARM64, so macOS on Apple Silicon is the best-supported platform

If something breaks, check Troubleshooting & FAQ.

Next steps

1. Read the Prerequisites — accounts, Docker, git, and Node requirements.
2. Follow the Quickstart to create an organization, install the CLI, connect it, and run your first workflow.