Why SoulForge?

Every AI coding tool starts blind. It reads files, greps around, slowly builds a mental model of your codebase. You wait. You pay. The agent is doing orientation work, not real work.

SoulForge already knows. On startup it builds a live dependency graph of your entire codebase: every file, symbol, import, and export, ranked by PageRank importance, enriched with git co-change history, updated in real-time as files change. The agent knows which files matter, what depends on what, and how far an edit will ripple before it writes a single line. It's faster. It's more accurate. And it costs less.

Faster, smarter, cheaper

How it compares

Verified March 29, 2026. Report inaccuracies.

Installation

macOS and Linux. First launch checks for prerequisites and offers to install Neovim and Nerd Fonts.

Homebrew (recommended)

brew tap proxysoul/tap
brew install soulforge

curl -fsSL https://bun.sh/install | bash
bun install -g @proxysoul/soulforge
soulforge

Download from Releases:

tar xzf soulforge-*.tar.gz && cd soulforge-*/ && ./install.sh

Installs to ~/.soulforge/, adds to PATH.

Ships Neovim 0.11, ripgrep, fd, lazygit, tree-sitter grammars, Nerd Font symbols. Zero system deps.

git clone https://github.com/ProxySoul/soulforge.git && cd soulforge && bun install
./scripts/bundle.sh              # macOS ARM64
./scripts/bundle.sh x64          # Intel Mac
./scripts/bundle.sh x64 linux    # Linux x64
./scripts/bundle.sh x64-baseline linux  # Linux x64 (older CPUs)
./scripts/bundle.sh arm64 linux  # Linux ARM64
cd dist/bundle/soulforge-*/ && ./install.sh

Requires Bun >= 1.0 and Neovim >= 0.11.

git clone https://github.com/ProxySoul/soulforge.git && cd soulforge && bun install
bun run dev          # development mode
# or
bun run build && bun link && soulforge

Quick start

soulforge                                  # launch, pick a model with Ctrl+L
soulforge --set-key anthropic sk-ant-...   # save a key
soulforge --headless "your prompt here"    # non-interactive

See GETTING_STARTED.md for a full walkthrough.

Usage

soulforge                                    # TUI
soulforge --headless "prompt"               # stream to stdout
soulforge --headless --json "prompt"        # structured JSON
soulforge --headless --chat                 # multi-turn
soulforge --headless --model provider/model # override model
soulforge --headless --mode architect       # read-only
soulforge --headless --diff "fix the bug"   # show changed files

Full CLI reference

Providers

Amazon Bedrock uses AWS IAM credentials. Set AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION (defaults us-east-1). Supports AWS_SESSION_TOKEN for temporary creds.

GitHub Copilot: sign in via IDE, copy oauth_token from ~/.config/github-copilot/apps.json, save with /keys or --set-key copilot. Full guide.

GitHub Models: free playground API, per-token billing. Fine-grained PAT with models:read. Lower rate limits than Copilot.

Ollama: auto-detected at localhost:11434. Override with OLLAMA_HOST.

LM Studio: auto-detected at localhost:1234. Override with LM_STUDIO_URL. Optional auth via LM_API_TOKEN.

Custom providers via config:

{
  "providers": [{
    "id": "my-provider",
    "name": "My Provider",
    "baseURL": "https://api.example.com/v1",
    "envVar": "MY_PROVIDER_API_KEY",
    "models": ["model-a", "model-b"]
  }]
}

Custom providers / Provider options

Configuration

Layered: global (~/.soulforge/config.json) + project (.soulforge/config.json).

{
  "defaultModel": "anthropic/claude-sonnet-4-6",
  "thinking": { "mode": "adaptive" },
  "repoMap": true,
  "taskRouter": {
    "spark": "anthropic/claude-sonnet-4-6",
    "ember": "anthropic/claude-opus-4-6",
    "webSearch": "anthropic/claude-haiku-4-5",
    "desloppify": "anthropic/claude-haiku-4-5",
    "compact": "google/gemini-2.0-flash"
  },
  "instructionFiles": ["soulforge", "claude", "cursorrules"]
}

Drop a SOULFORGE.md in your project root for conventions, architecture notes, preferences. Also reads CLAUDE.md, .cursorrules, AGENTS.md. Toggle via /instructions.

See GETTING_STARTED.md for the full config reference.

Documentation

Roadmap

Extracting the intelligence layer into reusable packages:

• @soulforge/intelligence : graph intelligence, tools, agent orchestration as a library
• @soulforge/mcp : Soul Map tools as MCP servers for Claude Code, Cursor, Copilot, any MCP client
• sf --headless : shipped. Docs

Inspirations

• Aider : tree-sitter repo maps with PageRank. SoulForge adds cochange, blast radius, clone detection, live updates.
• Everything Claude Code : enforce behavior with code, not prompts.
• Vercel AI SDK : multi-provider abstraction.
• Neovim : embedded via msgpack-RPC. Your config and muscle memory intact.

License

Business Source License 1.1. Free for personal and internal use. Commercial use requires a commercial license. Converts to Apache 2.0 on March 15, 2030.