arcKode brings structural understanding to local AI coding
Most local AI coding tools treat a project as a flat wall of text. arcKode takes a different approach. It parses the codebase with Tree-sitter to build a live symbol graph, then uses that graph to scope exactly what the model needs to see. The result is precise edits grounded in the code's actual structure rather than hallucinated file paths.
Semantic parsing across 11 languages
arcKode understands code at the symbol level. It parses Python, JavaScript, TypeScript, Go, Rust, Java, C#, Kotlin, Swift and more using Tree-sitter parsers. Each language gets a dedicated parser — tree-sitter-python, tree-sitter-javascript, tree-sitter-typescript and so on. The parser extracts functions, classes, imports, call edges and other symbols. Each symbol gets metadata including byte ranges, dependencies and summaries. This structural understanding is the foundation for everything else the tool does.
Token-aware context packing fits maximum signal into a fixed budget
LLMs have limited context windows, and arcKode optimizes what goes into that window. It uses reciprocal-rank fusion with exact-name boosting to select the most relevant symbols while staying within the token budget. The system calculates a token budget as context_window minus reserved_output_tokens minus system_prompt_tokens. With defaults of 8192 context window, 4096 reserved output tokens and 2048 system prompt tokens, the effective budget is 2048 tokens. This ensures the model sees the most relevant code without wasting space on irrelevant files.
Two-mode operation for different task sizes
arcKode offers two modes depending on the task's complexity. Single-shot mode handles surgical changes — renaming a variable, extracting a module, adding middleware. The model sees just the code it needs and produces an edit. Multi-step planner+coder mode handles complex refactors. The planner breaks the work into ordered steps, and at each step the coder produces a patch with confirmation before moving to the next step. This two-mode design means the tool is useful for both quick fixes and large-scale changes.
Built-in safety features
Writing code with AI carries risks, and arcKode includes several safeguards. Automatic snapshots take effect before every write, so a bad edit can be reverted. Anchored edits with occurrence control prevent unintended changes across the codebase. Path containment checks ensure edits stay within the intended scope. These features operate by default, adding a layer of safety without requiring the user to manually verify every change.
Incremental indexing keeps summaries current
Codebases change, and arcKode handles this with incremental indexing. SHA-256 change detection identifies which files have modified since the last run. Only those files get re-processed, and their summaries persist across runs. This means the tool stays up to date without re-indexing the entire project every time it launches.
Local-first with zero external dependencies
arcKode runs entirely on the user's machine. LLMs are exposed via Ollama locally; no API keys, no cloud calls, and no data leaves the machine. This local-first design addresses privacy concerns and works offline. The recommended model is qwen2.5-coder:7b, but the tool works with any Ollama-compatible model. Prerequisites are Python 3.12+, Ollama running locally, and uv for dependency management.
Installation and daily use
Getting started requires a few steps. First, clone the repository and install runtime dependencies with uv sync. Pull the desired model with ollama pull. Install the tool as a uv tool with uv tool install . Then index your project with arckode index and start coding with arckode do "your task description here". The uv tool install step is intentional friction — it ensures the user runs the exact code they audited.
Once running, several commands support daily workflows. arckode show plan displays the last execution plan. arckode show context --query "authenticate" searches indexed symbols. arckode show index exports the full codebase JSON. arckode config reads or overrides settings like model selection or think level. The configuration file follows precedence: environment variable ARKCODE_CONFIG, then ./arkrc project-local, then ~/.config/arckode/config.json user global. A typical config object includes ollama_url, coder_model, planner_model, context_window, reserved_output_tokens, system_prompt_tokens, think_level and think_overrides.
How the tool processes a request
When a user submits a task, the system follows a structured flow. The user request expands into a query, then keyword search narrows the scope. The context packer selects and orders the most relevant code symbols within the token budget. The coder model produces JSON patches for the changes. These anchored edits are applied against live source positions, with snapshots created before any write. Finally, the index re-indexes incrementally to reflect the changes.
An architectural diagram in the source illustrates this flow: user request → query expansion → keyword search → context packer → coder model → anchored edits → re-index. Each stage has a specific responsibility, and the incremental re-index ensures the symbol graph stays consistent with the codebase.
Index structure and supported languages
The index lives in .vc/vcdb.db with three tables. The files table records path, hash, language, size and imports for each source file. The blocks table stores symbol metadata, byte ranges, dependencies and summaries. The blocks_fts table provides FTS5 full-text search, though parent_file remains unindexed. A language reference table maps extensions to parsers: Python uses tree-sitter-python, JavaScript uses tree-sitter-javascript, TypeScript uses tree-sitter-typescript, Go uses tree-sitter-go, Rust uses tree-sitter-rust, Java uses tree-sitter-java, C# uses tree-sitter-c-sharp, Kotlin uses tree-sitter-kotlin and Swift uses tree-sitter-swift.
AGPL-3.0 license and future direction
arcKode is released under AGPL-3.0-only. The source code is open, and the developers welcome contributions. The tool addresses a growing need for local, privacy-preserving AI coding assistance that understands code structure rather than treating projects as text blobs. With Tree-sitter parsing, token-aware context packing, two-mode operation and built-in safety, it offers a practical approach to AI-assisted development that respects both the user's code and their privacy.