localforge

Localforge is a self-hosted AI coding agent that gives you a real graphical interface — not just a terminal — around an agentic loop that reads, edits, and executes code directly in your own project directories. It installs as a global npm package (@rockbite/localforge) that starts a local web server, or runs as a packaged Electron desktop app on macOS, Windows, and Linux, so the whole experience stays on your machine.

Under the hood, the agent is built around a Claude-Code-style tool registry — Bash, Edit, Glob, Grep, LS, Replace, View, and WebFetch — dispatched from a central orchestration loop (src/services/agent) that loads its system prompt from EJS templates and persists session/task state in a local LevelDB store. A DispatchAgentTool lets the main agent hand off scoped work to sub-agents, and a built-in task tracker (with sub-task support) keeps long-running sessions organized.

What sets Localforge apart from single-vendor coding assistants is its provider-agnostic middleware: a unified callLLMByType layer routes requests to Anthropic, OpenAI, Google Gemini, AWS Bedrock, Ollama, or Hugging Face depending on how you configure each of the three model slots (main, aux, expert). It also ships Puppeteer-backed browser tools so the agent can navigate, click, and screenshot pages it just built or modified, and a Model Context Protocol (MCP) client so you can plug in external tool servers — including IDE-hosted ones — without touching the codebase.

The project is young (first commit April 2025) and maintained essentially by a single core contributor, but it already ships nine tagged releases, an auto-updating Electron build pipeline, and a conversation-compression feature that uses an expert model to summarize long chat histories so token costs don’t spiral on extended sessions.

What You Get

• A desktop (Electron) or local web UI for driving an AI coding agent against your own project files, instead of a terminal-only experience
• A file-and-shell tool suite — Bash, Edit, Glob, Grep, LS, Replace, View, WebFetch — modeled on the tool patterns used by CLI coding agents
• Support for six LLM providers (Anthropic, OpenAI, Gemini, AWS Bedrock, Ollama, Hugging Face) configured independently for main, auxiliary, and expert model roles, so you can bring your own keys or run fully local models
• A built-in Model Context Protocol (MCP) client to attach external tool servers, including IDE-hosted MCP servers, without modifying the app
• Puppeteer-backed browser automation tools (claim, navigate, interact, screenshot) so the agent can drive and visually verify a real browser
• A persistent per-project task tracker with sub-task support, plus a conversation-compression feature that uses an expert model to summarize long chat histories

Common Use Cases

• Running an agentic coding assistant locally against a project without a hosted subscription, using API keys you already have
• Keeping code and conversation history entirely on your own machine for privacy, since all state persists locally via LevelDB and Conf
• Extending the agent’s available tools by connecting existing MCP servers instead of writing custom tool code
• Visually verifying frontend changes using the built-in Puppeteer-based browser automation tools
• Managing long, multi-day coding sessions with the built-in task tracker and conversation compression to keep token costs under control

Under The Hood

Architecture Localforge is a layered but tightly-coupled Node.js application: HTTP/Socket.io routes (src/routes/*Routes.js) sit above a services layer (src/services/agent, sessions, accounting, tasks, mcp, image), which in turn drives a whitelisted tool registry (tools/index.js) and a multi-provider LLM middleware (src/middleware/llm.js plus providers/*). The central orchestration file in src/services/agent/index.js is the real “brain” — it loads EJS-templated system prompts, manages the agentic tool-calling loop, and coordinates with a DispatchAgentTool for sub-agent delegation, while src/db/store.js and agentStore.js persist settings and session state locally via Conf and LevelDB. There is no dependency-injection framework; modules reach for shared singletons (store, agentStore, mcpService) directly, which keeps the codebase simple to follow but means the agent orchestration file is a load-bearing hub that most other layers depend on.

Tech Stack The backend is plain ESM JavaScript on Node.js using Express and Socket.io for the local server, wrapped by Electron for desktop distribution (with an auto-updater and packaged installers for macOS, Windows, and Linux). Persistence is entirely local — LevelDB plus the conf package — so no external database is required. LLM access spans six providers via official and community SDKs (@anthropic-ai/sdk, openai, @google/genai, @google-cloud/vertexai, plus Ollama and Hugging Face support), and tool capability is extended through the official @modelcontextprotocol/sdk. The frontend is server-rendered EJS combined with Shoelace web components and Lit, built with Vite, rather than a React/Vue single-page app. Browser-automation tools rely on Puppeteer, JSDOM, and Mozilla’s Readability library for page interaction and content extraction.

Code Quality Testing is minimal: the repository contains a single ad hoc test script (tests/grepTool.test.js) run directly with node, with no test framework, assertion library, or CI job that executes tests — the GitHub Actions workflows present are build/release pipelines only. There is no TypeScript and no linter or formatter configuration in the repo, so type safety and enforced style are absent. Error handling is present but informal: top-level uncaughtException/unhandledRejection handlers log crashes to disk, and individual modules use try/catch with console logging fairly consistently, but nothing is systematically typed or verified.

What Makes It Unique Localforge’s differentiator is packaging a Claude-Code-style agentic tool loop (Bash, Edit, Glob, Grep, LS, View, Replace, WebFetch) behind a real local desktop and web UI instead of a terminal, while remaining provider-agnostic — the same agent can run against Anthropic, OpenAI, Gemini, Bedrock, a local Ollama model, or Hugging Face depending on user configuration. Layered on top are sub-agent dispatch for delegated work, Puppeteer-driven browser tools so the agent can visually verify its own output, MCP client support for pulling in external tool servers, and a built-in task tracker with conversation compression for long sessions. None of these ideas are individually novel, but the combination — local-first, multi-provider, GUI-driven, browser-capable — occupies a fairly distinct niche relative to CLI-only or single-vendor coding agents.

Self-Hosting

Licensing Model MIT licensed — all features are available in self-hosted deployments with no restrictions or license keys required.

Self-Hosting Restrictions None found. No ee/, enterprise/, pro/, or cloud/ directories exist in the repo, and no license-gating code (requiresLicense, isPro, isEnterprise, feature flags) was found in the source. The entire agent, tool suite, provider integrations, and UI ship in the open-source repo.

Enterprise Features None. There is no separate paid software tier. The README links to a “Supporter Edition” on Gumroad, which is a voluntary donation that grants priority Discord access — it does not unlock or gate any application functionality.

License Key Required No.