Skip to content
Back to search

FrontAgent

Frontend AI coding agent platform with CLI, VS Code extension, desktop app, MCP server, RAG planning, Skills, SDD guardrails, browser automation, and LoRA planner models | 面向前端工程的 AI Agent 平台,支持 CLI、VS Code 插件、桌面端、MCP 服务、RAG、Skills、SDD、浏览器自动化与 LoRA 规划模型

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ceilf6/FrontAgent with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ceilf6/FrontAgent'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ceilf6--frontagent/badge.svg)](/listings/ceilf6--frontagent)

HTML

<a href="/listings/ceilf6--frontagent"><img src="/api/listings/ceilf6--frontagent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,374 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # FrontAgent
  2. <div align="center">
  3. <img src="./assets/branding/icon.png" alt="FrontAgent Logo" width="200"/>
  4. </div>
  5. [![npm version](https://badge.fury.io/js/frontagent.svg)](https://www.npmjs.com/package/frontagent)
  6. [![npm total downloads](https://img.shields.io/npm/dt/frontagent)](https://www.npmjs.com/package/frontagent)
  7. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  8. [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
  9. > Enterprise-grade frontend AI coding agent and MCP-powered automation system - constrained by Specification Driven Development (SDD) for controlled planning, code generation, browser-aware execution, and repository workflows
  10. [中文文档](docs/README-CN.md) | [Quick Start](docs/QUICKSTART.md) | [Architecture](docs/architecture.md) | [Design Doc](docs/design.md)
  11. FrontAgent is an open-source AI coding agent for frontend engineering. It helps teams build, modify, validate, and ship web applications through an agentic CLI, VS Code extension, desktop app, local MCP server, RAG planning, browser-aware automation, and SDD guardrails.
  12. > **Distilled Planner Models**: FrontAgent's Planner stage has been distilled into Hugging Face planner assets collected under [FrontAgent: Frontend Engineering Agent](https://hf.co/collections/ceilf6/frontagent-frontend-engineering-agent). Load the published adapters on their supported Qwen Coder base models 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](models/frontagent-planner).
  13. Use FrontAgent when you need a frontend AI agent that can:
  14. - Generate and refactor React, TypeScript, Vite, Tailwind CSS, and modern web UI code from structured execution plans.
  15. - Run as an AI agent CLI, VS Code AI extension, desktop agent app, or stdio MCP server for Claude Desktop, Cursor, Codex, and other MCP hosts.
  16. - Combine repository-aware RAG, Filesense navigation, facts memory, and module dependency tracking to reduce path hallucinations.
  17. - Execute browser-aware validation, page inspection, shell commands, and git/gh repository workflows behind explicit safety controls.
  18. - Enforce Specification Driven Development (SDD), minimal patches, self-healing error recovery, and quality gates for production frontend teams.
  19. - Use distilled Qwen Coder planner models from Hugging Face for local or lower-cost frontend execution planning.
  20. - ✅ **Two-Stage Architecture** - Separate planning and execution to avoid JSON parsing errors and enable dynamic code generation
  21. - ✅ **Phase-Based Execution** - Steps grouped by phases with error recovery within each phase
  22. - ✅ **Self-Healing** - Tool Error Feedback Loop automatically analyzes errors and generates fix steps
  23. - ✅ **Facts Memory** - Structured facts-based context system for precise project state tracking
  24. - ✅ **Module Dependency Tracking** - Automatic import/export parsing to detect path hallucinations
  25. - ✅ **Hallucination Prevention** - Multi-layer hallucination detection and interception
  26. - ✅ **SDD Constraints** - Specification Driven Development as hard constraints for agent behavior
  27. - ✅ **MCP Protocol** - Controlled tool invocation via Model Context Protocol
  28. - ✅ **Minimal Changes** - Patch-based code modifications with rollback support
  29. - ✅ **Web Awareness** - Understand page structure through browser MCP
  30. - ✅ **Shell Integration** - Terminal command execution (requires user approval)
  31. - ✅ **Pre-Planning Scan** - Scan project structure before planning to generate accurate file paths
  32. - ✅ **Auto Port Detection** - Automatically detect dev server ports from config files
  33. - ✅ **Remote Hybrid RAG** - Full-repository indexing with submodule exclusion, combining BM25 keyword search and embedding-based semantic search
  34. - ✅ **Filesense Navigation** - Budgeted current-repository navigation with generated schemas and notes
  35. - ✅ **LangGraph Engine (Optional)** - Switchable graph-based execution engine with optional checkpoints
  36. - ✅ **Planner Skills Layer** - Reusable planning skills for task decomposition and phase injection
  37. - ✅ **Distilled Planner Assets** - Repository-native training, evaluation, and release assets for the Hugging Face Planner model collection
  38. - ✅ **Skill Lab** - Benchmark, improve, and promote content skills with local eval suites
  39. - ✅ **VS Code Sidebar** - Marketplace extension with task runs, SDD helpers, secure settings, and run logs
  40. - ✅ **OSS Harness** - Local contract, quality, GitNexus, and workflow gates for maintainer-friendly changes
  41. - ✅ **Repository Management Phase** - Auto git/gh workflow after acceptance (commit, push, PR)
  42. - ✅ **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
  43. ## Current Release Snapshot
  44. The repository is currently aligned on `frontagent@2.2.0` for both the npm CLI package and the VS Code extension.
  45. - Runtime requirements: Node.js `>=20.0.0`; VS Code extension engine `^1.120.0`.
  46. - Build output: `pnpm build` builds the monorepo, bundles the CLI, syncs the VS Code version, and packages `apps/vscode/frontagent-2.2.0.vsix`.
  47. - Quality gates: `pnpm quality:predev`, `pnpm quality:precommit`, `pnpm quality:ci`, and `pnpm quality:local` combine contract checks, linting, typechecking, tests, workflow tests, and build verification.
  48. - v2.2.0 focus: the Electron desktop client, headless non-interactive CLI mode, session resume, lifecycle hooks, declarative permission rules, context zone budgets, the mcp-web-fetch adapter, and CLI/guard correctness fixes.
  49. ## Three Ways to Use FrontAgent
  50. FrontAgent supports terminal, VS Code, and standalone desktop workflows:
  51. - **CLI**: use `fa init`, `fa run`, RAG commands, Skill Lab, and automation-friendly workflows directly from your terminal.
  52. - **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.
  53. - **Desktop App**: a standalone Electron GUI (`apps/desktop`) that reuses the same Node runtime spine — a Task Console for launching tasks, watching live phase/step telemetry, and approving sensitive actions, plus a Settings panel for the LLM provider/model.
  54. Install the VS Code extension from the Marketplace by searching for `FrontAgent` or the extension id `ceilf6.frontagent`.
  55. #### Endpoint trust in the VS Code extension
  56. `frontagent.provider`, `frontagent.model`, and `frontagent.baseUrl` select the host that receives your API key and task context, so the extension treats them as user-scoped configuration. A repository may propose them through its own `.vscode/settings.json`, but FrontAgent withholds a workspace-supplied endpoint until you confirm that exact provider/model/base URL for that workspace folder, re-asks whenever the repository changes it, and ignores it entirely when the workspace is not trusted. `frontagent.apiKey` is `machine`-scoped and is read only from User Settings. See [`apps/vscode/README.md`](apps/vscode/README.md) for details and the reset command.
  57. ### Desktop App
  58. The desktop client is a sandboxed Electron window wired to the real runtime (`window.frontagent` → IPC → `runFrontAgentTask`); it persists settings under your OS user-data directory and degrades gracefully if the runtime is unavailable.
  59. - **Download**: grab the unsigned per-platform archive `frontagent-desktop-${version}-${os}-${arch}.zip` from the [GitHub Releases](https://github.com/FrontAgent/FrontAgent/releases) page (published automatically for each `v*` tag), unzip, and launch the `frontagent` executable. The LLM API key is read from the environment (`PROVIDER_API_KEY` / `API_KEY`); set provider/model/base URL in the in-app Settings panel.
  60. - **Build locally**: `pnpm --filter @frontagent/desktop package` produces an unpacked app under `apps/desktop/release/`, and `pnpm --filter @frontagent/desktop dev` runs it against the Vite dev server. The `release` script (`pnpm --filter @frontagent/desktop run release`) produces the distributable zip.
  61. > Desktop archives are currently unsigned; code signing, notarization, and native installers (dmg/nsis/AppImage) are planned follow-ups.
  62. ## CLI Quick Start
  63. ```bash
  64. # 1. Install globally via npm
  65. npm install -g frontagent
  66. # or using pnpm
  67. pnpm add -g frontagent
  68. # or using yarn
  69. yarn global add frontagent
  70. # 2. Configure LLM (supports OpenAI and Anthropic)
  71. # OpenAI config
  72. export PROVIDER="openai"
  73. export BASE_URL="https://api.openai.com/v1"
  74. export MODEL="gpt-4"
  75. export API_KEY="sk-..."
  76. # Or Anthropic config
  77. export PROVIDER="anthropic"
  78. export BASE_URL="https://api.anthropic.com"
  79. export MODEL="claude-sonnet-4-20250514"
  80. export API_KEY="sk-ant-..."
  81. # 3. Navigate to your project directory and initialize SDD
  82. cd your-project
  83. fa init
  84. # 4. Let AI help you complete tasks
  85. fa run "Create a user login page"
  86. fa run "Optimize homepage loading performance"
  87. fa run "Add dark mode support"
  88. # Use LangGraph engine + checkpoint (optional)
  89. fa run "Add route guards and open a PR" --engine langgraph --langgraph-checkpoint
  90. ```
  91. ## MCP Server
  92. 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.
  93. 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.
  94. ### Start the Server
  95. ```bash
  96. # Use the installed CLI
  97. fa mcp serve
  98. # Or run from a source checkout after pnpm build
  99. node /absolute/path/to/FrontAgent-app/apps/cli/dist/index.js \
  100. mcp serve
  101. ```
  102. 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.
  103. 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:
  104. ```bash
  105. fa mcp serve --project-root /absolute/path/to/your-project
  106. ```
  107. One MCP server process is bound to one resolved project root.
  108. Useful server options:
  109. ```bash
  110. fa mcp serve \
  111. --engine native \
  112. --security-mode balanced \
  113. --rag-repo https://github.com/ceilf6/Lab.git \
  114. --rag-branch main \
  115. --filesense-enabled true \
  116. --log-file .frontagent/runs/mcp-server.log
  117. ```
  118. ### Host Configuration
  119. Most MCP hosts use the same `mcpServers` shape. Start with the simple config:
  120. ```json
  121. {
  122. "mcpServers": {
  123. "frontagent": {
  124. "command": "fa",
  125. "args": ["mcp", "serve"]
  126. }
  127. }
  128. }
  129. ```
  130. If your host UI has separate fields, use:
  131. - Command: `fa`
  132. - Args: `mcp`, `serve`
  133. Do not put `fa mcp serve` into the command field as one string.
  134. 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:
  135. ```bash
  136. which node
  137. which fa
  138. ```
  139. ```json
  140. {
  141. "mcpServers": {
  142. "frontagent": {
  143. "command": "/opt/homebrew/bin/node",
  144. "args": ["/opt/homebrew/bin/fa", "mcp", "serve"]
  145. }
  146. }
  147. }
  148. ```
  149. If you are using a source checkout instead of a globally linked package, point `node` at the built CLI file after `pnpm build`:
  150. ```json
  151. {
  152. "mcpServers": {
  153. "frontagent": {
  154. "command": "/opt/homebrew/bin/node",
  155. "args": ["/absolute/path/to/FrontAgent-app/apps/cli/dist/index.js", "mcp", "serve"]
  156. }
  157. }
  158. }
  159. ```
  160. For direct LLM fallback, pass environment variables through the host config:
  161. ```json
  162. {
  163. "mcpServers": {
  164. "frontagent": {
  165. "command": "fa",
  166. "args": ["mcp", "serve"],
  167. "env": {
  168. "PROVIDER": "openai",
  169. "BASE_URL": "https://api.openai.com/v1",
  170. "MODEL": "gpt-4",
  171. "API_KEY": "sk-..."
  172. }
  173. }
  174. }
  175. }
  176. ```
  177. Examples of where to put the config:
  178. - Claude Desktop: add the server under `mcpServers` in `claude_desktop_config.json`.
  179. - Cursor: add the server under `mcpServers` in your Cursor MCP config, for example `.cursor/mcp.json`.
  180. - Codex or other MCP hosts: use the same command, args, and env values in the host's MCP server configuration surface.
  181. ### Exposed MCP Tools
  182. FrontAgent exposes six MCP tools:
  183. - `frontagent_status`: returns project root, SDD status, visible skills, LLM backend status, RAG status, and run-log directory.
  184. - `frontagent_run_task`: runs a full FrontAgent task. Inputs include `task`, `type`, `files`, `url`, `sddPath`, and `securityMode`.
  185. - `frontagent_plan_task`: generates a FrontAgent execution plan without executing tools or writing files.
  186. - `frontagent_validate_sdd`: validates the project SDD file.
  187. - `frontagent_list_skills`: lists visible content skills.
  188. - `frontagent_init_sdd`: creates an SDD template. Existing files are not overwritten unless `force=true`.
  189. `frontagent_run_task` returns structured JSON text with:
  190. ```json
  191. {
  192. "success": true,
  193. "taskId": "task_...",
  194. "output": "...",
  195. "error": null,
  196. "duration": 1234,
  197. "runLogPath": "/absolute/path/.frontagent/runs/...",
  198. "executedStepsSummary": [],
  199. "securityDecisions": []
  200. }
  201. ```
  202. ### LLM Backend Behavior
  203. MCP mode uses `auto` LLM backend selection:
  204. 1. If the host supports MCP Sampling, FrontAgent asks the host model through `sampling/createMessage`.
  205. 2. If Sampling is unsupported or unavailable, FrontAgent falls back to direct LLM configuration.
  206. Direct fallback uses the same environment variables and flags as `fa run`:
  207. ```bash
  208. export PROVIDER="openai"
  209. export BASE_URL="https://api.openai.com/v1"
  210. export MODEL="gpt-4"
  211. export API_KEY="sk-..."
  212. ```
  213. 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.
  214. ### Security Model
  215. MCP mode keeps FrontAgent's internal safety boundary:
  216. - External MCP hosts cannot directly call internal file, shell, browser, or RAG tools.
  217. - Internal file writes, shell commands, browser actions, and other side effects still go through `SecurityManager`.
  218. - The default security mode is `balanced`.
  219. - Because stdio MCP does not provide FrontAgent's interactive approval UI, any action that requires an `ask` decision fails closed.
  220. - `frontagent_init_sdd` only writes SDD files inside the configured project root.
  221. ## Remote RAG
  222. FrontAgent now supports a full remote repository knowledge base flow for planning and code generation:
  223. - It syncs the remote repository into `.frontagent/rag-cache/repo`
  224. - It indexes the full repository by chunk, and automatically excludes Git submodule paths
  225. - It runs BM25 keyword retrieval and embedding-based semantic retrieval in parallel
  226. - It applies metadata filters to each candidate list, then fuses the ranked results
  227. - Built indexes and embedding vectors are cached under `.frontagent/rag-cache`
  228. Default knowledge source:
  229. - Repository: `https://github.com/ceilf6/Lab.git`
  230. - Source mode: `git` by default; when `FRONTAGENT_OPENVIKING_ENDPOINT` is configured FrontAgent defaults to `composite` (`OpenViking` first, Git RAG fallback)
  231. CLI options:
  232. ```bash
  233. fa run "Explain React setState behavior" \
  234. --provider openai \
  235. --base-url https://yunwu.ai/v1 \
  236. --api-key YOUR_TOKEN \
  237. --rag-repo https://github.com/ceilf6/Lab.git \
  238. --rag-branch main \
  239. --rag-keyword-candidates 40 \
  240. --rag-semantic-candidates 40 \
  241. --rag-keyword-weight 0.45 \
  242. --rag-semantic-weight 0.55
  243. # When provider=openai, RAG embeddings inherit the same base-url/api-key by default.
  244. # Override them only if your embedding endpoint is different.
  245. fa run "Explain React setState behavior" \
  246. --provider openai \
  247. --base-url https://yunwu.ai/v1 \
  248. --api-key YOUR_TOKEN \
  249. --rag-embedding-model text-embedding-3-small \
  250. --rag-embedding-batch-size 32 \
  251. --rag-embedding-timeout-ms 30000
  252. # Use Weaviate as the semantic vector store (BM25 stays local)
  253. fa run "Explain React setState behavior" \
  254. --provider openai \
  255. --base-url https://yunwu.ai/v1 \
  256. --api-key YOUR_TOKEN \
  257. --rag-embedding-model text-embedding-3-small \
  258. --rag-vector-store-provider weaviate \
  259. --rag-weaviate-url http://127.0.0.1:8080 \
  260. --rag-weaviate-collection-prefix FrontAgentRagChunk \
  261. --rag-weaviate-batch-size 64 \
  262. --rag-weaviate-timeout-ms 30000
  263. # Use OpenViking Wiki as the primary knowledge provider, with Git RAG fallback
  264. fa run "Where is FrontAgent RAG implemented?" \
  265. --rag-source composite \
  266. --open-viking-endpoint https://openviking.example.com/query \
  267. --open-viking-corpus wiki \
  268. --open-viking-namespace docs/openviking \
  269. --open-viking-l1-entry docs/openviking/frontagent-l1.md
  270. # Require OpenViking only and disable Git fallback
  271. fa run "Where is FrontAgent RAG implemented?" \
  272. --rag-source openviking \
  273. --open-viking-endpoint https://openviking.example.com/query \
  274. --disable-open-viking-fallback
  275. # Disable LLM query rewrite before retrieval
  276. fa run "How to build a custom selector" \
  277. --disable-rag-query-rewrite
  278. # Cross-encoder reranking is enabled by default after BM25 + embedding candidate retrieval
  279. fa run "Explain React setState behavior" \
  280. --provider openai \
  281. --base-url https://yunwu.ai/v1 \
  282. --api-key YOUR_TOKEN \
  283. --rag-embedding-model text-embedding-3-small \
  284. --rag-reranker-model jina-reranker-v2-base-multilingual \
  285. --rag-reranker-base-url https://your-reranker-endpoint/v1 \
  286. --rag-reranker-timeout-ms 30000
  287. # Disable reranking for a run
  288. fa run "Explain React setState behavior" \
  289. --disable-rag-reranker
  290. # Disable semantic retrieval and use BM25 only
  291. fa run "Explain React setState behavior" \
  292. --disable-rag-semantic
  293. # Disable remote RAG for a run
  294. fa run "Create a page" --disable-rag
  295. # Force a remote git sync before this query; by default FrontAgent reuses the local cache
  296. fa run "Explain React setState behavior" --rag-sync-on-query
  297. ```
  298. ## Skill Lab
  299. FrontAgent now includes a local Skill Lab workflow for iterating on content skills under `skills/`.
  300. ```bash
  301. # List visible content skills
  302. fa skill list
  303. # Scaffold a new content skill
  304. fa skill scaffold pricing-audit
  305. # Generate starter trigger evals for a skill
  306. fa skill init-evals frontend-design
  307. # Generate starter behavior evals (binary checks for output quality)
  308. fa skill init-behavior-evals frontend-design
  309. # Benchmark current trigger behavior
  310. fa skill benchmark frontend-design
  311. # Benchmark trigger + behavior together
  312. fa skill benchmark frontend-design --behavior
  313. # Generate a candidate revision and compare it against baseline
  314. fa skill improve frontend-design
  315. # Improve with both trigger and behavior eval suites
  316. fa skill improve frontend-design --behavior
  317. # Promote a candidate after review
  318. fa skill promote frontend-design 20260331T120000Z
  319. ```
  320. The current Skill Lab flow supports two eval tracks for content skills:
  321. - Trigger evals: whether the skill activates correctly.
  322. - Behavior evals: whether the final output quality passes binary checks.
  323. You can run trigger-only (default) or trigger + behavior (`--behavior`) in benchmark/improve.
  324. Environment variables:
  325. ```bash
  326. export FRONTAGENT_RAG_SOURCE="composite" # git | openviking | composite
  327. export FRONTAGENT_OPENVIKING_ENDPOINT="https://openviking.example.com/query"
  328. export FRONTAGENT_OPENVIKING_API_KEY=""
  329. export FRONTAGENT_OPENVIKING_CORPUS="wiki"
  330. export FRONTAGENT_OPENVIKING_NAMESPACE="docs/openviking"
  331. export FRONTAGENT_OPENVIKING_L1_ENTRY="docs/openviking/frontagent-l1.md"
  332. export FRONTAGENT_OPENVIKING_TIMEOUT_MS="30000"
  333. export FRONTAGENT_RAG_REPO="https://github.com/ceilf6/Lab.git"
  334. export FRONTAGENT_RAG_BRANCH="main"
  335. export FRONTAGENT_RAG_SYNC_ON_QUERY="false"
  336. export FRONTAGENT_RAG_MAX_RESULTS="5"
  337. export FRONTAGENT_RAG_KEYWORD_CANDIDATES="40"
  338. export FRONTAGENT_RAG_SEMANTIC_CANDIDATES="40"
  339. export FRONTAGENT_RAG_KEYWORD_WEIGHT="0.45"
  340. export FRONTAGENT_RAG_SEMANTIC_WEIGHT="0.55"
  341. export FRONTAGENT_RAG_QUERY_REWRITE_MAX_TOKENS="160"
  342. export FRONTAGENT_RAG_QUERY_REWRITE_TEMPERATURE="0.1"
  343. export FRONTAGENT_RAG_RERANKER_MODEL="jina-reranker-v2-base-multilingual"
  344. export FRONTAGENT_RAG_RERANKER_BASE_URL="https://your-reranker-endpoint/v1"
  345. export FRONTAGENT_RAG_RERANKER_API_KEY="sk-..."
  346. export FRONTAGENT_RAG_RERANKER_CANDIDATE_COUNT="20"
  347. export FRONTAGENT_RAG_RERANKER_MAX_DOCUMENT_CHARS="1800"
  348. export FRONTAGENT_RAG_RERANKER_TIMEOUT_MS="30000"
  349. export FRONTAGENT_RAG_EMBEDDING_MODEL="text-embedding-3-small"
  350. export FRONTAGENT_RAG_EMBEDDING_BASE_URL="https://api.openai.com/v1"
  351. export FRONTAGENT_RAG_EMBEDDING_API_KEY="sk-..."
  352. export FRONTAGENT_RAG_EMBEDDING_DIMENSIONS=""
  353. export FRONTAGENT_RAG_EMBEDDING_BATCH_SIZE="32"
  354. export FRONTAGENT_RAG_EMBEDDING_TIMEOUT_MS="30000"
  355. export FRONTAGENT_RAG_VECTOR_STORE_PROVIDER="weaviate"
  356. export FRONTAGENT_RAG_WEAVIATE_URL="http://127.0.0.1:8080"
  357. export FRONTAGENT_RAG_WEAVIATE_API_KEY=""
  358. export FRONTAGENT_RAG_WEAVIATE_COLLECTION_PREFIX="FrontAgentRagChunk"
  359. export FRONTAGENT_RAG_WEAVIATE_BATCH_SIZE="64"
  360. export FRONTAGENT_RAG_WEAVIATE_TIMEOUT_MS="30000"
  361. # Filesense lightweight repository navigation
  362. export FRONTAGENT_FILESENSE_ENABLED="true"
  363. export FRONTAGENT_FILESENSE_OUTPUT="summary" # summary | candidates | verbose
  364. export FRONTAGENT_FILESENSE_WRITE_MODE="cache" # cache | workspace | none
  365. # Currently a no-op: navigate is read-only, so `cache`
  366. # and `none` behave identically and `workspace` is
  367. # downgraded during planning. No filesense tool reads
  368. # this value; filesense_sync always writes indexes.
  369. export FRONTAGENT_FILESENSE_MAX_ENTRIES="300"
  370. export FRONTAGENT_FILESENSE_MAX_BYTES="131072"
  371. export FRONTAGENT_FILESENSE_TIMEOUT_MS="3000"
  372. ```
  373. 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.
  374. Main LLM sampling controls:
  375. ```bash
  376. fa run "Explain React createElement" \
  377. --temperature 0.2 \
  378. --top-p 0.9
  379. ```
  380. - `--temperature` is supported.
  381. - `--top-p` is supported through the AI SDK call settings.
  382. - `--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.
  383. - `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.
  384. 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.
  385. 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.
  386. 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`.
  387. 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.
  388. Prebuilt cache bundle workflow:
  389. - Do not commit `.frontagent/rag-cache` into Git
  390. - Export a prebuilt cache bundle and upload it to GitHub Releases or object storage
  391. - Other users can import the bundle locally before their first query
  392. ```bash
  393. # Export the current cache directory as a distributable tar.gz bundle
  394. fa rag export
  395. # Export to a custom path
  396. fa rag export --output ./artifacts/frontagent-rag-cache.tar.gz
  397. # Import from a local file
  398. fa rag import ./artifacts/frontagent-rag-cache.tar.gz --force
  399. # Import from a remote URL
  400. fa rag import https://example.com/frontagent-rag-cache.tar.gz --force
  401. ```
  402. ## Architecture Overview
  403. ### System Architecture
  404. ```
  405. ┌─────────────────────────────────────────────────────────────────────┐
  406. │ FrontAgent System │
  407. ├─────────────────────────────────────────────────────────────────────┤
  408. │ │
  409. │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
  410. │ │ User Input │────▶│ Agent Core │────▶│ Output │ │
  411. │ └─────────────┘ └──────┬──────┘ └─────────────┘ │
  412. │ │ │
  413. │ ┌─────────────────┼─────────────────┐ │
  414. │ ▼ ▼ ▼ │
  415. │ ┌────────────────┐ ┌────────────┐ ┌────────────────┐ │
  416. │ │ SDD Layer │ │ Planner │ │ Executor │ │
  417. │ │ (Constraints) │ │ (Stage 1) │ │ (Stage 2) │ │
  418. │ └───────┬────────┘ └─────┬──────┘ └───────┬────────┘ │
  419. │ │ │ │ │
  420. │ ▼ ▼ ▼ │
  421. │ ┌──────────────────────────────────────────────────────┐ │
  422. │ │ MCP Layer (Trusted Interface) │ │
  423. │ ├──────────────┬───────────────┬──────────────────────┤ │
  424. │ │ MCP File │ MCP Web │ MCP Shell │ │
  425. │ └──────┬───────┴───────┬───────┴──────────┬───────────┘ │
  426. └─────────┼───────────────┼──────────────────┼────────────────────────┘
  427. ▼ ▼ ▼
  428. ┌──────────────┐ ┌──────────┐ ┌──────────┐
  429. │ File System │ │ Browser │ │ Shell │
  430. │ (Project) │ │(Playwright)│ │Commands │
  431. └──────────────┘ └──────────┘ └──────────┘
  432. ```
  433. ### Execution Flow
  434. ```
  435. User Task
  436. │
  437. ▼
  438. ┌──────────────────┐
  439. │ Pre-Planning │ ← Scan project structure (NEW!)
  440. │ File Scan │ Detect dev server port (NEW!)
  441. └────────┬─────────┘
  442. │
  443. ▼
  444. ┌──────────────────┐
  445. │ Planner (Stage1)│ ← SDD Constraints
  446. └────────┬─────────┘ Project file list
  447. │ Dev server port
  448. │ Generates execution plan (with phase field)
  449. ▼
  450. ┌──────────────────────────────────────────┐
  451. │ Executor (Stage 2) │
  452. │ ┌────────────────────────────────┐ │
  453. │ │ Phase 1: Analysis │ │
  454. │ │ ├─ Step 1 ✓ │ │
  455. │ │ ├─ Step 2 ✗ (error) │ │
  456. │ │ └─ Error Recovery │ │
  457. │ │ ├─ Analyze error │ │
  458. │ │ ├─ Generate fix steps │ │
  459. │ │ └─ Execute fix ✓ │ │
  460. │ └────────────────────────────────┘ │
  461. │ ┌────────────────────────────────┐ │
  462. │ │ Phase 2: Creation │ │
  463. │ │ ├─ Step 3 ✓ │ │
  464. │ │ └─ Step 4 ✓ │ │
  465. │ └────────────────────────────────┘ │
  466. │ │
  467. │ After each step: │
  468. │ └─ Update Facts │
  469. │ ├─ File system state │
  470. │ ├─ Dependency state │
  471. │ ├─ Module dependency graph │
  472. │ └─ Project state │
  473. │ │
  474. │ Phase completion validation: │
  475. │ └─ Check missing module references │
  476. │ └─ Auto-generate fix steps ✓ │
  477. └───────────────────────────────────────────┘
  478. │
  479. ▼
  480. Task Complete ✓
  481. ```
  482. Default phase taxonomy:
  483. `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)`
  484. ## Key Features
  485. ### 1. Pre-Planning Project Scan (NEW!)
  486. Before generating the execution plan, FrontAgent now automatically scans the project structure to provide accurate file context to the LLM:
  487. ```typescript
  488. // Automatically executed before planning
  489. const projectStructure = await scanProjectFiles();
  490. // Returns: "Project files (245 files): src/App.tsx, src/components/Button.tsx, ..."
  491. // LLM receives this context and generates more accurate file paths
  492. ```
  493. **Benefits**:
  494. - ✅ **Accurate File Paths** - LLM knows existing files and generates correct relative paths
  495. - ✅ **Reduced Hallucination** - Fewer "file not found" errors
  496. - ✅ **Better Context** - Planner understands the project structure before planning
  497. **Implementation**: `packages/core/src/agent/project-prescan-preparation.ts`
  498. ### 2. Automatic Dev Server Port Detection (NEW!)
  499. FrontAgent now automatically detects the development server port from your project configuration:
  500. ```typescript
  501. // Detection sources (in order):
  502. // 1. vite.config.ts/js: server.port field
  503. // 2. package.json scripts: --port or -p flags
  504. // 3. Framework defaults: Vite (5173), Next.js (3000), CRA (3000), Angular (4200)
  505. // 4. Fallback: 5173
  506. const devServerPort = await detectDevServerPort();
  507. // Used in browser navigation tasks
  508. ```
  509. **Benefits**:
  510. - ✅ **Automatic Port Discovery** - No manual port configuration needed
  511. - ✅ **Framework Awareness** - Recognizes different framework defaults
  512. - ✅ **Browser Testing** - Correct port used for browser validation tasks
  513. **Implementation**: `packages/core/src/agent/dev-server-detection.ts`
  514. ### 3. Two-Stage Architecture
  515. FrontAgent uses an innovative two-stage architecture that completely solves JSON parsing errors when generating large amounts of code:
  516. #### Stage 1: Planner
  517. - **Input**: User task + SDD constraints + project context + project file list (NEW!)
  518. - **Output**: Structured execution plan (descriptions only, no code)
  519. - **Tech**: Uses `generateObject` to produce Zod Schema-compliant JSON
  520. - **Key**: No code in JSON, avoiding escape and parsing issues
  521. ```json
  522. {
  523. "summary": "Create login page",
  524. "steps": [
  525. {
  526. "description": "Create Login.tsx component file",
  527. "action": "create_file",
  528. "params": {
  529. "path": "src/pages/Login.tsx",
  530. "codeDescription": "Create a React component with username, password inputs and login button"
  531. },
  532. "needsCodeGeneration": true
  533. }
  534. ]
  535. }
  536. ```
  537. #### Stage 2: Executor
  538. - **Input**: Structured execution plan
  539. - **Process**: Execute each step in the plan sequentially
  540. - **Code Generation**: When encountering `needsCodeGeneration: true`, dynamically generate code using `generateText`
  541. - **Tech**: Use MCP tools for file operations, command execution, etc.
  542. **Advantages**:
  543. 1. ✅ Completely avoid JSON parsing errors (code not in JSON)
  544. 2. ✅ Better controllability (each step validated individually)
  545. 3. ✅ Support large projects (no JSON size limit)
  546. 4. ✅ More precise code generation (based on real-time context)
  547. ### 4. Phase-Based Execution & Self-Healing
  548. FrontAgent implements advanced phase-based execution and automatic error recovery:
  549. #### Phase-Based Execution
  550. The execution plan is automatically divided into multiple phases, each focused on a specific goal:
  551. ```json
  552. {
  553. "steps": [
  554. {
  555. "stepId": "step-1",
  556. "phase": "Analysis Phase",
  557. "description": "Read existing files, analyze project structure",
  558. "action": "read_file"
  559. },
  560. {
  561. "stepId": "step-2",
  562. "phase": "Creation Phase",
  563. "description": "Create new component files",
  564. "action": "create_file"
  565. },
  566. {
  567. "stepId": "step-3",
  568. "phase": "Installation Phase",
  569. "description": "Install necessary dependencies",
  570. "action": "run_command"
  571. },
  572. {
  573. "stepId": "step-4",
  574. "phase": "Validation Phase",
  575. "description": "Run tests to verify functionality",
  576. "action": "run_command"
  577. },
  578. {
  579. "stepId": "step-5",
  580. "phase": "Repository Management Phase",
  581. "description": "Commit changes, push branch, and create/update PR with gh",
  582. "action": "run_command"
  583. }
  584. ]
  585. }
  586. ```
  587. **Advantages**:
  588. - 🎯 **Clear Execution Flow** - Each phase has a clear objective
  589. - 🔄 **Intra-Phase Error Recovery** - Errors automatically fixed within phases
  590. - 📊 **Better Progress Tracking** - Users see which phase is currently executing
  591. - 🔀 **Dependency-Aware Phase Ordering** - Phase DAG scheduling reduces out-of-order skips
  592. - 🚀 **Post-Acceptance Automation** - Optional repository management phase can handle git/gh flow
  593. #### Tool Error Feedback Loop
  594. When tool execution fails, the system automatically analyzes errors and generates fix steps:
  595. ```typescript
  596. // 1. Error detected
  597. Error: Cannot apply patch: file not found in context: src/App.tsx
  598. // 2. LLM analyzes error
  599. {
  600. "canRecover": true,
  601. "analysis": "File src/App.tsx not read into context, need to read it first",
  602. "recoverySteps": [
  603. {
  604. "description": "Read src/App.tsx into context",
  605. "action": "read_file",
  606. "tool": "filesystem",
  607. "params": { "path": "src/App.tsx" }
  608. },
  609. {
  610. "description": "Reapply patch to src/App.tsx",
  611. "action": "apply_patch",
  612. "tool": "filesystem",
  613. "params": { /* original params */ }
  614. }
  615. ]
  616. }
  617. // 3. Auto-execute fix steps
  618. // 4. Continue original flow
  619. ```
  620. **Features**:
  621. - 🔍 **Smart Error Analysis** - LLM understands error causes and finds root issues
  622. - 🛠️ **Auto-Generate Fixes** - No manual intervention needed
  623. - 📝 **Common Error Patterns** - Built-in handling for common errors
  624. - ♻️ **Phase-Level Recovery** - Errors fixed within phases without blocking overall flow
  625. ### 5. LangGraph Execution Engine (NEW!)
  626. FrontAgent now supports a switchable execution engine:
  627. - `native` (default): Existing executor flow with phase DAG scheduling
  628. - `langgraph`: Runs phase flow through `StateGraph` with optional `MemorySaver` checkpoint
  629. CLI options:
  630. ```bash
  631. # Use native engine (default)
  632. fa run "Add login page" --engine native
  633. # Use LangGraph engine
  634. fa run "Add login page" --engine langgraph
  635. # LangGraph + checkpoint + custom recovery attempts
  636. fa run "Add login page" --engine langgraph --langgraph-checkpoint --max-recovery-attempts 5
  637. ```
  638. ### 6. Planner Skills Layer (NEW!)
  639. FrontAgent adds a dedicated `skills` layer in Planner to encapsulate reusable planning logic.
  640. - Built-in task skills: `task.create`, `task.modify`, `task.query`, `task.debug`, `task.refactor`, `task.test`
  641. - Built-in phase skill: `phase.repository-management` (injects git/gh workflow after acceptance)
  642. - Custom task skills with the same match condition override built-ins (latest registered wins)
  643. - Executor also supports action-level skills (for params/codegen/error policy)
  644. - Supports runtime extension via API:
  645. ```typescript
  646. import { createAgent, type TaskPlanningSkill } from '@frontagent/core';
  647. const agent = createAgent(config);
  648. const customSkill: TaskPlanningSkill = {
  649. name: 'task.security-audit',
  650. supports: (task) => task.type === 'debug' && task.description.includes('security'),
  651. plan: ({ stepFactory }) => [
  652. stepFactory.createStep({
  653. description: 'Scan for security-sensitive patterns',
  654. action: 'search_code',
  655. tool: 'search_code',
  656. params: {
  657. pattern: 'eval|innerHTML|dangerouslySetInnerHTML',
  658. filePattern: 'src/**/*.{ts,tsx,js,jsx}',
  659. },
  660. }),
  661. ],
  662. };
  663. agent.registerTaskSkill(customSkill);
  664. console.log(agent.getPlannerSkillSnapshot());
  665. agent.registerExecutorActionSkill({
  666. name: 'action.run-command.noncritical-policy',
  667. action: 'run_command',
  668. shouldSkipToolError: ({ errorMsg, params }) => {
  669. if (typeof params.command === 'string' && params.command.includes('echo')) {
  670. return true;
  671. }
  672. return errorMsg.includes('already exists');
  673. },
  674. });
  675. console.log(agent.getExecutorSkillSnapshot());
  676. ```
  677. ### 7. Facts-Based Context System
  678. Traditional agents use logs as context, leading to information redundancy and inaccuracy. FrontAgent uses a structured "facts" system:
  679. **Traditional approach (log-based)**:
  680. ```
  681. Executed operation log:
  682. 1. Attempted to read src/App.tsx - failed
  683. 2. Attempted to create src/components/Button.tsx - success
  684. 3. Attempted to read src/App.tsx - success
  685. 4. Installed react-router-dom - success
  686. ...(lots of redundant info)
  687. ```
  688. **FrontAgent approach (facts-based)**:
  689. ```yaml
  690. ## File System State
  691. ### Confirmed Existing Files:
  692. - src/App.tsx
  693. - src/components/Button.tsx
  694. - package.json
  695. ### Confirmed Non-Existent Paths:
  696. - src/pages/Login.tsx
  697. ## Dependency State
  698. ### Installed Packages:
  699. react-router-dom, axios
  700. ### Missing Packages:
  701. @types/node
  702. ## Created Modules
  703. ### component (3 modules):
  704. - src/components/ui/Button.tsx (default export: Button)
  705. - src/components/ui/Card.tsx (default export: Card)
  706. - src/components/layout/Header.tsx (exports: Header, Navigation)
  707. ### page (2 modules):
  708. - src/pages/HomePage.tsx (default export: HomePage)
  709. - src/pages/LoginPage.tsx (default export: LoginPage)
  710. ### ⚠️ Missing Module References:
  711. - src/pages/HomePage.tsx references non-existent module: ../components/ui/Spinner
  712. ## Project State
  713. - Dev server: Running (port: 5173) ← Auto-detected!
  714. - Build status: Success
  715. ## Recent Errors
  716. - [apply_patch] Cannot apply patch: file not found in context
  717. ```
  718. **Advantages**:
  719. - 📊 **Structured Information** - Clear state categories (filesystem, dependencies, module graph, project state)
  720. - 🎯 **Deduplication** - Automatic deduplication using Set/Map
  721. - 💡 **Context Awareness** - LLM knows which files exist/don't exist
  722. - 🔄 **Real-time Updates** - Auto-update facts after each tool execution
  723. - 📉 **Reduced Token Usage** - Concise information reduces LLM input length
  724. - 🔗 **Module Tracking** - Auto-parse import/export relationships for each created file
  725. ### 8. Cross-Session Memory System (NEW!)
  726. FrontAgent now implements a four-phase memory architecture that persists knowledge across task runs, so the agent no longer starts from scratch every time.
  727. #### Architecture
  728. The memory system treats context as a time-phased pipeline:
  729. 1. **Phase 1 -- Startup Preload**: Load durable memories and seed `ProjectFacts` from the last snapshot before planning begins
  730. 2. **Phase 2 -- Runtime Recall**: Dynamically recall relevant memories during code generation based on file path, tags, and keywords
  731. 3. **Phase 3 -- Post-Task Persistence**: Extract and persist durable learnings (created files, error resolutions, dependency changes) after each task completes
  732. 4. **Phase 4 -- Compaction**: Deferred until multi-turn interactive mode is added
  733. #### Storage Layout
  734. ```
  735. <projectRoot>/.frontagent/memory/
  736. MEMORY.md # Index entrypoint (concise topic list)
  737. topics/
  738. project-structure.md # Filesystem layout, key modules
  739. dependencies.md # Packages, versions, known issues
  740. errors.md # Past error resolutions
  741. snapshots/
  742. facts-latest.json # Last ProjectFacts snapshot
  743. ```
  744. All memory files are human-readable Markdown (inspectable, editable). Facts snapshots use JSON for efficiency.
  745. #### Prompt Separation
  746. The system prompt is now structured into three independent zones, each with its own token budget:
  747. 1. **Rules zone** -- SDD constraints, behavioral instructions (immutable per task)
  748. 2. **Memory zone** -- Durable project knowledge loaded from `.frontagent/memory/`
  749. 3. **Context zone** -- Dynamic per-task data (files, RAG results, skills, facts)
  750. #### Key Design Decisions
  751. - **Single-writer pattern**: All writes go through `MemoryStore` to prevent conflicts
  752. - **Dedup tracking**: Per-session `injectedKeys` set prevents re-injecting the same memory
  753. - **Budget enforcement**: Configurable character limits for preload (default 8000) and per-step recall (default 2000)
  754. - **Non-blocking persistence**: Memory writes run off the critical path with full error swallowing
  755. - **Backward compatible**: Fresh projects with no prior memory run identically to previous behavior
  756. #### Configuration
  757. ```typescript
  758. const agent = createAgent({
  759. // ...other config
  760. memory: {
  761. enabled: true, // default: true
  762. preloadBudgetChars: 8000, // max chars injected at startup
  763. recallBudgetChars: 2000, // max chars per code-gen recall
  764. maxTopicFiles: 10, // max topic files loaded at startup
  765. },
  766. });
  767. ```
  768. **Implementation**: `packages/core/src/memory/`
  769. ## Core Modules
  770. ### @frontagent/sdd - SDD Control Layer
  771. Specification Driven Development (SDD) as hard constraints for agent behavior:
  772. ```yaml
  773. # sdd.yaml
  774. version: "1.0"
  775. project:
  776. name: "my-project"
  777. type: "react-spa"
  778. tech_stack:
  779. framework: "react"
  780. version: "^18.0.0"
  781. language: "typescript"
  782. forbidden_packages:
  783. - "jquery"
  784. - "lodash"
  785. code_quality:
  786. max_function_lines: 50
  787. max_file_lines: 300
  788. forbidden_patterns:
  789. - "any"
  790. - "// @ts-ignore"
  791. modification_rules:
  792. protected_files:
  793. - "package.json"
  794. require_approval:
  795. - pattern: "src/api/*"
  796. reason: "API layer changes require approval"
  797. ```
  798. ### @frontagent/mcp-file - File Operations MCP
  799. Provides file operation MCP tools:
  800. - `read_file` - Read file content
  801. - `list_directory` - List directory content (supports recursion)
  802. - `create_file` - Create new file (two-stage: generate code from description)
  803. - `apply_patch` - Apply code patches (two-stage: generate changes from description)
  804. - `search_code` - Search code
  805. - `get_ast` - Get AST analysis
  806. - `rollback` - Rollback changes
  807. ### @frontagent/mcp-shell - Shell Command MCP
  808. Provides terminal command execution (requires user approval):
  809. - `run_command` - Execute shell commands
  810. - Custom working directory support
  811. - Timeout settings
  812. - User approval required before execution
  813. - Auto-distinguish warnings from errors
  814. - Use cases: `npm install`, `git init`, `pnpm build`, etc.
  815. ### @frontagent/mcp-web - Web Awareness MCP
  816. Provides browser interaction MCP tools:
  817. - `browser_navigate` - Navigate to URL
  818. - `get_page_structure` - Get page DOM structure
  819. - `get_accessibility_tree` - Get accessibility tree
  820. - `get_interactive_elements` - Get interactive elements
  821. - `browser_click` / `browser_type` / `browser_scroll` - Page interactions
  822. - `browser_screenshot` - Page screenshot
  823. - `browser_wait_for_selector` - Wait for element availability
  824. ### @frontagent/hallucination-guard - Hallucination Prevention
  825. Multi-layer hallucination detection:
  826. 1. **File Existence Check** - Verify referenced files exist
  827. 2. **Import Validity Check** - Verify imports are resolvable
  828. 3. **Syntax Validity Check** - Verify code syntax is correct
  829. 4. **SDD Compliance Check** - Verify compliance with SDD constraints
  830. ## Tech Stack
  831. - **Language**: TypeScript
  832. - **Runtime**: Node.js 20+
  833. - **Package Manager**: pnpm
  834. - **MCP SDK**: @modelcontextprotocol/sdk
  835. - **Browser Automation**: Playwright
  836. - **AST Analysis**: ts-morph
  837. - **LLM Integration**: Vercel AI SDK
  838. ## Directory Structure
  839. ```
  840. frontagent/
  841. ├── packages/
  842. │ ├── shared/ # Shared types and utilities
  843. │ ├── sdd/ # SDD control layer
  844. │ ├── mcp-file/ # File operations MCP client
  845. │ ├── mcp-web/ # Web awareness MCP client
  846. │ ├── mcp-shell/ # Shell commands MCP client
  847. │ ├── hallucination-guard/ # Hallucination prevention
  848. │ └── core/ # Agent core (two-stage architecture)
  849. │ └── memory/ # Cross-session memory system
  850. ├── apps/
  851. │ └── cli/ # CLI tool
  852. ├── examples/
  853. │ ├── sdd-example.yaml # SDD config example
  854. │ └── e-commerce-frontend/ # E-commerce frontend example
  855. └── docs/
  856. ├── architecture.md # Architecture design
  857. └── design.md # Original requirements
  858. ```
  859. ## Usage Examples
  860. ### Example 1: Create New Project
  861. ```bash
  862. cd examples
  863. fa run "Create an e-commerce frontend project using React + TypeScript + Vite + Tailwind CSS"
  864. ```
  865. Agent will automatically:
  866. 1. Analyze project requirements
  867. 2. Generate execution plan
  868. 3. Create package.json and config files
  869. 4. Request to execute `npm install` (requires user approval)
  870. 5. Generate page components and style files
  871. ### Example 2: Modify Existing Files
  872. ```bash
  873. fa run "Modify vite.config.ts to add path alias configuration"
  874. ```
  875. Agent will:
  876. 1. Read existing vite.config.ts
  877. 2. Understand current configuration
  878. 3. Generate new config code
  879. 4. Apply minimal patches
  880. ### Example 3: Add New Features
  881. ```bash
  882. fa run "Add user authentication feature, including login, registration, and token management"
  883. ```
  884. Agent will:
  885. 1. Analyze existing project structure
  886. 2. Plan files to create
  887. 3. Generate auth-related components
  888. 4. Create API integration code
  889. 5. Update route configuration
  890. ### Example 4: Performance Optimization
  891. ```bash
  892. fa run "Analyze and optimize homepage loading performance"
  893. ```
  894. Agent will:
  895. 1. Read relevant component code
  896. 2. Analyze performance issues
  897. 3. Propose optimization solutions
  898. 4. Implement code-level optimizations (lazy loading, code splitting, etc.)
  899. ### Example 5: Auto Error Recovery
  900. ```bash
  901. fa run "Add route configuration in App.tsx"
  902. ```
  903. Execution process shows self-healing:
  904. ```
  905. Phase 1: Analysis Phase
  906. ✓ Step 1: Read package.json
  907. Phase 2: Creation Phase
  908. ✗ Step 2: Modify App.tsx
  909. Error: Cannot apply patch: file not found in context
  910. 🔄 Error recovery in progress...
  911. Analysis: App.tsx not read into context
  912. ✓ Recovery Step 1: Read src/App.tsx into context
  913. ✓ Recovery Step 2: Reapply patch to App.tsx
  914. Phase 3: Validation Phase
  915. ✓ Step 3: Run type check
  916. ✅ Task complete! Auto-fixed 1 error
  917. ```
  918. **Key Features**:
  919. - 🎯 **Phase-Based Execution** - Clear execution phases (Analysis, Creation, Validation)
  920. - 🔄 **Auto-Fix** - Detected file not read, auto-insert read step
  921. - 📊 **Facts Tracking** - System knows which files are read/unread
  922. - ⚡ **No Retry Needed** - One-shot completion, no manual re-runs needed
  923. ### Example 6: Enable LangGraph Engine
  924. ```bash
  925. fa run "Implement user profile page and open PR" \
  926. --type create \
  927. --engine langgraph \
  928. --langgraph-checkpoint \
  929. --max-recovery-attempts 5
  930. ```
  931. Notes:
  932. - `--engine langgraph` enables graph-based phase orchestration
  933. - `--langgraph-checkpoint` enables in-memory checkpointing for the run
  934. - After acceptance passes, repository management phase can run `git/gh` actions
  935. ## Environment Variables
  936. ### Required Configuration
  937. | Variable | Description | Example Value |
  938. | ----------------------- | ------------------------------- | ------------------------------------- |
  939. | `PROVIDER` | LLM provider | `openai` or `anthropic` |
  940. | `API_KEY` | API key | `sk-...` |
  941. | `MODEL` | Model name | `gpt-4` or `claude-sonnet-4-20250514` |
  942. | `BASE_URL` | API endpoint | `https://api.openai.com/v1` |
  943. | `EXECUTION_ENGINE` | Execution engine | `native` or `langgraph` |
  944. | `LANGGRAPH_CHECKPOINT` | Enable LangGraph checkpoint | `true` / `false` |
  945. | `MAX_RECOVERY_ATTEMPTS` | Max recovery attempts per phase | `3` |
  946. ### OpenAI Configuration Example
  947. ```bash
  948. export PROVIDER="openai"
  949. export BASE_URL="https://api.openai.com/v1"
  950. export MODEL="gpt-4"
  951. export API_KEY="sk-..."
  952. ```
  953. ### Anthropic Configuration Example
  954. ```bash
  955. export PROVIDER="anthropic"
  956. export BASE_URL="https://api.anthropic.com"
  957. export MODEL="claude-sonnet-4-20250514"
  958. export API_KEY="sk-ant-..."
  959. ```
  960. ## Development
  961. ```bash
  962. # Development mode
  963. pnpm dev
  964. # Type check
  965. pnpm typecheck
  966. # Build
  967. pnpm build
  968. # Clean
  969. pnpm clean
  970. ```
  971. ## Roadmap
  972. ### Completed ✅
  973. - [x] Two-stage agent architecture (Planner + Executor)
  974. - [x] Phase-based execution
  975. - [x] Tool Error Feedback Loop (self-healing)
  976. - [x] Facts-based context system
  977. - [x] Module dependency graph
  978. - [x] Post-generation validation
  979. - [x] Path hallucination detection
  980. - [x] Multi-LLM provider support (OpenAI, Anthropic)
  981. - [x] Shell command execution (with user approval)
  982. - [x] Dynamic code generation (avoid JSON parsing errors)
  983. - [x] MCP tool integration (File, Web, Shell)
  984. - [x] Type auto-normalization (handle LLM output uncertainty)
  985. - [x] Unlimited steps (support complex tasks with many steps)
  986. - [x] LLM schema constraint optimization (multi-strategy auto-fix, smart retry)
  987. - [x] **Pre-planning file scan** (NEW!)
  988. - [x] **Auto dev server port detection** (NEW!)
  989. - [x] **Dependency-aware phase DAG scheduling** (NEW!)
  990. - [x] **LangGraph execution engine (optional)** (NEW!)
  991. - [x] **Repository management phase (git/gh automation)** (NEW!)
  992. - [x] **Cross-session memory system** (NEW!) -- Four-phase durable memory with structured Markdown storage, runtime recall, and prompt zone separation
  993. - [x] **Distilled Planner Models** -- SFT fine-tuned from FrontAgent Planner prompts, published in the [FrontAgent: Frontend Engineering Agent](https://hf.co/collections/ceilf6/frontagent-frontend-engineering-agent) Hugging Face collection, with training and release assets in [models/frontagent-planner](models/frontagent-planner)
  994. - [x] **VS Code extension** -- Sidebar task console, current file/selection context, SDD commands, secure configuration, run logs, and packaged Marketplace artifact
  995. - [x] **Local stdio MCP server** -- Host-facing FrontAgent task, planning, status, skill, and SDD tools with fail-closed internal execution security
  996. - [x] **Filesense repository navigation** -- Budgeted current-repository structure lookup with generated JSON schemas and explicit cache/workspace/none write modes
  997. - [x] **OSS Harness quality gates** -- Bootstrap, local contract, precommit, CI, GitNexus, and workflow-rule checks
  998. ### In Progress 🚧
  999. - [ ] Enhanced SDD constraints (finer-grained rule control)
  1000. ### Planned 📋
  1001. - [ ] Memory-driven pattern learning (auto-extract coding conventions from past tasks)
  1002. - [ ] GUI agent auto-testing (Playwright-based)
  1003. - [ ] Multi-agent collaboration (decompose large tasks)
  1004. - [ ] Custom MCP server support (user-defined tools)
  1005. - [ ] Code review mode (auto-check code quality)
  1006. - [ ] Incremental update mode (only modify necessary parts)
  1007. ## Friendly Links
  1008. - [Linux.do](https://linux.do/) - Chinese AI learning and developer community.
  1009. - [Aionui](https://github.com/iOfficeAI/AionUi) - Mobile remote-control UI for letting AI agents operate tasks from a phone.
  1010. - [OfficeCLI](https://github.com/iOfficeAI/OfficeCLI) - Office suite designed for AI agents.
  1011. - [deepseek-pp](https://github.com/zhu1090093659/deepseek-pp) - Browser extension for DeepSeek web conversations.
  1012. - [MuseAI](https://github.com/yejiming/MuseAI) - Local AI companion, text adventure, and interactive fiction app.
  1013. - [RedBox](https://github.com/Jamailar/RedBox) - Local AI creation workspace for Xiaohongshu creators.
  1014. - [1flowbase](https://github.com/taichuy/1flowbase) - Virtual model gateway for publishing multi-model workflows as OpenAI/Claude-compatible endpoints, with trace, token, latency, and cost visibility.
  1015. ## Ablation Benchmark (reproducible)
  1016. A frozen 30-task benchmark measures whether SDD constraints and the hallucination guard actually improve first-pass success. It runs on an isolated fixture project with machine-checkable acceptance (`tsc --noEmit`, `vitest`, file assertions), two arms, and resume-on-interrupt.
  1017. ```bash
  1018. pnpm build
  1019. pnpm --dir benchmarks/eval/fixture install # fixture deps (required)
  1020. node benchmarks/eval/run-eval.mjs --arm full --tasks all # SDD on
  1021. node benchmarks/eval/run-eval.mjs --arm ablation --tasks all # SDD off
  1022. node benchmarks/eval/report.mjs benchmarks/eval/out
  1023. ```
  1024. A separate arm ablates **filesense** alone — it differs from `full` in exactly one
  1025. field, so unlike `full` vs `ablation` (which leaves filesense enabled in both) its
  1026. difference is attributable to navigation. It is meant to be run against the deep
  1027. fixture: on the flat one, filesense scans 17 of the repository's 18 entries and
  1028. never truncates, so budgeted navigation and a plain `ls -R` are indistinguishable
  1029. by construction.
  1030. ```bash
  1031. # One-time: install fixture dependencies and materialise the generated module tree.
  1032. # The runner refuses to start without node_modules — a dangling symlink would
  1033. # otherwise turn every typecheck into a FAIL and record an arm of noise as data.
  1034. pnpm --dir benchmarks/eval/fixture-deep install
  1035. node benchmarks/eval/fixture-deep/generate.mjs
  1036. node benchmarks/eval/run-eval.mjs --arm full --fixture deep --tasks all
  1037. node benchmarks/eval/run-eval.mjs --arm no-filesense --fixture deep --tasks all
  1038. node benchmarks/eval/report-filesense.mjs benchmarks/eval/out deep
  1039. ```
  1040. Latest results: [`benchmarks/results/`](benchmarks/results/). **The current findings are negative and actionable**: SDD showed no measurable effect on first-pass rate, and the hallucination guard recorded zero interceptions while syntactically invalid files still landed on disk. Three root causes are documented in the report and tracked as issues.
  1041. That zero-interception count has since been qualified: [`2026-07-31-validation-telemetry.md`](benchmarks/results/2026-07-31-validation-telemetry.md) shows the event had no emit site anywhere in the repo at the time, so it could not have been anything but zero. A deterministic probe (committed alongside the report, no LLM spend) shows the check was running and failing all along — it just emitted nothing and left the file on disk.
  1042. ## Download Stats (verifiable)
  1043. [![Cumulative npm downloads since 2026-01-14](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.npmjs.org%2Fdownloads%2Fpoint%2F2026-01-14%3A2099-12-31%2Ffrontagent&query=%24.downloads&label=cumulative%20npm%20downloads%20since%202026-01-14)](https://www.npmjs.com/package/frontagent)
  1044. The badge is rendered live by shields.io from the public npm registry endpoint below, so the number it shows is the one you can reproduce yourself:
  1045. ```bash
  1046. # macOS: date -u -v-1d +%F | Linux: date -u -d yesterday +%F
  1047. curl -s "https://api.npmjs.org/downloads/point/2026-01-14:$(date -u -v-1d +%F 2>/dev/null || date -u -d yesterday +%F)/frontagent" | jq
  1048. ```
  1049. ## Contributing
  1050. Welcome to contribute! Submit issues, bugs, or suggestions:
  1051. 1. Fork the repository
  1052. 2. Create a new branch `git checkout -b feature/amazing-feature`
  1053. 3. Commit your changes `git commit -m 'Add amazing feature'`
  1054. 4. Push to the branch `git push origin feature/amazing-feature`
  1055. 5. Open a Pull Request
  1056. ## License
  1057. MIT
  1058. Contributions are welcome! Please feel free to submit issues, bug reports, or suggestions.
  1059. 1. Fork this repository
  1060. 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
  1061. 3. Commit your changes (`git commit -m 'Add amazing feature'`)
  1062. 4. Push to the branch (`git push origin feature/amazing-feature`)
  1063. 5. Open a Pull Request
  1064. ## License
  1065. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.