Quickstart

Create your first project with BlueForge in under 2 minutes.

Installation

BlueForge is available as a desktop app (macOS/Windows), an npm CLI, and Docker image.

Desktop App

Download for the full IDE experience with integrated terminal, file browser, and live preview.

CLI (npm)

Requires Node.js 18+.

Docker

# One-shot mode
docker run --rm -v $(pwd):/workspace \
  -e ANTHROPIC_API_KEY=sk-... \
  blueforge-cli "Build a landing page"

# HTTP server mode
docker run -d -p 3202:3202 \
  -v $(pwd):/workspace \
  blueforge-cli --serve

System Requirements

Import existing project

Bring your existing project into BlueForge. Auto-detect your tech stack, scan for databases, and continue building with AI assistance.

Steps

Supported Stacks 40+

BlueForge auto-detects 13 ecosystems (incl. embedded firmware — PlatformIO & Arduino) and 40+ frameworks. Import any project and continue development with AI assistance.

Node.js / JavaScript / TypeScript

Python

Package managers: pip, poetry, pipenv, uv, conda

Go

Rust

Java / Kotlin (JVM)

Dart / Flutter

PHP

Ruby

C# / .NET

Deno

Static Sites & Docker

Embedded / Firmware New

Embedded projects compile to firmware — there's no dev server or browser preview. BlueForge auto-detects the toolchain, compiles, and parses gcc/PlatformIO compiler errors (file:line:col) so the AI can self-fix. Flash with pio run -t upload / arduino-cli upload when a board is connected. ESP32 & Arduino first. Requires pio / arduino-cli installed locally.

Database & BaaS Detection

Home

Your project hub. Create, import, and manage all projects from here.

Project Cards

Each project is a card with name, description, tech stack, and last modified date. Click to open.

Sidebar Navigation

• Home — Project list
• Settings — API keys, preferences
• MCP Servers — Manage MCP connections
• Commands — Slash command management
• Agent Skills — Passive behavioral skills
• Extensions — Marketplace

Discovery

The Discovery wizard guides you through defining your project. Describe what you want, and BlueForge generates a complete architecture blueprint.

Blueprint

A visual representation of your entire app architecture, organized into 5 layers.

5-Layer Structure

Implementation Tiers

Project Dashboard

A 9-phase lifecycle view from planning to production monitoring.

Layout

Header shows project name and progress gauge. The Phase Timeline displays 9 circular stages below.

Phases

Data Persistence

All settings are auto-saved to project.json. Tokens are stored in OS secure keychain.

Phase 1 — Plan

Summarizes project requirements from Discovery.

Radar Chart

Displays 5 axes — Screens, Features, Architecture, Processes, DB/API — showing project scope. This phase is read-only. Edit the Blueprint directly.

Phase 2 — Design

Configure your project's visual design system.

Design Theme

8 AI-recommended themes. Click a card to apply. "Browse All" for the full preset library.

Color Palette

6 colors: Primary, Secondary, Accent, Background, Surface, Text.

Live Preview

Preview in Login, Landing, and Dashboard layouts.

Typography

Heading, Body, and Mono fonts from Google Fonts with live preview.

Theme & Shape

Mode (Light/Dark/System) and Radius (None/Small/Medium/Large).

Phase 3 — Source Control

Connect GitHub for version control.

Phase 4 — Infrastructure

Choose backend, hosting, and database stack.

Recommended Combos

7 pre-configured stacks (ForgeDB Native, Vercel+Supabase, AWS Full Stack). Each shows price tier.

Custom Stack

Phase 5 — Build

Code generation, task management, and quality verification.

Generate Tasks

AI analyzes your blueprint and generates development tasks by tier.

Build History

Recent 5 builds with success/failure, task count, errors, and deploy status.

Quality Gate

Automatic lint, type checking, and build verification.

Phase 6 — Test

Configure and run tests across multiple categories.

Test Types

Toggle: Unit, Integration, E2E, Component, A/B, Load, Security.

Modes

• Auto — Detects Jest/Vitest and runs automatically.
• Manual — Record Pass/Fail/Skip manually.

AI Test Generation

"Generate Tests" creates test items per category from code analysis.

Phase 7 — Docs

Select documentation types to generate.

Toggle: README, API Docs, Storybook, ADR, User Guide, Changelog. Generated after first deployment.

Phase 8 — Deploy

Configure deployment infrastructure.

Domain Provider

Cloudflare, Namecheap, GoDaddy, Route53, or None.

CDN

Cloudflare, Vercel Edge, AWS CloudFront, or None.

Phase 9 — Monitor

Monitoring and analytics setup.

Monitoring

Sentry, Datadog, or None.

Analytics

Google Analytics 4, PostHog, Mixpanel, or None.

Build Studio

AI-powered coding workspace. The agent reads your blueprint and generates production-ready code in real-time.

Interface

• Chat Panel — Communicate with the AI agent
• Code Editor — Monaco Editor with syntax highlighting
• File Explorer — Browse project files
• Terminal — Integrated xterm.js
• Preview — Live preview of your running app

AI Agent Workflow

LLM Selection

Device Lab

Test across multiple devices simultaneously. Compare iOS, Android, and desktop viewports in real-time.

Supported Devices

iOS

iPhone SE, 14/14 Pro, 15/15 Pro, 16/16 Pro and Plus/Max variants.

Android

Pixel 7–9 Pro, Galaxy S23–S25 Ultra, Z Flip/Fold 6, Galaxy A54, OnePlus 12.

Web

Desktop 1920x1080, 1440x900, 1280x720, iPad, iPad Pro 12.9", Galaxy Tab S9.

Usage

Settings

Configure API keys, LLM preferences, and account settings.

API Keys (BYOK)

Key Priority

1. Explicit selection   (manual model picker)
2. Environment vars     (ANTHROPIC_API_KEY, etc.)
3. App settings         (Settings page BYOK)
4. BlueForge credits    (default fallback)

Local AI Models

Run AI tasks on your own machine using Google Gemma 4 via Ollama. Zero cloud costs, full privacy, no internet required.

Setup

Model Catalog

Google Gemma 4 models, optimized for code generation and analysis.

Task Routing

Choose which AI tasks run on your local machine vs cloud APIs. Tasks are grouped into 9 categories. BlueForge auto-detects your downloaded models and optimizes routing automatically — if you have 26B+ models, Code and Review tasks route locally too.

Cloud-Locked Tasks

These tasks always run on cloud and cannot be routed to local models:

• Image & Vision — No local image generation models are available
• Critical — Full system refactoring and production incidents require premium reasoning capabilities
• Security — Security audits require the highest-quality models for accurate vulnerability detection

Presets

Credits & Pricing

Local model usage is always free — no credits are deducted. This applies regardless of which model you use (E2B through 31B). Only cloud-routed tasks consume credits.

Local (Gemma 4 E2B/E4B/26B/31B)   FREE  # 0 credits
Cloud (Gemini 2.0 Flash)           10    # credits per call
Cloud (Claude Sonnet 4)            20    # credits per call
Cloud (GPT-4o)                     20    # credits per call

System Requirements

AI Memory

A 3-tier memory system that prevents the AI from forgetting context — Short-term · Project State · Long-term Semantic Memory.

3-Tier Memory Architecture

Tier A — Short-term Memory

Every LLM call now carries the last 20 messages as full text in the system prompt. Before v0.7.26 only 3 messages were sent, so anything older than message 4 was instantly forgotten.

• User messages: up to 3000 characters (long GitHub PATs or deploy configs pasted at once are not truncated)
• AI responses: up to 5000 characters
• Short follow-ups like "continue": window expands to last 30 messages

Tier B — Project State Header + Context Spine

Two blocks are automatically prepended to the system prompt on every LLM call.

Project State Header (~150 tokens)

## Project State (current configuration — do not re-ask)
- GitHub: jays-visionAI/blueforge
- Deploy target: vercel
- Active model: claude-sonnet-4-6 (anthropic)

Context Spine Summary (~600 token budget)

An auto-summarised view of decisions, completed work, and recent agent activity from previous sessions. Spine read was disabled in v0.7.18 and revived in v0.7.27.

Tier C — Long-term Semantic Memory PRO+

How to activate

How it works

1. Each message you send → embedded with Gemini embedding-001 (768-dim) → stored in a local JSON file
2. Each new message → embedded → cosine-similarity scored against every past entry → top-5 picked (similarity ≥ 0.55)
3. Those 5 snippets are auto-injected into the system prompt under ## Relevant Past Context (semantic recall — Pro+)
4. The AI can then accurately quote details from messages 50+ turns ago

Storage & Cost

Privacy

• Embedding requests go directly from your machine to Google using your registered Gemini API key (never via Blueforge servers)
• Both vectors and original text live only on your local disk
• Backing up the project folder backs up memory too (.blueforge/ is included)
• Deleting the project automatically deletes its memory

Disable / Reset

• Toggle OFF in Settings → new messages stop being embedded (existing data is preserved)
• Full wipe → delete {projectDir}/.blueforge/long-term-memory.json

FAQ

CLI Reference

Run BlueForge AI agent from the terminal — Linux, macOS, CI/CD, Docker. No GUI required.

Installation

Three Modes

One-shot

blueforge "Add a login page with email/password"
blueforge -m claude-sonnet-4-20250514 "Refactor auth.ts"
blueforge -p gemini "Generate unit tests for src/utils/"

Interactive

blueforge              # Start interactive session
blueforge -p anthropic # With specific provider

HTTP Server

blueforge --serve
blueforge --serve --port 8080 --api-key my-secret-key

API Endpoints

Environment Variables

MCP Server

Connect your AI agents to BlueForge via Model Context Protocol. Access file operations, terminal, git, and project context.

Architecture

Your Agent  (LLM)
    |
MCP Client  (BlueforgeConnector)
    |  MCP Protocol (stdio / SSE)
BlueForge MCP Server
    +-- file_read / file_write / file_edit
    +-- file_delete / file_list / file_search
    +-- terminal_exec / npm_install
    +-- git_status / git_diff / git_commit
    +-- project_info

Setup

{
  "mcpServers": {
    "blueforge": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "BLUEFORGE_PROJECT_DIR": "/path/to/project"
      }
    }
  }
}

Available Tools

Security

CredentialVault (API Key Encryption)

MCP server API keys are encrypted at rest using OS-level keychain via Electron safeStorage. Keys are never stored as plaintext in config files.

[Install]
User API Key  ->  CredentialVault.store()  ->  OS Keychain (encrypted)
              ->  mcp-servers.json: { "API_KEY": "__vault__" }

[Connect]
mcp:connect   ->  retrieveCredentials()  ->  OS Keychain decrypt
              ->  process.env injection   ->  child_process.spawn()
              ->  MCP handshake           ->  connected

[Uninstall]
mcp:remove    ->  removeCredentials()   ->  OS Keychain purge

.bfx Bundle Format

Blueforge Extension (.bfx) is a self-contained bundle format for MCP servers. It eliminates npx dependencies and enables offline, one-click installation.

manifest.json

{
  "name": "my-mcp-server",
  "version": "1.0.0",
  "description": "Server description",
  "transport": "stdio",
  "command": "node",
  "entrypoint": "index.js",
  "env_keys": ["API_KEY"],
  "category": "Development"
}

Installation

Multi-Agent System

20+ specialized AI agents collaborate on complex tasks. An intelligent router selects the best agent for each request.

Master Agents

Domain Specialists

Quality & Security

Routing

Commands & Agent Skills

BlueForge provides two complementary systems for extending AI behavior: Commands (active, slash-invoked) and Agent Skills (passive, auto-injected).

Commands

Commands are slash-triggered workflows you invoke in the chat with /command-name. They provide specialized behavior for common tasks.

How to use

Built-in Command Categories

Managing Commands

Navigate to Commands in the sidebar to browse, enable, or disable commands. Commands are project-independent and available across all projects.

Agent Skills

Agent Skills are passive behavioral instructions housed in .agent/skills/ directories within your project. They are automatically injected into the AI system prompt for every LLM call, shaping how the AI writes code, reviews, and responds.

Directory structure

my-project/
  .agent/
    skills/
      clean-code/
        SKILL.md              // Main instruction file
      testing-patterns/
        SKILL.md
        scripts/
          test_runner.py      // Optional helper scripts
      frontend-design/
        SKILL.md
        examples/
          card-component.tsx  // Reference implementations

SKILL.md format

Each SKILL.md file has YAML frontmatter followed by markdown instructions.

---
name: Clean Code Standards
description: Pragmatic coding standards for concise, readable code
trigger: always_on
---

# Instructions body (markdown)

All code must follow these rules:
- Use meaningful variable names
- Keep functions under 30 lines
- No unnecessary comments
- Self-documenting code preferred
...

Frontmatter fields

How it works

Managing Agent Skills

Navigate to Agent Skills in the sidebar to view all detected skills, toggle them on/off, and see estimated token usage per skill.

Built-in Skill Categories

BlueForge's .agent/skills/ directory includes 30+ pre-built skills:

Commands vs Agent Skills

Extensions

Access the Extension Marketplace from the sidebar to browse, install, and manage extensions that add new capabilities to BlueForge.

Custom AI Rules

Control how the AI behaves across all your projects or for a specific project. BlueForge provides two rule layers: BlueforgeRule (global system rules via Settings) that always apply as a baseline, and ProjectRule.md (per-project file) that adds project-specific overrides. Both layers are active simultaneously.

Two-Tier Rule System

BlueForge uses a two-tier rule system. BlueforgeRule provides a global baseline for all projects, while ProjectRule.md lets you customize behavior for a specific project.

BlueforgeRule (Settings)

BlueforgeRule defines global system rules that apply across all projects. Managed directly in the Settings UI. Perfect for personal coding standards, naming conventions, and universal preferences.

ProjectRule.md (Per-Project)

For project-specific rules, create a ProjectRule.md file in the project root directory. When this file exists, it is applied alongside BlueforgeRule. On any conflict, ProjectRule.md takes precedence.

Directory Structure

my-project/
  ProjectRule.md      // Project-specific AI rules (overrides BlueforgeRule on conflict)
  .agent/
    skills/           // Agent Skills (Layer 14)
  src/
  package.json

Example: BlueforgeRule (Settings)

# My Global Coding Rules

## Code Style
- Use TypeScript strict mode for all files
- Prefer functional components with hooks
- Use Zustand for state management, no Redux

## Naming Conventions
- Components: PascalCase (UserCard.tsx)
- Hooks: camelCase with use prefix (useAuth.ts)
- Constants: SCREAMING_SNAKE_CASE

## Forbidden
- No `any` type usage
- No console.log in production code
- No hardcoded API URLs (use env variables)

Example: ProjectRule.md

# E-Commerce Project Rules

## Tech Stack
- Next.js 15 with App Router
- Supabase for database and auth
- Tailwind CSS v4 for styling

## Architecture
- Feature-based folder structure: src/features/{name}/
- All API calls must go through src/services/
- Use Row Level Security (RLS) on all tables

## API Design
- RESTful endpoints under /api/v1/
- Always return { data, error, meta } response shape

## Deployment
- Target: Vercel
- Preview deployments on every PR

How Priority Works

Both BlueforgeRule and ProjectRule.md are always injected into the AI's context simultaneously. When rules from different layers conflict, the higher-priority layer wins:

Comparison with Other Tools

Integrations & Workflows

BlueForge's Platform Workflow Engine (PWE) provides pre-built browser automation workflows for 56+ platforms across 14 categories. The AI Agent uses these workflows to navigate external services, extract credentials, and configure integrations automatically.

Overview

Global Services

BaaS & Database

Auth

AI

Hosting & Compute

AWS (8 Services)

Payment

Email & SMS

Messaging

Maps & SEO

DNS & SCM

Korea

Japan

Southeast Asia

Security Model

Workflows enforce a human-in-the-loop security model. Each step has an agentCanDo flag:

3-Layer Merge Strategy

Workflows are resolved in a 3-layer priority system: