frontagent
Advanced tools
FrontAgent CLI and VS Code extension for frontend AI engineering with SDD constraints, MCP-controlled execution, and RAG planning
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.
FrontAgent now supports both terminal-first and VS Code desktop workflows:
fa init, fa run, RAG commands, Skill Lab, and automation-friendly workflows directly from your terminal.Install the VS Code extension from the Marketplace by searching for FrontAgent or the extension id ceilf6.frontagent.
# 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
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.
# 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
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:
famcp, serveDo 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:
mcpServers in claude_desktop_config.json.mcpServers in your Cursor MCP config, for example .cursor/mcp.json.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": []
}
MCP mode uses auto LLM backend selection:
sampling/createMessage.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.
MCP mode keeps FrontAgent's internal safety boundary:
SecurityManager.balanced.ask decision fails closed.frontagent_init_sdd only writes SDD files inside the configured project root.FrontAgent now supports a full remote repository knowledge base flow for planning and code generation:
.frontagent/rag-cache/repo.frontagent/rag-cacheDefault knowledge source:
https://github.com/ceilf6/Lab.gitgit 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
FrontAgent now includes a local Skill Lab workflow for iterating on content skills under skills/.
# 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-design
# Benchmark current trigger behavior
fa skill benchmark frontend-design
# Benchmark trigger + behavior together
fa skill benchmark frontend-design --behavior
# Generate a candidate revision and compare it against baseline
fa skill improve frontend-design
# Improve with both trigger and behavior eval suites
fa skill improve frontend-design --behavior
# Promote a candidate after review
fa skill promote frontend-design 20260331T120000Z
The current Skill Lab flow supports two eval tracks for content skills:
You can run trigger-only (default) or trigger + behavior (--behavior) in benchmark/improve.
Environment variables:
export FRONTAGENT_RAG_SOURCE="composite" # git | openviking | composite
export FRONTAGENT_OPENVIKING_ENDPOINT="https://openviking.example.com/query"
export FRONTAGENT_OPENVIKING_API_KEY=""
export FRONTAGENT_OPENVIKING_CORPUS="wiki"
export FRONTAGENT_OPENVIKING_NAMESPACE="docs/openviking"
export FRONTAGENT_OPENVIKING_L1_ENTRY="docs/openviking/frontagent-l1.md"
export FRONTAGENT_OPENVIKING_TIMEOUT_MS="30000"
export FRONTAGENT_RAG_REPO="https://github.com/ceilf6/Lab.git"
export FRONTAGENT_RAG_BRANCH="main"
export FRONTAGENT_RAG_SYNC_ON_QUERY="false"
export FRONTAGENT_RAG_MAX_RESULTS="5"
export FRONTAGENT_RAG_KEYWORD_CANDIDATES="40"
export FRONTAGENT_RAG_SEMANTIC_CANDIDATES="40"
export FRONTAGENT_RAG_KEYWORD_WEIGHT="0.45"
export FRONTAGENT_RAG_SEMANTIC_WEIGHT="0.55"
export FRONTAGENT_RAG_QUERY_REWRITE_MAX_TOKENS="160"
export FRONTAGENT_RAG_QUERY_REWRITE_TEMPERATURE="0.1"
export FRONTAGENT_RAG_RERANKER_MODEL="jina-reranker-v2-base-multilingual"
export FRONTAGENT_RAG_RERANKER_BASE_URL="https://your-reranker-endpoint/v1"
export FRONTAGENT_RAG_RERANKER_API_KEY="sk-..."
export FRONTAGENT_RAG_RERANKER_CANDIDATE_COUNT="20"
export FRONTAGENT_RAG_RERANKER_MAX_DOCUMENT_CHARS="1800"
export FRONTAGENT_RAG_EMBEDDING_MODEL="text-embedding-3-small"
export FRONTAGENT_RAG_EMBEDDING_BASE_URL="https://api.openai.com/v1"
export FRONTAGENT_RAG_EMBEDDING_API_KEY="sk-..."
export FRONTAGENT_RAG_VECTOR_STORE_PROVIDER="weaviate"
export FRONTAGENT_RAG_WEAVIATE_URL="http://127.0.0.1:8080"
export FRONTAGENT_RAG_WEAVIATE_API_KEY=""
export FRONTAGENT_RAG_WEAVIATE_COLLECTION_PREFIX="FrontAgentRagChunk"
# Filesense lightweight repository navigation
export FRONTAGENT_FILESENSE_ENABLED="true"
export FRONTAGENT_FILESENSE_OUTPUT="summary" # summary | candidates | verbose
export FRONTAGENT_FILESENSE_WRITE_MODE="cache" # cache | workspace | none
export FRONTAGENT_FILESENSE_MAX_ENTRIES="300"
export FRONTAGENT_FILESENSE_MAX_BYTES="131072"
export FRONTAGENT_FILESENSE_TIMEOUT_MS="3000"
If provider=openai, and FRONTAGENT_RAG_EMBEDDING_BASE_URL / FRONTAGENT_RAG_EMBEDDING_API_KEY are not set, FrontAgent will reuse the LLM base-url and api-key automatically.
Main LLM sampling controls:
fa run "Explain React createElement" \
--temperature 0.2 \
--top-p 0.9
--temperature is supported.--top-p is supported through the AI SDK call settings.--top-k is exposed, but only some providers/models support it. For example, Anthropic models can use it, while OpenAI-compatible chat models may ignore it as unsupported.repetition_penalty is not exposed yet in FrontAgent because the current AI SDK/provider stack does not provide a stable cross-provider path for it.Before retrieval, FrontAgent now sends the user's original request through a separate LLM rewrite step to generate a more retrieval-friendly frontend search query. This rewrite uses the same provider/base-url/model/api-key as the main agent, but the rewritten query is only used for RAG and does not replace the user's original task.
After BM25 + embedding recall, FrontAgent will by default send the top candidate chunks to a reranker endpoint (/rerank, Jina/Cohere-compatible) for cross-encoder-style final ordering when reranker model/base-url/api-key are available. Use --disable-rag-reranker to turn it off for a run.
When FRONTAGENT_RAG_VECTOR_STORE_PROVIDER=weaviate, FrontAgent keeps BM25 in the local index.json, but semantic vectors are written to and queried from Weaviate instead of embeddings.json.
Filesense is used as a current-repository navigation provider. FrontAgent prefers filesense_navigate for structure/location/create/refactor preparation because it is budgeted and avoids full-repo persistent sync. filesense_sync_and_summarize remains available for explicit index maintenance, but is not the normal planning path.
Prebuilt cache bundle workflow:
.frontagent/rag-cache into Git# Export the current cache directory as a distributable tar.gz bundle
fa rag export
# Export to a custom path
fa rag export --output ./artifacts/frontagent-rag-cache.tar.gz
# Import from a local file
fa rag import ./artifacts/frontagent-rag-cache.tar.gz --force
# Import from a remote URL
fa rag import https://example.com/frontagent-rag-cache.tar.gz --force
┌─────────────────────────────────────────────────────────────────────┐
│ FrontAgent System │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ User Input │────▶│ Agent Core │────▶│ Output │ │
│ └─────────────┘ └──────┬──────┘ └─────────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌────────────────┐ ┌────────────┐ ┌────────────────┐ │
│ │ SDD Layer │ │ Planner │ │ Executor │ │
│ │ (Constraints) │ │ (Stage 1) │ │ (Stage 2) │ │
│ └───────┬────────┘ └─────┬──────┘ └───────┬────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ MCP Layer (Trusted Interface) │ │
│ ├──────────────┬───────────────┬──────────────────────┤ │
│ │ MCP File │ MCP Web │ MCP Shell │ │
│ └──────┬───────┴───────┬───────┴──────────┬───────────┘ │
└─────────┼───────────────┼──────────────────┼────────────────────────┘
▼ ▼ ▼
┌──────────────┐ ┌──────────┐ ┌──────────┐
│ File System │ │ Browser │ │ Shell │
│ (Project) │ │(Playwright)│ │Commands │
└──────────────┘ └──────────┘ └──────────┘
User Task
│
▼
┌──────────────────┐
│ Pre-Planning │ ← Scan project structure (NEW!)
│ File Scan │ Detect dev server port (NEW!)
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Planner (Stage1)│ ← SDD Constraints
└────────┬─────────┘ Project file list
│ Dev server port
│ Generates execution plan (with phase field)
▼
┌──────────────────────────────────────────┐
│ Executor (Stage 2) │
│ ┌────────────────────────────────┐ │
│ │ Phase 1: Analysis │ │
│ │ ├─ Step 1 ✓ │ │
│ │ ├─ Step 2 ✗ (error) │ │
│ │ └─ Error Recovery │ │
│ │ ├─ Analyze error │ │
│ │ ├─ Generate fix steps │ │
│ │ └─ Execute fix ✓ │ │
│ └────────────────────────────────┘ │
│ ┌────────────────────────────────┐ │
│ │ Phase 2: Creation │ │
│ │ ├─ Step 3 ✓ │ │
│ │ └─ Step 4 ✓ │ │
│ └────────────────────────────────┘ │
│ │
│ After each step: │
│ └─ Update Facts │
│ ├─ File system state │
│ ├─ Dependency state │
│ ├─ Module dependency graph │
│ └─ Project state │
│ │
│ Phase completion validation: │
│ └─ Check missing module references │
│ └─ Auto-generate fix steps ✓ │
└───────────────────────────────────────────┘
│
▼
Task Complete ✓
Default phase taxonomy:
Phase 1 Analysis -> Phase 2 Creation -> Phase 3 Installation -> Phase 4 Validation/Acceptance -> Phase 5 Startup -> Phase 6 Browser Validation -> Phase 7 Repository Management (git/gh)
Before generating the execution plan, FrontAgent now automatically scans the project structure to provide accurate file context to the LLM:
// Automatically executed before planning
const projectStructure = await scanProjectFiles();
// Returns: "Project files (245 files): src/App.tsx, src/components/Button.tsx, ..."
// LLM receives this context and generates more accurate file paths
Benefits:
Implementation: packages/core/src/agent.ts:217-255
FrontAgent now automatically detects the development server port from your project configuration:
// Detection sources (in order):
// 1. vite.config.ts/js: server.port field
// 2. package.json scripts: --port or -p flags
// 3. Framework defaults: Vite (5173), Next.js (3000), CRA (3000), Angular (4200)
// 4. Fallback: 5173
const devServerPort = await detectDevServerPort();
// Used in browser navigation tasks
Benefits:
Implementation: packages/core/src/agent.ts:732-793
FrontAgent uses an innovative two-stage architecture that completely solves JSON parsing errors when generating large amounts of code:
generateObject to produce Zod Schema-compliant JSON{
"summary": "Create login page",
"steps": [
{
"description": "Create Login.tsx component file",
"action": "create_file",
"params": {
"path": "src/pages/Login.tsx",
"codeDescription": "Create a React component with username, password inputs and login button"
},
"needsCodeGeneration": true
}
]
}
needsCodeGeneration: true, dynamically generate code using generateTextAdvantages:
FrontAgent implements advanced phase-based execution and automatic error recovery:
The execution plan is automatically divided into multiple phases, each focused on a specific goal:
{
"steps": [
{
"stepId": "step-1",
"phase": "Analysis Phase",
"description": "Read existing files, analyze project structure",
"action": "read_file"
},
{
"stepId": "step-2",
"phase": "Creation Phase",
"description": "Create new component files",
"action": "create_file"
},
{
"stepId": "step-3",
"phase": "Installation Phase",
"description": "Install necessary dependencies",
"action": "run_command"
},
{
"stepId": "step-4",
"phase": "Validation Phase",
"description": "Run tests to verify functionality",
"action": "run_command"
},
{
"stepId": "step-5",
"phase": "Repository Management Phase",
"description": "Commit changes, push branch, and create/update PR with gh",
"action": "run_command"
}
]
}
Advantages:
When tool execution fails, the system automatically analyzes errors and generates fix steps:
// 1. Error detected
Error: Cannot apply patch: file not found in context: src/App.tsx
// 2. LLM analyzes error
{
"canRecover": true,
"analysis": "File src/App.tsx not read into context, need to read it first",
"recoverySteps": [
{
"description": "Read src/App.tsx into context",
"action": "read_file",
"tool": "filesystem",
"params": { "path": "src/App.tsx" }
},
{
"description": "Reapply patch to src/App.tsx",
"action": "apply_patch",
"tool": "filesystem",
"params": { /* original params */ }
}
]
}
// 3. Auto-execute fix steps
// 4. Continue original flow
Features:
FrontAgent now supports a switchable execution engine:
native (default): Existing executor flow with phase DAG schedulinglanggraph: Runs phase flow through StateGraph with optional MemorySaver checkpointCLI options:
# Use native engine (default)
fa run "Add login page" --engine native
# Use LangGraph engine
fa run "Add login page" --engine langgraph
# LangGraph + checkpoint + custom recovery attempts
fa run "Add login page" --engine langgraph --langgraph-checkpoint --max-recovery-attempts 5
FrontAgent adds a dedicated skills layer in Planner to encapsulate reusable planning logic.
task.create, task.modify, task.query, task.debug, task.refactor, task.testphase.repository-management (injects git/gh workflow after acceptance)import { createAgent, type TaskPlanningSkill } from '@frontagent/core';
const agent = createAgent(config);
const customSkill: TaskPlanningSkill = {
name: 'task.security-audit',
supports: (task) => task.type === 'debug' && task.description.includes('security'),
plan: ({ stepFactory }) => [
stepFactory.createStep({
description: 'Scan for security-sensitive patterns',
action: 'search_code',
tool: 'search_code',
params: {
pattern: 'eval|innerHTML|dangerouslySetInnerHTML',
filePattern: 'src/**/*.{ts,tsx,js,jsx}',
},
}),
],
};
agent.registerTaskSkill(customSkill);
console.log(agent.getPlannerSkillSnapshot());
agent.registerExecutorActionSkill({
name: 'action.run-command.noncritical-policy',
action: 'run_command',
shouldSkipToolError: ({ errorMsg, params }) => {
if (typeof params.command === 'string' && params.command.includes('echo')) {
return true;
}
return errorMsg.includes('already exists');
},
});
console.log(agent.getExecutorSkillSnapshot());
Traditional agents use logs as context, leading to information redundancy and inaccuracy. FrontAgent uses a structured "facts" system:
Traditional approach (log-based):
Executed operation log:
1. Attempted to read src/App.tsx - failed
2. Attempted to create src/components/Button.tsx - success
3. Attempted to read src/App.tsx - success
4. Installed react-router-dom - success
...(lots of redundant info)
FrontAgent approach (facts-based):
## File System State
### Confirmed Existing Files:
- src/App.tsx
- src/components/Button.tsx
- package.json
### Confirmed Non-Existent Paths:
- src/pages/Login.tsx
## Dependency State
### Installed Packages:
react-router-dom, axios
### Missing Packages:
@types/node
## Created Modules
### component (3 modules):
- src/components/ui/Button.tsx (default export: Button)
- src/components/ui/Card.tsx (default export: Card)
- src/components/layout/Header.tsx (exports: Header, Navigation)
### page (2 modules):
- src/pages/HomePage.tsx (default export: HomePage)
- src/pages/LoginPage.tsx (default export: LoginPage)
### ⚠️ Missing Module References:
- src/pages/HomePage.tsx references non-existent module: ../components/ui/Spinner
## Project State
- Dev server: Running (port: 5173) ← Auto-detected!
- Build status: Success
## Recent Errors
- [apply_patch] Cannot apply patch: file not found in context
Advantages:
FrontAgent now implements a four-phase memory architecture that persists knowledge across task runs, so the agent no longer starts from scratch every time.
The memory system treats context as a time-phased pipeline:
ProjectFacts from the last snapshot before planning begins<projectRoot>/.frontagent/memory/
MEMORY.md # Index entrypoint (concise topic list)
topics/
project-structure.md # Filesystem layout, key modules
dependencies.md # Packages, versions, known issues
errors.md # Past error resolutions
snapshots/
facts-latest.json # Last ProjectFacts snapshot
All memory files are human-readable Markdown (inspectable, editable). Facts snapshots use JSON for efficiency.
The system prompt is now structured into three independent zones, each with its own token budget:
.frontagent/memory/MemoryStore to prevent conflictsinjectedKeys set prevents re-injecting the same memoryconst agent = createAgent({
// ...other config
memory: {
enabled: true, // default: true
preloadBudgetChars: 8000, // max chars injected at startup
recallBudgetChars: 2000, // max chars per code-gen recall
maxTopicFiles: 10, // max topic files loaded at startup
},
});
Implementation: packages/core/src/memory/
Specification Driven Development (SDD) as hard constraints for agent behavior:
# sdd.yaml
version: "1.0"
project:
name: "my-project"
type: "react-spa"
tech_stack:
framework: "react"
version: "^18.0.0"
language: "typescript"
forbidden_packages:
- "jquery"
- "lodash"
code_quality:
max_function_lines: 50
max_file_lines: 300
forbidden_patterns:
- "any"
- "// @ts-ignore"
modification_rules:
protected_files:
- "package.json"
require_approval:
- pattern: "src/api/*"
reason: "API layer changes require approval"
Provides file operation MCP tools:
read_file - Read file contentlist_directory - List directory content (supports recursion)create_file - Create new file (two-stage: generate code from description)apply_patch - Apply code patches (two-stage: generate changes from description)search_code - Search codeget_ast - Get AST analysisrollback - Rollback changesProvides terminal command execution (requires user approval):
run_command - Execute shell commands
npm install, git init, pnpm build, etc.Provides browser interaction MCP tools:
browser_navigate - Navigate to URLget_page_structure - Get page DOM structureget_accessibility_tree - Get accessibility treeget_interactive_elements - Get interactive elementsbrowser_click / browser_type / browser_scroll - Page interactionsbrowser_screenshot - Page screenshotbrowser_wait_for_selector - Wait for element availabilityMulti-layer hallucination detection:
frontagent/
├── packages/
│ ├── shared/ # Shared types and utilities
│ ├── sdd/ # SDD control layer
│ ├── mcp-file/ # File operations MCP client
│ ├── mcp-web/ # Web awareness MCP client
│ ├── mcp-shell/ # Shell commands MCP client
│ ├── hallucination-guard/ # Hallucination prevention
│ └── core/ # Agent core (two-stage architecture)
│ └── memory/ # Cross-session memory system
├── apps/
│ └── cli/ # CLI tool
├── examples/
│ ├── sdd-example.yaml # SDD config example
│ └── e-commerce-frontend/ # E-commerce frontend example
└── docs/
├── architecture.md # Architecture design
└── design.md # Original requirements
cd examples
fa run "Create an e-commerce frontend project using React + TypeScript + Vite + Tailwind CSS"
Agent will automatically:
npm install (requires user approval)fa run "Modify vite.config.ts to add path alias configuration"
Agent will:
fa run "Add user authentication feature, including login, registration, and token management"
Agent will:
fa run "Analyze and optimize homepage loading performance"
Agent will:
fa run "Add route configuration in App.tsx"
Execution process shows self-healing:
Phase 1: Analysis Phase
✓ Step 1: Read package.json
Phase 2: Creation Phase
✗ Step 2: Modify App.tsx
Error: Cannot apply patch: file not found in context
🔄 Error recovery in progress...
Analysis: App.tsx not read into context
✓ Recovery Step 1: Read src/App.tsx into context
✓ Recovery Step 2: Reapply patch to App.tsx
Phase 3: Validation Phase
✓ Step 3: Run type check
✅ Task complete! Auto-fixed 1 error
Key Features:
fa run "Implement user profile page and open PR" \
--type create \
--engine langgraph \
--langgraph-checkpoint \
--max-recovery-attempts 5
Notes:
--engine langgraph enables graph-based phase orchestration--langgraph-checkpoint enables in-memory checkpointing for the rungit/gh actions| Variable | Description | Example Value |
|---|---|---|
PROVIDER | LLM provider | openai or anthropic |
API_KEY | API key | sk-... |
MODEL | Model name | gpt-4 or claude-sonnet-4-20250514 |
BASE_URL | API endpoint | https://api.openai.com/v1 |
EXECUTION_ENGINE | Execution engine | native or langgraph |
LANGGRAPH_CHECKPOINT | Enable LangGraph checkpoint | true / false |
MAX_RECOVERY_ATTEMPTS | Max recovery attempts per phase | 3 |
export PROVIDER="openai"
export BASE_URL="https://api.openai.com/v1"
export MODEL="gpt-4"
export API_KEY="sk-..."
export PROVIDER="anthropic"
export BASE_URL="https://api.anthropic.com"
export MODEL="claude-sonnet-4-20250514"
export API_KEY="sk-ant-..."
# Development mode
pnpm dev
# Type check
pnpm typecheck
# Build
pnpm build
# Clean
pnpm clean
Welcome to contribute! Submit issues, bugs, or suggestions:
git checkout -b feature/amazing-featuregit commit -m 'Add amazing feature'git push origin feature/amazing-featureMIT
Contributions are welcome! Please feel free to submit issues, bug reports, or suggestions.
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)MIT
FAQs
FrontAgent CLI and VS Code extension for frontend AI engineering with SDD constraints, MCP-controlled execution, and RAG planning
The npm package frontagent receives a total of 20 weekly downloads. As such, frontagent popularity was classified as not popular.
We found that frontagent demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Newer packages in this compromise use native extensions and .pth loaders to execute JavaScript stealers in developer environments.
Research
Socket found 37 malicious PyPI wheels that abuse Python startup hooks to launch a Bun-powered credential stealer tied to Mini Shai-Hulud/Miasma.
Security News
RubyGems and Bundler 4.0.13 introduced an opt-in cooldown feature that delays newly published gems during dependency resolution.