Warning
This project is currently in active development (Beta). APIs, CLI commands, and internal architectures are highly unstable and subject to change without notice. Please use with caution and ensure you have committed your work to version control before running Wildcode.
Wildcode is an advanced, agentic CLI coding assistant designed to help you analyze, plan, and confidently refactor large codebases. By leveraging a multi-agent "Tribunal" review system and deep semantic indexing, Wildcode acts as a true pair-programming partner that enforces structural integrity and strict domain constraints before touching a single file.
The Origin of Wildcode & API Flexibility: The primary motivation behind this project was to explore the absolute limits of running capable AI coding agents on memory-constrained devices. The name "Wildcode" was inspired by a good friend named Wild, who is known for being incredibly frugal yet fiercely logical. This perfectly mirrors the core philosophy of the tool: being extraordinarily frugal with memory (VRAM/Context Windows) while unlocking maximum, robust AI logic. It employs a "Disk/Time for Memory" tradeoff—utilizing persistent disk storage and multi-node execution to navigate massive codebases without exhausting context limits. While highly optimized for local LLMs, Wildcode fully supports ANY AI service that complies with the standard OpenAI API specification (e.g., OpenAI, LM Studio, vLLM, Groq, Together).
Wildcode was built with four core philosophies in mind:
Instead of letting a single LLM blindly write code to your disk, Wildcode implements a Polymath Expert Tribunal.
- A Lead Engineer drafts the code changes based on your plan.
- A dynamically assembled Technical Reviewer (with multiple cross-domain perspectives) acts as a strict auditor.
- AI-Driven Polyglot Scoped Compilation: Wildcode goes beyond static analysis by running actual compiler checks (e.g.,
tsc,go build,cargo check). It uses a background LLM to automatically detect your project's language and infer the correct CLI tools. Crucially, it performs Scoped Verification, meaning it filters the compiler output to only catch errors inside the exact files the AI just modified, preventing the AI from getting blocked by preexisting global errors in your project. - If the draft fails, it is VETOED and returned to the Lead Engineer for fixing with the exact compiler errors attached. Only completely aligned patches are ever committed to disk.
A coding assistant needs more than simple text search. Wildcode builds a Semantic Index of your entire project.
- It parses your AST (symbols, roles) and groups files into logical modules.
- It summarizes business logic, implicit dependencies, and potential risks for every module.
- It uses a token-budgeted Map-Reduce architecture to handle files of any size without losing context, gracefully chunking and merging ultra-large files to maintain inference fidelity.
- Dynamic Retrieval (RAG): If the project scales to dozens of modules, Wildcode dynamically filters the semantic map using a lightweight LLM routing agent. It perfectly partitions and retrieves only the Top 5 most relevant modules for your immediate task, ensuring maximum focus and zero context-overflow.
Your codebase changes rapidly. Wildcode uses SHA-256 content hashing on file contents and prompt states to skip unchanged modules when rebuilding the semantic index. This dramatically reduces API token costs and speeds up continuous development loops.
Wildcode strictly separates "Intelligence" from "Execution". The AI is restricted from running unsafe shell commands or directly mutating files. Instead, it must generate patches in a strict, system-defined DSL (<<<<<<< SEARCH, =======, >>>>>>> REPLACE, and <<<<<<< DELETE). The robust Node.js parser on your machine securely interprets this DSL, ensuring changes are perfectly confined to the writeScope approved by you.
Wildcode is specifically optimized to prevent context-window amnesia and VRAM exhaustion, making it perfect for local, privacy-first AI models while retaining seamless compatibility with any OpenAI API-compliant endpoint. By heavily decomposing complex coding tasks into granular, rigidly token-budgeted chunks and dynamically filtering context (RAG), Wildcode ensures maximum reliability regardless of the backend provider.
- Pure Ephemeral State Architecture: Wildcode leaves zero footprint in your project repo. It uses a purely in-memory execution loop for sessions, drafts, and AST trees, which are garbage-collected instantly. Global API keys are stored securely in
~/.wildcode/config.json, while your local.wildcode/directory only caches essential map files.
The explicit goal here is to minimize RAM footprint. On Unified Memory devices (like Macs), Wildcode leaves enough memory available so you can keep your favorite background apps running—like YouTube, Docker, and countless browser tabs—without your computer's fans spinning out of control while the AI writes code. For example, Wildcode is designed to run fluently on a MacBook Pro M4 Pro (24GB RAM) using models like Gemma4-26B-A4B-it-4bit via oMLX.
When you ask for a massive refactoring task, Wildcode does not naively stuff everything into one context window. Instead, it utilizes a Node-based orchestration pipeline. By mapping specific task intents to isolated execution contracts (Nodes), Wildcode dynamically limits the context window to only the exact files and prompts needed for that specific operation. This acts as an absolute safeguard against VRAM exhaustion on local hardware and ensures maximum precision.
A CLI tool should be a joy to use. Wildcode features a modern, beautifully structured interface using tasteful Unicode box-drawing and semantic iconography. It avoids heavy, distracting animations in favor of a clean, dashboard-like experience that keeps you focused on the code and system status.
Wildcode uses pnpm as its primary package manager.
# Install dependencies
pnpm install
# Build the project (if running the compiled version)
pnpm buildYou can start Wildcode directly in development mode using tsx:
pnpm dev(Alternatively, you can link the wildcode bin locally).
Once the Wildcode interactive session starts, you'll be greeted with a ❯ prompt. You can describe what you want the AI to do (e.g., "Refactor the authentication flow"), or use the built-in slash commands:
/help(or just/) Shows the help menu with all available commands directly in the terminal./initAnalyzes your entire project to build or update the deep "Semantic Index". It groups files into logical modules so the AI understands your project architecture./statusShows whether your Semantic Index is loaded and displays any currently pending AI task plan./diffShows a standardgit diffof all the code changes the AI has written to your local files so far./modelChange the AI model used for execution (e.g./model gemma-4-26b-a4b-it-4bit). You can provide the model name directly or just type/modelto be prompted./endpointUpdate the OpenAI-compatible API base URL (e.g. your local LM Studio or vLLM server address)./modeToggle betweeninteractive(review-first) andauto(auto-execute) modes./exitSafely exits the Wildcode session.
💡 Pro-Tip: When Wildcode proposes a plan, you don't need a slash command—simply type
yto approve and execute it, ornto cancel it. The CLI also supports standardreadlineautocomplete!
src/cli/: The main entry points, REPL loop, and interactive prompt handling.src/map/: The core Semantic Indexing engine (AST parsing, file chunking, incremental hashing).src/runtime/: The multi-agent orchestrator, including theTribunalreview loops and context gathering.src/patch/: The strict DSL parser and file mutator that applies accepted changes.src/contracts/: Defining the strict schemas, JSON formats, and safety rules that guide LLM outputs.
This project is licensed under the Apache License 2.0.