FrontAgent

Enterprise-grade AI Agent System - Constrained by SDD, Powered by MCP for Controlled Perception and Execution

中文文档 | Quick Start | Architecture | Design Doc

FrontAgent is an AI Agent system designed specifically for frontend engineering, addressing core challenges faced when deploying agents in real-world engineering scenarios:

Distilled Planner Model: FrontAgent's Planner stage has been distilled into a standalone small model frontagent-planner-7B-lora. Load the LoRA adapter on top of Qwen2.5-Coder-7B to generate frontend execution plans directly, without calling large LLM APIs. The training workflow, prompts, evaluation scripts, and Hugging Face release metadata live in models/frontagent-planner.

• ✅ Two-Stage Architecture - Separate planning and execution to avoid JSON parsing errors and enable dynamic code generation
• ✅ Phase-Based Execution - Steps grouped by phases with error recovery within each phase
• ✅ Self-Healing - Tool Error Feedback Loop automatically analyzes errors and generates fix steps
• ✅ Facts Memory - Structured facts-based context system for precise project state tracking
• ✅ Module Dependency Tracking - Automatic import/export parsing to detect path hallucinations
• ✅ Hallucination Prevention - Multi-layer hallucination detection and interception
• ✅ SDD Constraints - Specification Driven Development as hard constraints for agent behavior
• ✅ MCP Protocol - Controlled tool invocation via Model Context Protocol
• ✅ Minimal Changes - Patch-based code modifications with rollback support
• ✅ Web Awareness - Understand page structure through browser MCP
• ✅ Shell Integration - Terminal command execution (requires user approval)
• ✅ Pre-Planning Scan - Scan project structure before planning to generate accurate file paths
• ✅ Auto Port Detection - Automatically detect dev server ports from config files
• ✅ Remote Hybrid RAG - Full-repository indexing with submodule exclusion, combining BM25 keyword search and embedding-based semantic search
• ✅ LangGraph Engine (Optional) - Switchable graph-based execution engine with optional checkpoints
• ✅ Planner Skills Layer - Reusable planning skills for task decomposition and phase injection
• ✅ Distilled Planner Assets - Repository-native training, evaluation, and release assets for the Planner LoRA model
• ✅ Skill Lab - Benchmark, improve, and promote content skills with local eval suites
• ✅ Repository Management Phase - Auto git/gh workflow after acceptance (commit, push, PR)
• ✅ Cross-Session Memory - Four-phase memory system (preload, runtime recall, post-task persistence, structured storage) that persists project facts, error resolutions, and dependency state across runs

Two Ways to Use FrontAgent

FrontAgent now supports both terminal-first and VS Code desktop workflows:

• CLI: use fa init, fa run, RAG commands, Skill Lab, and automation-friendly workflows directly from your terminal.
• VS Code Extension: use the FrontAgent sidebar task console to run tasks, attach the current file or selection, provide a browser URL, review phase/step progress, approve sensitive actions, initialize/validate SDD, and open run logs from inside VS Code.

Install the VS Code extension from the Marketplace by searching for FrontAgent or the extension id ceilf6.frontagent.

CLI Quick Start

# 1. Install globally via npm
npm install -g frontagent
# or using pnpm
pnpm add -g frontagent
# or using yarn
yarn global add frontagent

# 2. Configure LLM (supports OpenAI and Anthropic)
# OpenAI config
export PROVIDER="openai"
export BASE_URL="https://api.openai.com/v1"
export MODEL="gpt-4"
export API_KEY="sk-..."

# Or Anthropic config
export PROVIDER="anthropic"
export BASE_URL="https://api.anthropic.com"
export MODEL="claude-sonnet-4-20250514"
export API_KEY="sk-ant-..."

# 3. Navigate to your project directory and initialize SDD
cd your-project
fa init

# 4. Let AI help you complete tasks
fa run "Create a user login page"
fa run "Optimize homepage loading performance"
fa run "Add dark mode support"
# Use LangGraph engine + checkpoint (optional)
fa run "Add route guards and open a PR" --engine langgraph --langgraph-checkpoint

MCP Server

FrontAgent can run as a local stdio MCP Server for MCP hosts such as Claude Desktop, Cursor, Codex, and other clients that can launch a command-based MCP server.

MCP mode exposes FrontAgent's upper-level agent capabilities only. It does not expose raw internal tools such as read_file, apply_patch, run_command, browser tools, or rag_query directly to the external host.

Start the Server

# Use the installed CLI
fa mcp serve

# Or run from a source checkout after pnpm build
node /absolute/path/to/FrontAgent-app/apps/cli/dist/index.js \
  mcp serve

By default, FrontAgent resolves the project root from the MCP host's workspace roots when the host exposes exactly one file root. If host roots are unavailable, it falls back to the MCP server process current working directory.

Use --project-root only when you want to pin the server to a specific project, or when the host exposes multiple workspace roots and FrontAgent cannot choose safely:

fa mcp serve --project-root /absolute/path/to/your-project

One MCP server process is bound to one resolved project root.

Useful server options:

fa mcp serve \
  --security-mode balanced \
  --rag-repo https://github.com/ceilf6/Lab.git \
  --rag-branch main

Host Configuration

Most MCP hosts use the same mcpServers shape. Start with the simple config:

{
  "mcpServers": {
    "frontagent": {
      "command": "fa",
      "args": [
        "mcp",
        "serve"
      ]
    }
  }
}

If your host UI has separate fields, use:

• Command: fa
• Args: mcp, serve

Do not put fa mcp serve into the command field as one string.

If the host reports command "fa" not found or env: node: No such file or directory, the GUI host probably does not inherit your terminal shell PATH. Then use absolute paths:

which node
which fa

{
  "mcpServers": {
    "frontagent": {
      "command": "/opt/homebrew/bin/node",
      "args": [
        "/opt/homebrew/bin/fa",
        "mcp",
        "serve"
      ]
    }
  }
}

If you are using a source checkout instead of a globally linked package, point node at the built CLI file after pnpm build:

{
  "mcpServers": {
    "frontagent": {
      "command": "/opt/homebrew/bin/node",
      "args": [
        "/absolute/path/to/FrontAgent-app/apps/cli/dist/index.js",
        "mcp",
        "serve"
      ]
    }
  }
}

For direct LLM fallback, pass environment variables through the host config:

{
  "mcpServers": {
    "frontagent": {
      "command": "fa",
      "args": [
        "mcp",
        "serve"
      ],
      "env": {
        "PROVIDER": "openai",
        "BASE_URL": "https://api.openai.com/v1",
        "MODEL": "gpt-4",
        "API_KEY": "sk-..."
      }
    }
  }
}

Examples of where to put the config:

• Claude Desktop: add the server under mcpServers in claude_desktop_config.json.
• Cursor: add the server under mcpServers in your Cursor MCP config, for example .cursor/mcp.json.
• Codex or other MCP hosts: use the same command, args, and env values in the host's MCP server configuration surface.

Exposed MCP Tools

FrontAgent exposes six MCP tools:

• frontagent_status: returns project root, SDD status, visible skills, LLM backend status, RAG status, and run-log directory.
• frontagent_run_task: runs a full FrontAgent task. Inputs include task, type, files, url, sddPath, and securityMode.
• frontagent_plan_task: generates a FrontAgent execution plan without executing tools or writing files.
• frontagent_validate_sdd: validates the project SDD file.
• frontagent_list_skills: lists visible content skills.
• frontagent_init_sdd: creates an SDD template. Existing files are not overwritten unless force=true.

frontagent_run_task returns structured JSON text with:

{
  "success": true,
  "taskId": "task_...",
  "output": "...",
  "error": null,
  "duration": 1234,
  "runLogPath": "/absolute/path/.frontagent/runs/...",
  "executedStepsSummary": [],
  "securityDecisions": []
}

LLM Backend Behavior

MCP mode uses auto LLM backend selection:

1. If the host supports MCP Sampling, FrontAgent asks the host model through sampling/createMessage.
2. If Sampling is unsupported or unavailable, FrontAgent falls back to direct LLM configuration.

Direct fallback uses the same environment variables and flags as fa run:

export PROVIDER="openai"
export BASE_URL="https://api.openai.com/v1"
export MODEL="gpt-4"
export API_KEY="sk-..."

Read-only tools such as frontagent_status, frontagent_list_skills, frontagent_validate_sdd, and frontagent_init_sdd do not require LLM configuration. frontagent_run_task and frontagent_plan_task require either host Sampling support or a valid direct LLM fallback.

Security Model

MCP mode keeps FrontAgent's internal safety boundary:

• External MCP hosts cannot directly call internal file, shell, browser, or RAG tools.
• Internal file writes, shell commands, browser actions, and other side effects still go through SecurityManager.
• The default security mode is balanced.
• Because stdio MCP does not provide FrontAgent's interactive approval UI, any action that requires an ask decision fails closed.
• frontagent_init_sdd only writes SDD files inside the configured project root.

Remote RAG

FrontAgent now supports a full remote repository knowledge base flow for planning and code generation:

• It syncs the remote repository into .frontagent/rag-cache/repo
• It indexes the full repository by chunk, and automatically excludes Git submodule paths
• It runs BM25 keyword retrieval and embedding-based semantic retrieval in parallel
• It applies metadata filters to each candidate list, then fuses the ranked results
• Built indexes and embedding vectors are cached under .frontagent/rag-cache

Default knowledge source:

• Repository: https://github.com/ceilf6/Lab.git
• Source mode: git by default; when FRONTAGENT_OPENVIKING_ENDPOINT is configured FrontAgent defaults to composite (OpenViking first, Git RAG fallback)

CLI options:

fa run "Explain React setState behavior" \
  --provider openai \
  --base-url https://yunwu.ai/v1 \
  --api-key YOUR_TOKEN \
  --rag-repo https://github.com/ceilf6/Lab.git \
  --rag-branch main \
  --rag-keyword-candidates 40 \
  --rag-semantic-candidates 40 \
  --rag-keyword-weight 0.45 \
  --rag-semantic-weight 0.55

# When provider=openai, RAG embeddings inherit the same base-url/api-key by default.
# Override them only if your embedding endpoint is different.
fa run "Explain React setState behavior" \
  --provider openai \
  --base-url https://yunwu.ai/v1 \
  --api-key YOUR_TOKEN \
  --rag-embedding-model text-embedding-3-small

# Use Weaviate as the semantic vector store (BM25 stays local)
fa run "Explain React setState behavior" \
  --provider openai \
  --base-url https://yunwu.ai/v1 \
  --api-key YOUR_TOKEN \
  --rag-embedding-model text-embedding-3-small \
  --rag-vector-store-provider weaviate \
  --rag-weaviate-url http://127.0.0.1:8080 \
  --rag-weaviate-collection-prefix FrontAgentRagChunk

# Use OpenViking Wiki as the primary knowledge provider, with Git RAG fallback
fa run "Where is FrontAgent RAG implemented?" \
  --rag-source composite \
  --open-viking-endpoint https://openviking.example.com/query \
  --open-viking-corpus wiki \
  --open-viking-namespace docs/openviking \
  --open-viking-l1-entry docs/openviking/frontagent-l1.md

# Require OpenViking only and disable Git fallback
fa run "Where is FrontAgent RAG implemented?" \
  --rag-source openviking \
  --open-viking-endpoint https://openviking.example.com/query \
  --disable-open-viking-fallback

# Disable LLM query rewrite before retrieval
fa run "How to build a custom selector" \
  --disable-rag-query-rewrite

# Cross-encoder reranking is enabled by default after BM25 + embedding candidate retrieval
fa run "Explain React setState behavior" \
  --provider openai \
  --base-url https://yunwu.ai/v1 \
  --api-key YOUR_TOKEN \
  --rag-embedding-model text-embedding-3-small \
  --rag-reranker-model jina-reranker-v2-base-multilingual \
  --rag-reranker-base-url https://your-reranker-endpoint/v1

# Disable reranking for a run
fa run "Explain React setState behavior" \
  --disable-rag-reranker

# Disable semantic retrieval and use BM25 only
fa run "Explain React setState behavior" \
  --disable-rag-semantic

# Disable remote RAG for a run
fa run "Create a page" --disable-rag

# Force a remote git sync before this query; by default FrontAgent reuses the local cache
fa run "Explain React setState behavior" --rag-sync-on-query

Skill Lab

FrontAgent now includes a local Skill Lab workflow for iterating on content skills under skills/.

```bash

List visible content skills

fa skill list

Scaffold a new content skill

fa skill scaffold pricing-audit

Generate starter trigger evals for a skill

fa skill init-evals frontend-design

Generate starter behavior evals (binary checks for output quality)

fa skill init-behavior-evals frontend