我如何用 Git Worktrees 和 Docker 建構非同步預測式編譯器

Current AI coding tools have a fundamental workflow problem: they are entirely reactive.

You write a function, you run your test suite, it fails, you copy the error logs, paste them into the AI chat, and wait for a fix. You are the orchestrator, and the AI is just glorified autocomplete.

I wanted an engine that operates entirely in the gap between keystrokes. I wanted a system that detects my unfinished code, spins up a parallel replica of my project, tests it, and patches the broken dependencies before I even hit git commit.

So, I built Shadow-Branch Engine. It is a background daemon that uses Git hardlinks, AST pruning, and zero-trust Docker sandboxing to test and heal your code asynchronously.

Here is how the architecture works under the hood.

1. Bypassing the npm install Bottleneck The biggest challenge of running background tests is environment replication. If I want to test uncommitted changes in the background, I can't just copy the directory—running npm install on a massive node_modules folder takes way too long.

To solve this, Shadow-Branch manipulates the filesystem directly. When you save a file, the daemon triggers a git stash create and instantly mounts a hidden parallel git worktree. It uses OS-level hardlinks to mirror your existing node_modules.

The result? A sub-millisecond, fully isolated replica of your codebase, ready for execution.

1. AST Token Pruning (ts-morph) Passing an entire codebase into an LLM context window to generate tests is incredibly expensive and slow.

Instead of dumping raw text, Shadow-Branch uses the TypeScript Compiler API (ts-morph). When a file is saved, the engine parses the Abstract Syntax Tree (AST), identifies the specific function you modified, and traces its exact dependency graph.

It strips away all unrelated files and comments, sending only the mathematically necessary context to the local AI. This drops the token count by over 90%, making local model execution incredibly fast.

1. The Docker Execution Sandbox Once the AI generates the test suite or a patch, we cannot just run it directly on the host machine. AI-generated code is inherently untrusted.

Shadow-Branch uses the dockerode library to dynamically spin up a lightweight, network-isolated Docker container mapped only to the .shadow-workspace. It executes the test suite inside the container.

If the test fails, the daemon captures the exit codes and routes the error logs back through a local XState state machine for an autonomous healing loop. If the test passes, it surfaces a clean, ready-to-merge patch directly to your IDE.

1. Parallel Fuzzing Swarms Because the engine runs asynchronously, it has the luxury of time that a blocking terminal command does not.

If the AST detects asynchronous operations (Promise.all, database transactions), Shadow-Branch doesn't just run one test. It spins up a swarm of 10 parallel Micro-VMs inside Docker to aggressively fuzz for race conditions. If even one container fails, the patch is rejected.

The Code
I just open-sourced the entire Shadow-Branch Engine today. It is built strictly as a local Node.js daemon with zero dependencies on external, closed-source SaaS platforms.

If you are interested in Git manipulation, AST parsing, or local Docker orchestration, check out the repository. We have several open issues tagged help wanted for adding Python and Rust LSP support.

Repository: https://github.com/hariom123-dev/Shadow-Branch.git

Let me know your thoughts on the architecture in the comments. I'd love to hear how other people are handling local autonomous execution!