ForgePilot

ForgePilot is an Electron desktop agent workspace for local and hosted LLMs. It provides a Codex/Cursor-style chat UI, a multi-provider runtime, built-in file and terminal tools, MCP support, web research tools, and document ingestion for PDFs and office files.

The core design goal is simple: even if a model does not support native tool calling, the app can still run tools through an emulated agent envelope and continue the same workflow.

What's New in v2.4.1

• Reuse the latest successful web search from earlier turns when redirecting an invented URL to a discovered result. This no longer depends on matching message timestamps.
• Keep Windows command smoke tests tolerant of cold shell startup and web error tests independent of real browser/network availability.
• Publish tagged releases only after every platform build succeeds; partial uploads remain drafts.

What's New in v2.4.0

• Render assistant responses as safe Markdown with tables, task lists, code blocks, and copy controls.
• Expand file changes directly inside chat, with added and removed lines highlighted.
• Keep reasoning collapsed by default, reduce composer height, and grow the input as you type.
• Collapse source lists, open sources directly in the browser, and remove duplicated header controls.
• Send with Enter and insert a new line with Shift+Enter, including composition-safe keyboard handling.
• Send lightweight streaming updates rather than the full conversation for each chunk.
• Automatically load root-level AGENTS.md and discover project skills in .agents/skills, .claude/skills, and .opencode/skills. Skill bodies are read on demand with fs_read.
• Compact older turns using an approximate context-size budget as well as message count. Large tool outputs are shortened for the model without changing saved history or breaking native tool-call pairs.
• Reject file writes and patches when a previously read or edited file has changed externally, including after reopening saved threads. Read the file again to continue.
• Reject ambiguous patch matches unless replaceAll is explicitly requested.
• Accept LF patch excerpts for Windows CRLF files while preserving their line endings.
• Open only HTTP/HTTPS links in the external browser; model HTML is displayed as text and remote Markdown images are not loaded automatically.

Project Instructions and Skills

Put project instructions in AGENTS.md at the workspace root. ForgePilot reloads them at the beginning of each run. Files larger than 24 KB are not loaded automatically; read those explicitly with the file tools.

Skills use <directory>/<skill-name>/SKILL.md under one of the three supported skill directories above. Use YAML frontmatter with a name and description, followed by the instructions. ForgePilot includes a bounded catalog of descriptions and exact paths, not every skill's full content, in the model context. Existing permission presets and agent modes still apply to skill-directed tool use.

Context budgeting is an estimate, not a provider-specific tokenizer. It preserves the latest user turn and its tool calls; unusually large single turns or tool catalogs may still exceed a model's context limit. File freshness checks protect the built-in fs_write and fs_patch tools, not edits made through terminal commands or external MCP tools.

What's New in v2.3.1

• Bundled the renderer locally so the desktop UI opens without loading React from an external CDN.
• Added live streaming for OpenAI-compatible and Anthropic providers, including streamed tool calls and JSON fallback responses from local servers.
• Kept Plan mode read-only for MCP and plugin tools as well as built-in tools.
• Counted distinct fetched URLs as research sources, so opening the same page twice does not satisfy the multi-source check.
• Restored search result IDs from saved thread history so earlier results can be opened in later turns.
• Kept the chat at the user's reading position during updates and limited the height of live activity.
• Updated Electron and packaging dependencies, with zero findings in the current npm audit.

What's New in v2.1

• Added a scalable localization layer with a 5-language core:
  • English
  • Turkce
  • Deutsch
  • Espanol
  • Russkiy
• Added browser_fetch as a browser-backed research tool for blocked or JS-heavy pages
• Improved web_search and web_fetch reliability:
  • DuckDuckGo redirect unwrapping
  • inaccessible-result filtering
  • result-aware fetch flow using discovered search results
  • stricter runtime guards against hallucinated URLs
  • better timeout and network error handling
• Added thread-level attachment reuse and visible document shelf support in the UI
• Added agent modes:
  • build for direct implementation
  • plan for read-first analysis
  • research for stricter source-backed investigation
• Added richer research UX:
  • source cards under research-heavy answers
  • live activity phases
  • diagnostics footer
  • progress/debug report export from Help/About
• Improved provider and session error handling so common configuration issues surface as UI notifications instead of noisy console failures
• Expanded cross-platform packaging and CI workflows for Windows, macOS, and Linux artifacts

Highlights

• Multi-provider runtime
  • Ollama
  • OpenAI
  • Anthropic
  • OpenAI-compatible APIs such as LM Studio, OpenRouter, Groq, Together, DeepSeek, vLLM, and LocalAI
• Native tool calling when a provider supports it
• Emulated tool calling when a model does not support tools natively
• Workspace-scoped permissions
  • read_only
  • ask
  • full_access
• Agent modes
  • build
  • plan
  • research
• Built-in tools
  • fs_list
  • fs_read
  • fs_write
  • fs_patch
  • fs_mkdir
  • fs_delete
  • search_text
  • run_command
  • web_search
  • web_fetch
  • browser_fetch
• MCP server support from Settings
• Stdio plugin support
• Conversation search palette
• Persistent threads, settings, and runtime state
• Multi-language UI with English default
  • en
  • tr
  • de
  • es
  • ru
• Attachment reuse across a thread
• Cross-platform packaging targets
  • Windows x64 portable
  • macOS x64 + arm64
  • Linux x64 AppImage + deb
• Document extraction for:
  • pdf
  • docx
  • xlsx
  • pptx
  • odt
  • ods
  • odp

Desktop UX

• Custom top chrome with app-style controls
• Composer with provider, agent mode, permission, model, and attachment controls
• Live progress feed for tool execution
• Live activity phases such as searching, fetching, reading, analyzing, and waiting approval
• Approval flow for risky tools in ask mode
• Change summary cards after file edits
• Thread attachment/document shelf for reusing previously added files
• Source cards for research-heavy answers
• Exportable progress/debug reports from Help and About
• Structure-first web fetch with title, description, heading outline, and link previews

Architecture

src/
  core/
    agent/        Agent loop, tool orchestration, approvals, context management
    providers/    Ollama, OpenAI-compatible, Anthropic, provider registry
    tools/        Filesystem, command, search, web, document extraction
    mcp/          MCP stdio integration and registry
    plugins/      Stdio plugin loading
  main/
    main.js       Electron main process and IPC
    preload.js    Safe renderer bridge
    session-service.js
                  Session lifecycle, persistence, provider/model management
  renderer/
    app.js        Main UI
    styles.css    Main styles
test/
  unit and runtime behavior tests
plugins/
  echo/           Example stdio plugin

Requirements

• Node.js >= 24
• Electron ^35
• Ollama for local Ollama sessions
• Python 3 for structured document reading from PDFs and office files
• Python packages from requirements-docs.txt for PDF and Office extraction
• Optional API keys for hosted providers:
  • OpenAI
  • Anthropic
  • Any OpenAI-compatible endpoint that requires authentication

Official Platform Targets

• Windows x64
• macOS x64 and arm64
• Linux x64

Kali Linux is covered through the Debian-style deb package target.

Getting Started

Install dependencies:

npm install

Install document-reading Python dependencies:

python -m pip install -r requirements-docs.txt

Start the app:

node --run start

Run tests:

node --test

Build Outputs

Build for the current Windows host:

npm.cmd run build:win

Build on macOS:

npm run build:mac

Build on Linux:

npm run build:linux

Expected artifacts:

• ForgePilot-<version>-win-x64.exe
• ForgePilot-<version>-mac-x64.dmg
• ForgePilot-<version>-mac-arm64.dmg
• ForgePilot-<version>-linux-x64.AppImage
• ForgePilot-<version>-linux-x64.deb

Native Release Automation

The repository includes GitHub Actions workflows for native multi-platform validation and packaging:

• .github/workflows/ci.yml
  • runs node --test on Windows, macOS, and Ubuntu
• .github/workflows/release.yml
  • builds native artifacts on:
    • windows-latest
    • macos-latest
    • ubuntu-latest

This is the recommended path for final macOS and Linux release artifacts, since electron-builder only supports macOS packaging on macOS and Linux distributables are most reliable on a native Linux runner.

Provider Notes

Ollama

• Best for local workflows
• Supports both native and emulated tool loops
• Make sure the Ollama service is running before opening a session

OpenAI / Anthropic

• Add API credentials in Settings > General
• Model refresh now reports missing credentials in the UI instead of crashing

OpenAI-compatible providers

Use this for local or hosted endpoints that expose an OpenAI-style API surface. Examples:

• LM Studio
• OpenRouter
• Groq
• Together
• DeepSeek
• vLLM
• LocalAI

MCP Support

You can add stdio MCP servers from Settings > MCP.

For each server you can configure:

• Name
• Command
• Arguments
• Working directory
• Environment variables

Once connected, discovered MCP tools become available to the agent runtime just like built-in tools.

Attachments and Documents

Files added in a conversation are copied into a session attachment area so the agent can reuse them in later turns. This includes documents outside the current workspace.

The runtime supports:

• Re-reading previously attached files
• Resolving attachment aliases and filename-only references
• Extracting readable text from PDFs and office documents
• Showing reusable thread attachments in the renderer
• Including richer document metadata in progress summaries when available

Web Research

ForgePilot includes two built-in web tools:

• web_search
• web_fetch
• browser_fetch

web_fetch follows a structure-first approach inspired by browser automation tools such as FSB: besides plain text, it returns the page title, meta description, canonical URL, heading outline, and a compact link preview list. That gives weaker local models more reliable page context than a raw text dump alone.

browser_fetch is the heavier fallback path for pages that are blocked, highly dynamic, or incomplete through a normal fetch. The research runtime now prefers exact discovered search results and applies stronger guards against hallucinated URLs in emulated tool mode.

Acceptance Tests

To run the real Ollama acceptance flow:

$env:RUN_OLLAMA_ACCEPTANCE='1'
node --test test/ollama-acceptance.test.js

Known Limits

• Hosted provider support depends on the target endpoint correctly implementing its API contract
• Some weaker local models may still overuse search or produce unstable tool envelopes
• macOS and Linux packaging should be generated on their native host OS for the most reliable release artifacts
• UI is optimized for desktop usage first

Development Notes

• State is persisted locally between restarts
• Running tool traces are cleaned up on stop and app shutdown
• Renderer notifications are used for provider and runtime errors instead of console-spam for common user-facing issues
• Research runs now require at least one successful fetched source before final write-heavy output is accepted in standard web research flows
• research mode pushes the agent toward multi-source synthesis before it finalizes a web-backed answer
• plan mode hides workspace-changing tools from the model and keeps the loop in analysis-first behavior
• Progress export can be used to inspect web/tool behavior when debugging model decisions