Frontagent
AI agent platform for frontend engineering with SDD constraints & MCP-controlled automation. | ι’εεη«―ε·₯η¨ηδΌδΈηΊ§ AI Agent εΉ³ε°
Installation
npx frontagentAsk AI about Frontagent
Powered by Claude Β· Grounded in docs
I know everything about Frontagent. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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:
- β 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
- β 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
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
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
# 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/.
# 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:
- Trigger evals: whether the skill activates correctly.
- Behavior evals: whether the final output quality passes binary checks.
You can run trigger-only (default) or trigger + behavior (--behavior) in benchmark/improve.
Environment variables:
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"
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
--temperatureis supported.--top-pis supported through the AI SDK call settings.--top-kis 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_penaltyis 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.
Prebuilt cache bundle workflow:
- Do not commit
.frontagent/rag-cacheinto Git - Export a prebuilt cache bundle and upload it to GitHub Releases or object storage
- Other users can import the bundle locally before their first query
# 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
Architecture Overview
System Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 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 β
ββββββββββββββββ ββββββββββββ ββββββββββββ
Execution Flow
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)
Key Features
1. Pre-Planning Project Scan (NEW!)
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:
- β Accurate File Paths - LLM knows existing files and generates correct relative paths
- β Reduced Hallucination - Fewer "file not found" errors
- β Better Context - Planner understands the project structure before planning
Implementation: packages/core/src/agent.ts:217-255
2. Automatic Dev Server Port Detection (NEW!)
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:
- β Automatic Port Discovery - No manual port configuration needed
- β Framework Awareness - Recognizes different framework defaults
- β Browser Testing - Correct port used for browser validation tasks
Implementation: packages/core/src/agent.ts:732-793
3. Two-Stage Architecture
FrontAgent uses an innovative two-stage architecture that completely solves JSON parsing errors when generating large amounts of code:
Stage 1: Planner
- Input: User task + SDD constraints + project context + project file list (NEW!)
- Output: Structured execution plan (descriptions only, no code)
- Tech: Uses
generateObjectto produce Zod Schema-compliant JSON - Key: No code in JSON, avoiding escape and parsing issues
{
"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
}
]
}
Stage 2: Executor
- Input: Structured execution plan
- Process: Execute each step in the plan sequentially
- Code Generation: When encountering
needsCodeGeneration: true, dynamically generate code usinggenerateText - Tech: Use MCP tools for file operations, command execution, etc.
Advantages:
- β Completely avoid JSON parsing errors (code not in JSON)
- β Better controllability (each step validated individually)
- β Support large projects (no JSON size limit)
- β More precise code generation (based on real-time context)
4. Phase-Based Execution & Self-Healing
FrontAgent implements advanced phase-based execution and automatic error recovery:
Phase-Based Execution
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:
- π― Clear Execution Flow - Each phase has a clear objective
- π Intra-Phase Error Recovery - Errors automatically fixed within phases
- π Better Progress Tracking - Users see which phase is currently executing
- π Dependency-Aware Phase Ordering - Phase DAG scheduling reduces out-of-order skips
- π Post-Acceptance Automation - Optional repository management phase can handle git/gh flow
Tool Error Feedback Loop
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:
- π Smart Error Analysis - LLM understands error causes and finds root issues
- π οΈ Auto-Generate Fixes - No manual intervention needed
- π Common Error Patterns - Built-in handling for common errors
- β»οΈ Phase-Level Recovery - Errors fixed within phases without blocking overall flow
5. LangGraph Execution Engine (NEW!)
FrontAgent now supports a switchable execution engine:
native(default): Existing executor flow with phase DAG schedulinglanggraph: Runs phase flow throughStateGraphwith optionalMemorySavercheckpoint
CLI 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
6. Planner Skills Layer (NEW!)
FrontAgent adds a dedicated skills layer in Planner to encapsulate reusable planning logic.
- Built-in task skills:
task.create,task.modify,task.query,task.debug,task.refactor,task.test - Built-in phase skill:
phase.repository-management(injects git/gh workflow after acceptance) - Custom task skills with the same match condition override built-ins (latest registered wins)
- Executor also supports action-level skills (for params/codegen/error policy)
- Supports runtime extension via API:
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());
7. Facts-Based Context System
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:
- π Structured Information - Clear state categories (filesystem, dependencies, module graph, project state)
- π― Deduplication - Automatic deduplication using Set/Map
- π‘ Context Awareness - LLM knows which files exist/don't exist
- π Real-time Updates - Auto-update facts after each tool execution
- π Reduced Token Usage - Concise information reduces LLM input length
- π Module Tracking - Auto-parse import/export relationships for each created file
8. Cross-Session Memory System (NEW!)
FrontAgent now implements a four-phase memory architecture that persists knowledge across task runs, so the agent no longer starts from scratch every time.
Architecture
The memory system treats context as a time-phased pipeline:
- Phase 1 -- Startup Preload: Load durable memories and seed
ProjectFactsfrom the last snapshot before planning begins - Phase 2 -- Runtime Recall: Dynamically recall relevant memories during code generation based on file path, tags, and keywords
- Phase 3 -- Post-Task Persistence: Extract and persist durable learnings (created files, error resolutions, dependency changes) after each task completes
- Phase 4 -- Compaction: Deferred until multi-turn interactive mode is added
Storage Layout
<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.
Prompt Separation
The system prompt is now structured into three independent zones, each with its own token budget:
- Rules zone -- SDD constraints, behavioral instructions (immutable per task)
- Memory zone -- Durable project knowledge loaded from
.frontagent/memory/ - Context zone -- Dynamic per-task data (files, RAG results, skills, facts)
Key Design Decisions
- Single-writer pattern: All writes go through
MemoryStoreto prevent conflicts - Dedup tracking: Per-session
injectedKeysset prevents re-injecting the same memory - Budget enforcement: Configurable character limits for preload (default 8000) and per-step recall (default 2000)
- Non-blocking persistence: Memory writes run off the critical path with full error swallowing
- Backward compatible: Fresh projects with no prior memory run identically to previous behavior
Configuration
const 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/
Core Modules
@frontagent/sdd - SDD Control Layer
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"
@frontagent/mcp-file - File Operations MCP
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 changes
@frontagent/mcp-shell - Shell Command MCP
Provides terminal command execution (requires user approval):
run_command- Execute shell commands- Custom working directory support
- Timeout settings
- User approval required before execution
- Auto-distinguish warnings from errors
- Use cases:
npm install,git init,pnpm build, etc.
@frontagent/mcp-web - Web Awareness MCP
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 availability
@frontagent/hallucination-guard - Hallucination Prevention
Multi-layer hallucination detection:
- File Existence Check - Verify referenced files exist
- Import Validity Check - Verify imports are resolvable
- Syntax Validity Check - Verify code syntax is correct
- SDD Compliance Check - Verify compliance with SDD constraints
Tech Stack
- Language: TypeScript
- Runtime: Node.js 20+
- Package Manager: pnpm
- MCP SDK: @modelcontextprotocol/sdk
- Browser Automation: Playwright
- AST Analysis: ts-morph
- LLM Integration: Vercel AI SDK
Directory Structure
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
Usage Examples
Example 1: Create New Project
cd examples
fa run "Create an e-commerce frontend project using React + TypeScript + Vite + Tailwind CSS"
Agent will automatically:
- Analyze project requirements
- Generate execution plan
- Create package.json and config files
- Request to execute
npm install(requires user approval) - Generate page components and style files
Example 2: Modify Existing Files
fa run "Modify vite.config.ts to add path alias configuration"
Agent will:
- Read existing vite.config.ts
- Understand current configuration
- Generate new config code
- Apply minimal patches
Example 3: Add New Features
fa run "Add user authentication feature, including login, registration, and token management"
Agent will:
- Analyze existing project structure
- Plan files to create
- Generate auth-related components
- Create API integration code
- Update route configuration
Example 4: Performance Optimization
fa run "Analyze and optimize homepage loading performance"
Agent will:
- Read relevant component code
- Analyze performance issues
- Propose optimization solutions
- Implement code-level optimizations (lazy loading, code splitting, etc.)
Example 5: Auto Error Recovery
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:
- π― Phase-Based Execution - Clear execution phases (Analysis, Creation, Validation)
- π Auto-Fix - Detected file not read, auto-insert read step
- π Facts Tracking - System knows which files are read/unread
- β‘ No Retry Needed - One-shot completion, no manual re-runs needed
Example 6: Enable LangGraph Engine
fa run "Implement user profile page and open PR" \
--type create \
--engine langgraph \
--langgraph-checkpoint \
--max-recovery-attempts 5
Notes:
--engine langgraphenables graph-based phase orchestration--langgraph-checkpointenables in-memory checkpointing for the run- After acceptance passes, repository management phase can run
git/ghactions
Environment Variables
Required Configuration
| 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 |
OpenAI Configuration Example
export PROVIDER="openai"
export BASE_URL="https://api.openai.com/v1"
export MODEL="gpt-4"
export API_KEY="sk-..."
Anthropic Configuration Example
export PROVIDER="anthropic"
export BASE_URL="https://api.anthropic.com"
export MODEL="claude-sonnet-4-20250514"
export API_KEY="sk-ant-..."
Development
# Development mode
pnpm dev
# Type check
pnpm typecheck
# Build
pnpm build
# Clean
pnpm clean
Roadmap
Completed β
- Two-stage agent architecture (Planner + Executor)
- Phase-based execution
- Tool Error Feedback Loop (self-healing)
- Facts-based context system
- Module dependency graph
- Post-generation validation
- Path hallucination detection
- Multi-LLM provider support (OpenAI, Anthropic)
- Shell command execution (with user approval)
- Dynamic code generation (avoid JSON parsing errors)
- MCP tool integration (File, Web, Shell)
- Type auto-normalization (handle LLM output uncertainty)
- Unlimited steps (support complex tasks with many steps)
- LLM schema constraint optimization (multi-strategy auto-fix, smart retry)
- Pre-planning file scan (NEW!)
- Auto dev server port detection (NEW!)
- Dependency-aware phase DAG scheduling (NEW!)
- LangGraph execution engine (optional) (NEW!)
- Repository management phase (git/gh automation) (NEW!)
- Cross-session memory system (NEW!) -- Four-phase durable memory with structured Markdown storage, runtime recall, and prompt zone separation
In Progress π§
- Enhanced SDD constraints (finer-grained rule control)
Planned π
- Memory-driven pattern learning (auto-extract coding conventions from past tasks)
- GUI agent auto-testing (Playwright-based)
- VS Code plugin (use directly in IDE)
- Multi-agent collaboration (decompose large tasks)
- Custom MCP server support (user-defined tools)
- Code review mode (auto-check code quality)
- Incremental update mode (only modify necessary parts)
Contributing
Welcome to contribute! Submit issues, bugs, or suggestions:
- Fork the repository
- Create a new branch
git checkout -b feature/amazing-feature - Commit your changes
git commit -m 'Add amazing feature' - Push to the branch
git push origin feature/amazing-feature - Open a Pull Request
License
MIT
Contributions are welcome! Please feel free to submit issues, bug reports, or suggestions.
- Fork this repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
MIT
