VoidCode

VoidCode is a local-first coding agent runtime inspired by OpenCode and Claude Code.

Status: VoidCode is shipping its first productionized release of the runtime control plane. The current focus is tightening runtime boundaries, improving the execution control plane, and shipping a repeatable end-to-end single-agent loop.

Documentation note: contributor-facing documents at the repository root are in English. Internal design and planning documents under docs/ are currently mostly written in Chinese.

What VoidCode aims to provide

VoidCode is built around a local developer workflow with these core capabilities:

• conversational task execution
• code reading and search
• controlled tool calls and file editing
• approval checkpoints for risky operations
• hooks and observable runtime events
• local session persistence and resume
• a headless runtime separated from CLI and future UI clients

The roadmap remains intentionally narrow: ship a stable, demoable single-agent MVP first, then expand from a runtime-owned control plane rather than growing outward too early.

Quick start

The recommended setup uses uv for Python and Bun for the frontend. Supported Python version: 3.13.

Current state: the repository already has a real CLI → runtime → single-agent loop with multi-step execution, session persistence and resume, and inline approval in TTY mode. Provider-backed execution is the product path by default. Deterministic execution remains available as an explicit test/dev/no-key harness. It also exposes a minimal local HTTP/SSE transport. The TUI and web frontend both exist, but neither is yet at full CLI parity.

# Install toolchain and Python dependencies
mise install
uv sync --extra dev

# Install frontend dependencies
mise run frontend:install

# Explore the CLI
uv run voidcode --help

# Run deterministic explicitly for test/dev/no-key harness workflows
VOIDCODE_EXECUTION_ENGINE=deterministic uv run voidcode run "read README.md" --workspace .

# Run the provider-backed product path after configuring credentials and a model
OPENCODE_API_KEY=... VOIDCODE_MODEL=opencode-go/glm-5 uv run voidcode run "read README.md" --workspace .

# Run a write task that requires approval
uv run voidcode run "write hello.txt hello world" --workspace . --approval-mode ask

# List persisted sessions
uv run voidcode sessions list --workspace .

Configuration

Workspace-local runtime config lives in .voidcode.json at the workspace root. To enable IDE auto-completion and validation, point the $schema field at the published JSON Schema:

{
  "$schema": "https://raw.githubusercontent.com/lei-jia-xing/voidcode/master/schema/voidcode.config.schema.json",
  "approval_mode": "ask",
  "model": "opencode-go/glm-5"
}

User-level overrides resolve from ~/.config/voidcode/config.json (XDG default). Environment variables (VOIDCODE_MODEL, VOIDCODE_APPROVAL_MODE, VOIDCODE_EXECUTION_ENGINE, etc.) override file config; see .env.example for the full surface.

Architecture overview

VoidCode uses a runtime-centric architecture: runtime is the system control plane, graph is the execution/orchestration layer, and LangGraph currently powers only the deterministic reference/debug slice.

• The runtime owns session state, permissions, tools, storage, streaming, and governance.
• The graph advances execution state. Today that includes a LangGraph-backed deterministic reference slice and a runtime-driven provider-backed single-agent path; new product behavior should prefer the provider-backed path when a model/provider is configured.
• Clients such as the CLI, web frontend, and future integrations talk to the runtime rather than invoking tools or graph code directly.
• The repository already contains src/voidcode/agent/ as a declaration layer for agent presets, but true multi-agent execution semantics are still post-MVP.

Key backend boundaries:

• src/voidcode/runtime/ — runtime services and execution boundary
• src/voidcode/graph/ — execution/orchestration layer
• src/voidcode/tools/ — built-in tools and tool metadata
• src/voidcode/hook/ — hook configuration and executor
• src/voidcode/lsp/, skills/, provider/, acp/, mcp/ — capability-layer boundaries
• src/voidcode/tui/ — terminal client layer

Design principles that currently shape the project:

• keep runtime, orchestration, and UI responsibilities clearly separated
• gate tool usage through registry, permission, and hook policies
• make sessions and execution state resumable
• allow concurrent reads while controlling writes
• preserve observability around turns, tools, approvals, hooks, and failures
• keep the MVP scope narrow and verifiable

Repository layout

voidcode/
├── src/voidcode/         # Python package (src-layout)
├── tests/                # pytest unit and integration coverage
├── frontend/             # Bun/Vite/React shell
├── docs/                 # internal architecture, roadmap, and contract docs
├── .github/workflows/    # CI and release automation
└── mise.toml             # canonical task runner entrypoint

Development workflow

One-time setup:

mise install
uv sync --extra dev
mise run frontend:install

Common tasks from mise.toml:

# Python
mise run lint
mise run format
mise run typecheck
mise run test:fast
mise run test
mise run test:coverage
mise run build

# Frontend
mise run frontend:dev
mise run frontend:lint
mise run frontend:typecheck
mise run frontend:test
mise run frontend:e2e
mise run frontend:build

# Combined verification
mise run check
mise run ci

# Release notes / changelog
mise run release:preview
mise run release:notes

# Pre-commit hooks
mise run pre-commit
uv run pre-commit install

mise orchestrates tasks and loads the local virtual environment. uv remains the source of truth for Python dependency management and execution. Use mise run test:fast for the tight local feedback loop, mise run test for parallel full pytest without coverage, and mise run test:coverage for coverage-bearing validation. Bun scripts are owned by frontend/package.json; the repository root intentionally has no package.json so root-level automation goes through mise.toml.

Release notes are generated with git-cliff using cliff.toml. The current GitHub release workflow keeps its release.published trigger and uses git-cliff to populate the GitHub Release body while artifact upload continues through GitHub Actions.

Documentation map

For a deeper view of the current design and roadmap, see:

• docs/architecture.md
• docs/roadmap.md
• docs/mvp-todo-plan.md
• docs/mvp-demo-guide.md
• docs/contracts/README.md
• docs/development.md

These internal docs are currently maintained in Chinese.

Contributing and community

• Contribution guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Changelog: CHANGELOG.md

License

VoidCode is released under the MIT License.