Soulforge
Graph-powered code intelligence, multi-agent coding with codebase-aware AI. No more grep & pray
Ask AI about Soulforge
Powered by Claude · Grounded in docs
I know everything about Soulforge. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
The agent that treats code as code
~5 tokensto change a function return type(AST edit vs ~100 lines of oldString) | ~$0average compaction cost(V2 extracts as you go) | 34 → 5messages after compactionwith 0 LLM tokens spent |
Every other AI coding tool treats your codebase as text. It greps, it pastes 500-line files into context, it builds oldString/newString blobs and prays the whitespace matches. Half the turn is orientation. The other half is string-matching roulette.
SoulForge treats code as code. On startup it parses your project into a live Soul Map — every file, symbol, import edge — ranked by PageRank and git co-change. Forge opens every turn oriented: it reads single symbols by name (not whole files), edits TS/JS through the AST (symbol kind + name, 65+ ops, zero text matching), and rewrites the rest with line-anchored edits that never drift.
What that means in practice:
ast_editchanges a return type withvalue: "Promise<User>"— nooldString, no whitespace failures, no line-offset math.- Reads pull one function by name, not an 800-line dump. Context stays lean.
- V2 compaction serializes structured state as the conversation happens — when context fills, it compacts for free.
- Sub-agents share a read cache, so 3 parallel explorers don't re-open the same file 3 times.
Same work, a fraction of the tokens, a fraction of the seconds.
Not your average CLI
🧠 Live Soul MapSQLite graph of every file, symbol, and import — PageRank-ranked, git-co-change-aware, personalized per turn. Renders into the system prompt with blast radius tags so the agent knows which edits ripple. Learn more |
🔪 Surgical reads across 33 languagesRead a single function by name. A 500-line file becomes a 20-line extraction. TypeScript, Python, Rust, Go, Java, Ruby, C/C++, Swift, Kotlin, Elixir, Zig, Solidity, and more. Learn more |
🤖 Parallel agents with shared cacheForge dispatches explore, code, and web-search agents in parallel. Files one reads are cached for the others — 3 agents don't re-read 3x. Real-time findings propagate between them. Learn more |
💰 Free compactionV2 compaction tracks structured state as the conversation happens — files touched, decisions, failures, tool results. When context fills up, serialization is instant and typically costs zero LLM tokens. Learn more |
🎯 One call, complete job
|
🔬 AST-native editing
|
📝 Your Neovim, embeddedReal Neovim in a PTY — your config, your plugins, your LSP servers. Agent edits route through the same editor you use. Over SSH, in tmux, wherever. |
🎚️ Mix-and-match modelsHaiku for exploration. Sonnet for code. Flash for compaction. The task router wires a different model to each job — cheap work goes to cheap models. 21 providers + any OpenAI-compatible API. |
📱 Reach your forge from anywhereHearth turns a running SoulForge into a remote agent. Telegram or Discord. Tap-to-approve for destructive ops, auto-redaction of secrets. Your code never leaves your host. Learn more |
↶ Undo any turnEvery prompt is a checkpoint. |
📑 Tab-aware file claimsUp to 5 tabs per project with independent model, mode, session, and checkpoints. Tabs see each other's claimed files and active agents. Git hard-blocks during cross-tab dispatch, partial commits are impossible. Learn more |
🪝 Drop-in Claude Code hooks13 lifecycle events (PreToolUse, PostToolUse, compaction, subagents). Reads your existing |
🔌 MCP-compatibleAny Model Context Protocol server works out of the box. stdio, HTTP, SSE. Auto-reconnect, namespaced tools. Learn more |
🧩 SkillsInstall domain-specific skills with |
And a lot more
- Steering — type while the agent works, messages inject mid-stream. More
- Lock-in mode — hide narration, show only tool activity and final answer
- Inline images — pixel-perfect images and animated GIFs via Kitty graphics protocol
- 24 themes — Catppuccin, Dracula, Gruvbox, Nord, Tokyo Night, Rose Pine, and more. Hot-reload custom themes. More
- Floating terminals — Ghostty-powered PTYs next to the chat
- Plan mode — research, write a structured plan, you approve, then execute. More
- Memory — persistent SQLite memory across sessions, scoped per project or global
- Pre-commit enforcement —
git commitauto-runs lint + typecheck; fails block the commit - 100 slash commands — full reference
Install
brew tap proxysoul/tap && brew install soulforge
macOS and Linux. Neovim and a Nerd Font auto-install on first launch.
Windows: not natively supported. Use WSL for now. Tracked in #57.
Other install methods
# Bun (global)
bun install -g @proxysoul/soulforge
# Prebuilt binary
# download from https://github.com/ProxySoul/soulforge/releases/latest
tar xzf soulforge-*.tar.gz && cd soulforge-*/ && ./install.sh
# Source
git clone https://github.com/ProxySoul/soulforge.git && cd soulforge && bun install && bun run dev
Get a key
Pick any one.
soulforge --set-key llmgateway sk-... # one key for every major model, up to 30% off frontier
soulforge --set-key anthropic sk-ant-... # or any individual provider you already have
soulforge # launch, Ctrl+L to pick a model
All providers · Custom providers
How it compares
| SoulForge | Claude Code | Codex CLI | OpenCode | |
|---|---|---|---|---|
| Codebase awareness | Live SQLite graph — PageRank + git co-change, blast-radius tags, per-turn personalization | File reads + grep | File reads + grep | File reads + grep |
| Cost tactics | Surgical reads, parallel shared cache, free V2 compaction, model-per-task router | Auto-compaction | Server-side compaction | Auto-compaction |
| Code intelligence | LSP → ts-morph → tree-sitter → regex, 33 languages, Mason installer (576+ servers) | LSP via plugins | — | LSP auto-load |
| Editor | Embedded Neovim — your config | — | — | — |
| Remote control | Hearth: Telegram, Discord | — | — | — |
| Multi-agent | Parallel dispatch + shared cache + edit coordination | Subagents + Teams | Multi-agent v2 | Multi-session subagents |
| Hooks | 13 events, Claude Code drop-in compatible | Hooks (PreToolUse, etc.) | — | — |
| Providers | 21 + any OpenAI-compatible | Anthropic only | OpenAI only | 75+ via Models.dev |
| License | BSL 1.1 (converts to Apache 2.0 in 2030) | Proprietary | Apache 2.0 | MIT |
Verified April 2026. Report inaccuracies.
Real numbers
All from SoulForge's own codebase, on Claude Sonnet 4.6:
| Rename a class across 8 files | 19 steps, $0.228 (text edits) → 3 steps, $0.036 (rename_symbol) |
| Change a function return type | ~100 lines of oldString/newString → ~5 tokens with ast_edit |
| Compact a 34-message session | V1 LLM summary: ~8k output tokens, 5-15s → V2: 0 tokens, instant |
| Post-compaction conversation | 4.5M prompt tokens → 7.5k tokens (context utilization 6% → 4%) |
Claude Code's Explore subagent averages ~$0.70 per 5-minute research run with Haiku. SoulForge matches it when you route spark to Haiku via the task router — with the added benefit of full repo-map context.
Try it
brew tap proxysoul/tap && brew install soulforge
cd your-project
soulforge
Then:
> rename AgentBus to CoordinationBus across the project
> run tests and commit
Pair a Telegram/Discord bot once with /hearth pair, then keep chatting from your phone — the session auto-syncs both ways.
Full docs at soulforge.proxysoul.com.
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.