ProxySoul

@BniWael

I Built an AI Coding Agent That Already Knows Your Codebase Before It Reads a Single File

Most AI coding agent starts the same way.

You give it a task, It greps, It reads a file, It greps again, reads three more files then Half its token budget gone, and it still doesn't understand the full architecture.

I spent months watching agents burn through context and time just to figure out where things are. Not because the models are bad. Because they're flying blind. They see files. They don't see systems.

So I built one that does.

What SoulForge Actually Does Differently

When you open a project, SoulForge parses every file across 30+ languages, extracts every symbol and import edge, and builds a live dependency graph backed by SQLite.

Before the agent touches anything, it sees a Soul Map, every file ranked by importance, every exported symbol indexed, every dependency arrow drawn:

Which files matter most, PageRank ranks by structural importance, boosted by your recent edits

What changes together, git cochange analysis catches coupling that imports don't show

How far an edit ripples, blast radius tells the agent "be careful, 30 files depend on this"

Where everything is, full-text search over every symbol with signatures, answered in milliseconds

The graph updates in real-time. Edit a file, the map recalculates. The agent always sees the current state.

This isn't context stuffing. It's understanding.

Tools That Query the Graph, Not the Filesystem

Most agents get grep and read_file and hope for the best. SoulForge gives the agent tools that answer from the graph directly, zero file reads, zero LLM tokens:

soul_find, "where is AuthMiddleware?" → PageRank-ranked results with signatures, instantly

soul_grep, checks identifier frequency in the graph before even spawning ripgrep

soul_analyze, unused exports, file profiles, top files, external packages

soul_impact, "what breaks if I change this?" → dependents, cochanges, blast radius

One graph query replaces a dozen grep-read cycles.

The agent does less work, makes fewer mistakes, and you trust the result more.

Your Conventions, Loaded Once

Drop a SOULFORGE.md in your project root. Architecture notes, naming conventions, toolchain preferences, and it's injected into every prompt.

Already using Claude Code, Cursor, or Copilot? SoulForge loads instruction files from 10 formats: CLAUDE.md, .cursorrules, AGENTS.md, .github/copilot-instructions.md, and more. Your conventions follow you across tools.

Plus installable skills for domain-specific knowledge. The agent knows how your codebase works, not just what's in it.

4-Tier Code Intelligence

For precise operations, SoulForge routes through four tiers: LSP → ts-morph → tree-sitter → regex.

The agent gets the full LSP surface, definitions, references, workspace rename, call hierarchy, diagnostics. When LSP isn't available, it falls through gracefully. Every language always gets the best available intelligence.

This powers compound tools that do the complete job in one call:

rename_symbol, LSP workspace rename with grep verification across all files

move_symbol, extract to another file, update all importers automatically

rename_file, rename/move with import path updates

refactor, extract function/variable, organize imports

One tool call. Not twelve.

Parallel Agents That Actually Coordinate

Big tasks fan out to parallel agents through a shared bus:

Investigate agents scan broadly, counts, patterns, structural analysis

Explore agents extract targeted context from specific files

Code agents edit with full findings already cached

Up to 8 agents, 3 running concurrently. One agent reads a file, every other agent gets it instantly. Edit ownership prevents race conditions. A dependency DAG ensures code agents start with research already done.

The agent decides when to dispatch. Small tasks stay direct. Complex tasks fan out automatically.

Your Actual Neovim, Embedded

This was non-negotiable for me. I wanted to co-edit alongside the agent, not just watch a chat window.

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

It works over SSH. tmux, screen, remote servers. No Electron, no browser. Terminal-native.

10 Providers, Per-Task Routing

LLM Gateway, Anthropic, OpenAI, Google, xAI, Ollama (local), OpenRouter, Vercel AI Gateway, a local proxy, and any custom OpenAI-compatible API.

Per-task model routing sends different tasks to different models automatically. Opus for coding accuracy. Haiku for cheap search queries. Sonnet for planning. Cost visible per task, per agent, per model.

You see exactly what you're spending.

Context That Doesn't Rot

This is where every AI tool breaks down. Hour-long sessions. Context fills up. Every API call sends 100K tokens of stale content.

SoulForge tracks working state deterministically from tool calls. When context fills up: serialize, compress, continue. 80% token reduction. Zero LLM cost. Sessions save incrementally, crash, close, resume from exactly where you left off.

Safety That Isn't Optional

Approval gates on every destructive action, rm -rf, git push --force, edits to .env or credentials. Individually prompted. No "Always Allow" button.

Forbidden files blocked across every tool. The LLM never sees your secrets. Pre-commit gate auto-runs lint and typecheck before any git commit.

The Numbers

33 tools.

30+ languages.

10 providers.

Up to 8 parallel agents.

23 auto-detected toolchains.

21 themes.

86 slash commands.

Headless mode for CI/CD.

BSL 1.1 — free for personal and internal use.

Get Started

Homebrew:

BUN:

Then just run: soulforge

Docs: soulforge.proxysoul.com

Source: github.com/ProxySoul/soulforge

If you've ever wished your AI coding agent understood what it was touching before it touched it, try it.

Disclaimer: SoulForge is in early release, if you face any issues don't hesitate to raise an issue or contibute <3