Documentation

Getting Started

Get Forage running on your machine in under five minutes.

System Requirements

RequirementMinimumRecommended
OSmacOS 12, Windows 10, Ubuntu 20.04Latest stable release
RAM2 GB8 GB+ for large codebases
Disk500 MB free2 GB+ for graph storage

Installation

Forage ships as a small archive containing two files — the main binary and a companion vec0 extension for vector search. No installer, no runtime required. Download the archive for your platform from the Download page and extract it:

  1. Download forage-win.zip from the Download page.
  2. Extract the archive (right-click → Extract All) to get two files: forage-win.exe and vec0.dll.
  3. Move both files to the same folder on your PATH — they must stay together. Optionally rename forage-win.exe to forage.exe so you can type forage in any terminal.
  1. Download forage-macos.tar.gz from the Download page.
  2. Extract, make executable, and move both files to your PATH:
Terminal
cd ~/Downloads
tar -xzf forage-macos.tar.gz
chmod +x forage-macos
sudo mv forage-macos /usr/local/bin/forage
sudo mv vec0.dylib /usr/local/bin/vec0.dylib
Gatekeeper (first run): Because Forage is not yet distributed via the Mac App Store, macOS may block the first run. Open System Settings → Privacy & Security, scroll down, and click Allow Anyway next to the Forage entry. Alternatively, right-click the binary in Finder and choose Open to bypass Gatekeeper in one step.
  1. Download forage-linux.tar.gz from the Download page.
  2. Extract, make executable, and move both files to your PATH:
Terminal
cd ~/Downloads
tar -xzf forage-linux.tar.gz
chmod +x forage-linux
sudo mv forage-linux /usr/local/bin/forage
sudo mv vec0.so /usr/local/bin/vec0.so

Verify the installation:

Terminal
forage --version

Initializing a project

Navigate to your project root and run:

Terminal
forage --init

This creates a config.json file in your project root and starts the initial indexing pass. Depending on your codebase size, the first index takes between 30 seconds and a few minutes.

Large codebases: If your project has more than 50,000 files, consider setting include paths in your config to limit the initial scope. See Configuration for details.

You can watch indexing progress in your terminal. Once complete, Forage starts two local servers:

ServerDefault URLPurpose
Web UIhttp://localhost:9988Graph explorer, AI chat, file editor
MCP Serverhttp://localhost:9989/mcpAI agent integration endpoint

Using the web UI

Open http://localhost:9988 in your browser. The Forage web UI gives you:

  • Graph explorer — visualize file dependencies, function call graphs, and module relationships
  • AI chat — ask natural-language questions about your codebase ("which functions call the auth middleware?", "find all TODOs in the payment module")
  • File editor — browse and edit files with full syntax highlighting, plus a full Code Assistant with sandboxed edits, an integrated terminal, and inline quick-fixes
  • Annotations — browse all TODO, FIXME, BUG, HACK, and DEPRECATED comments indexed across your project
  • Snapshots — create and compare graph snapshots to track structural changes over time
  • Goals — hand Forage a single high-level goal and let it work autonomously, across many rounds, as a persistent background job
  • Documentation — create and maintain User Documentation and Technical Documentation for your workspace, with AI-assisted generation, rich-text editing, and export to TXT, MD, HTML, DOCX, PDF, or Google Docs
  • Compliance — run AI-powered compliance assessments against your codebase for SOC 2, ISO 27001, GDPR, HIPAA, PCI-DSS, NIST CSF, and SOX frameworks
Next step: Connect your AI agent to Forage via the MCP server. See MCP Integration to get AgentOS, Claude Code, Cursor, or Windsurf querying your graph.

Keeping the graph up to date

By default, Forage watches your project directory for file changes and updates the graph incrementally in the background. You never need to re-run forage init.

To manually trigger a smart incremental update:

Terminal
forage --refresh

To stop the Forage servers:

Terminal
forage --stop

CLI reference

Run forage --help at any time to print the full reference. The complete command set is listed below.

Commands

CommandDescription
forage --initInitialize the current folder as a Forage workspace and start the server
forage --runStart both the web UI and MCP servers in the background
forage --uiStart the web UI server only (no MCP server)
forage --mcpStart the MCP stdio server in the foreground (for direct use by MCP clients)
forage --mcp-httpStart the MCP HTTP+SSE server in the background
forage --refreshSmart incremental update of the knowledge graph
forage --rebuildFull re-crawl from scratch — wipes and rebuilds the entire graph
forage --stopStop the background Forage server for this workspace
forage --restartRestart the background Forage server for this workspace
forage --statusShow whether the background server is running
forage --genkeyGenerate a new API key for the MCP server
forage --diagnosticsPrint version, Node.js version, OS, config summary, and recent errors
forage --install-serviceInstall Forage as an OS startup service (see --mode flag below)
forage --uninstall-serviceUninstall the Forage startup service

Global flags

These flags can be combined with any command.

FlagDescription
--port <n>Web UI port (default 9988)
--mcp-port <n>MCP HTTP port (default 9989)
--no-openDo not auto-open the browser on startup

install-service flags

FlagDescription
--mode <mode>Service mode: run (web UI + MCP, default) or mcp (MCP only)
Goals →