Getting Started — Forage Docs

System Requirements

Requirement	Minimum	Recommended
OS	macOS 12, Windows 10, Ubuntu 20.04	Latest stable release
Node.js	18.0	20 LTS or later
RAM	2 GB	8 GB+ for large codebases
Disk	500 MB free	2 GB+ for graph storage

Installation

Download the Forage installer for your platform and run it, or install via npm:

Terminal

npm install -g @squrl/forage

Terminal

brew install squrl-labs/tap/forage

PowerShell

winget install SqurlLabs.Forage

Terminal

curl -fsSL https://get.squrl-labs.com/forage | sh

Verify the installation:

Terminal

forage --version

Initializing a project

Navigate to your project root and run:

Terminal

forage --init

This creates a forage.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:

Server	Default URL	Purpose
Web UI	`http://localhost:9988`	Graph explorer, AI chat, file editor
MCP Server	`http://localhost:9989/mcp`	AI 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
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

Next step: Connect your AI agent to Forage via the MCP server. See MCP Integration to get 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 --init.

To manually trigger a full re-index:

Terminal

forage --reindex

To stop the Forage servers:

Terminal

forage --stop