Introducing SoulForge: Graph-Powered Code Intelligence

Today I'm releasing SoulForge, graph-powered code intelligence for the terminal.

Why I built this

I use AI coding agents daily. Claude Code, Copilot, Codex. They're genuinely good. But I kept hitting the same wall: I couldn't fully trust them.

Not because the models are bad. Because the agents don't understand what they're touching. They read a file, grep for a pattern, make an edit, and move on. They don't know that 30 files depend on the function they just renamed. They don't know that two files always change together. They don't know which parts of the codebase matter most right now.

I wanted an agent that thinks about code the way an architect does. Not file by file, but as a system with structure, coupling, and consequences. An agent that can answer "what breaks if I change this?" before it changes anything.

That's what trust requires. Not better prompts. Better understanding.

The Soul Map

When you open a project, SoulForge parses every file across 30+ languages with tree-sitter, extracts symbols and imports, and builds a live dependency graph backed by SQLite.

The agent sees a Soul Map: every file ranked by importance, with exported symbols, signatures, and dependency arrows. Before it reads a single file, it already knows which files matter most, what changes together, how far an edit ripples, and what symbols exist where.

The graph updates in real-time. Edit a file and the agent sees the current state on the next turn.

And when it does need to read code, it doesn't read whole files. It pulls exactly the function or class it needs by name. A 500-line file becomes a 20-line symbol extraction. The Soul Map provides line numbers and signatures, so the agent always knows precisely what to ask for.

How the Soul Map works →

Tools that work with the graph

Most AI coding tools give the agent grep and read_file and hope for the best. SoulForge gives the agent tools that query the graph directly: soul_grep, soul_find, soul_analyze, soul_impact. Answered from SQLite in milliseconds, zero LLM tokens burned.

The agent doesn't grep and read 20 files to understand a module. It asks the graph "what depends on this?" and gets an answer with file paths, symbol names, and blast radius in one call.

4-tier code intelligence

The graph handles structure. For precise code operations, SoulForge routes through four tiers: LSP → ts-morph → tree-sitter → regex.

The agent gets the full LSP surface as tools. Go-to-definition, find references, workspace rename, call hierarchy, type hierarchy, diagnostics, code actions, formatting. When LSP isn't available, the intelligence router falls through gracefully.

This powers compound tools that do the complete job in one call: read batches multiple files in parallel with surgical symbol extraction, multi_edit applies multiple edits atomically, rename_symbol does LSP workspace rename with verification, move_symbol moves code between files and updates all importers, rename_file moves files with import path updates, and project auto-detects your toolchain across 23 ecosystems.

One tool call replaces a dozen grep-read-edit cycles.

Compound tools reference →

Parallel agents that coordinate

When a task spans many files, SoulForge dispatches parallel agents through a shared bus. Two tiers: Sparks (explore/investigate, read-only, share the forge's cache prefix for zero cold-start cost) and Embers (code agents, own model, full edit capabilities).

Agents share a file cache, post findings to each other in real-time, and coordinate edits. Up to 8 agents, 3 running concurrently. Optional post-dispatch passes: a cleanup agent reviews edits in fresh context, a verify agent checks correctness.

You can also run multiple tabs side by side with different models and modes per tab. Agents see what other tabs are editing and git operations coordinate automatically.

Agent Bus deep dive →

Context that doesn't rot

AI tools are great for 10 minutes. Hour-long sessions are where they break. Context fills up, old tool results pile on, every API call sends 100K tokens of stale content.

SoulForge tracks working state deterministically from tool calls: files touched, decisions made, errors hit. When context fills up, it compacts from this pre-built state. No LLM call, no latency, no cost. Old tool results get pruned to one-liners enriched with Soul Map symbols. Sessions save incrementally and survive crashes.

Compaction deep dive →

Your Neovim, embedded

I wanted to stay hands-on with the code. Not just watch a chat window, actually co-edit alongside the agent.

SoulForge embeds real Neovim via msgpack-RPC. Your config loads. Your plugins work. LazyVim, Mason, Catppuccin, treesitter, all of it. The AI and the editor share the same LSP connection. When you rename in Neovim, the agent sees it. When the agent edits, you see it in the buffer.

Toggle the editor closed and the intelligence router falls back to standalone LSP servers automatically. Open it back up and they reconnect.

It works over SSH. tmux, screen, remote servers. No Electron, no X11 forwarding. SoulForge is a terminal app.

24 themes

Ships with 24 builtin themes including Catppuccin, Dracula, Gruvbox, Tokyo Night, Nord, Rose Pine, Kanagawa, and more. Create your own with a JSON file. Themes hot-reload instantly.

Cost transparency

You see exactly what you're spending per-task, per-agent, per-model. The task router lets you assign different models to different jobs. Put Opus on complex code, Haiku on search and cleanup. You choose what goes where.

Lock-in mode

Hides agent narration during work, shows only tool activity and the final answer. Toggle via /lock-in or config. When you don't need to watch the agent think, just see what it does and what it produces.

Safety built in

• Approval gates. rm -rf, git push --force, edits to .env or credentials, individually prompted every time. No "Always Allow" button.
• Forbidden files. .env, *.pem, *.key, credentials.json blocked across every tool. The LLM never sees your secrets.
• Pre-commit gate. Auto-runs lint and typecheck before any git commit. Broken commits don't happen.

Everything works headless

soulforge --headless "fix the auth bug"              # Stream to stdout
soulforge --headless --json "add rate limiting"       # Structured JSON
soulforge --headless --events "refactor auth"         # Real-time JSONL events
soulforge --headless --chat                           # Multi-turn interactive
echo "prompt" | soulforge --headless                  # Pipe from stdin

Exit codes: 0 success, 1 error, 2 timeout, 130 abort. Designed for CI/CD, scripting, and automation.

The numbers

Get started

# Homebrew (macOS / Linux)
brew tap proxysoul/tap && brew install soulforge
 
# Bun (global install, requires Bun >= 1.2)
curl -fsSL https://bun.sh/install | bash   # install Bun if needed
bun install -g @proxysoul/soulforge
 
soulforge   # or: sf

• Docs: soulforge.proxysoul.com
• Repository: github.com/proxysoul/soulforge

If you've ever wished you could trust your AI coding agent to understand what it's touching before it touches it, give it a try.

- ProxySoul