From a coding request to a reviewable diff — local-first coding agent runtime.
中文 ·
·
CodeLeveler is a local-first coding agent runtime with terminal and browser clients, built around a persistent execution engine that can inspect, edit, run, and verify real repositories. Work interactively in the TUI, use the Web UI, or automate a task from the CLI. Sessions, permissions, and project state stay on your machine; model requests go only to the provider you configure.
The primary product surface today is the terminal coding workflow; the same
runtime also powers leveler web and a host-side remote bridge. Desktop/mobile
APP productization, long-running NPC workflows, and a Capability/Extension
framework are architectural directions — not all shipped yet. See
Architecture for CURRENT vs TARGET vs FUTURE.
Windows, macOS, and Linux are tested in CI. CodeLeveler is currently in public
beta (0.1.x).
CodeLeveler writes the code. ReviewGate reviews it. AgentGate connects both to your model APIs. Each tool works independently, or they can be used together:
| Tool | Focus |
|---|---|
| CodeLeveler | Inspect, edit, run, and verify code via a persistent local runtime (TUI, Web, CLI) |
| AgentGate | Adapt model APIs behind one local gateway |
| ReviewGate | Review code changes and surface high-confidence issues |
- A complete coding loop. Explore a repository, make focused edits, run project checks, repair failures, and leave a reviewable diff.
- One runtime, multiple clients. TUI and Web share the same client protocol
(
ClientCommand/RuntimeEvent/ snapshots); work can outlive a single terminal process on platforms that support the local daemon. - Run your own commands.
!command(e.g.!git status,!cargo test) executes an explicit shell command in the repository without invoking the model — live output, per-command stop, same sandbox as agent commands. - Control stays with you. Typed tools, approval rules, workspace boundaries, checkpoints, and platform-aware command isolation constrain what the agent may do.
- Resume saved work. SQLite-backed sessions preserve the conversation, pending approvals, tool results, diffs, and verification state for later review or resume.
- Bring your own model. Use configurable OpenAI-compatible providers without coupling the agent runtime to one model vendor.
Option A — Homebrew (macOS, recommended)
brew install dengmengmian/tap/levelerbrew upgrade leveler moves you to newer releases.
Option B — Download a prebuilt binary
From the latest release,
download the archive for your platform, unpack it, and move leveler onto your
PATH. Example (replace V/T for your platform):
V=0.1.0; T=aarch64-apple-darwin # or x86_64-apple-darwin, x86_64-unknown-linux-gnu
curl -LO https://github.com/dengmengmian/CodeLeveler/releases/download/v$V/leveler-v$V-$T.tar.gz
tar -xzf "leveler-v$V-$T.tar.gz"
sudo mv "leveler-v$V-$T/leveler" /usr/local/bin/
leveler --versionOn Windows, download leveler-v<version>-x86_64-pc-windows-msvc.zip, unzip it,
and add the folder to PATH. After installing on any platform, leveler upgrade moves you to newer releases.
Option C — Build from source
You need Rust 1.90+ and Git.
git clone https://github.com/dengmengmian/CodeLeveler.git
cd codeleveler
cargo install --path crates/leveler-cli --lockedFirst run — security prompts. The prebuilt binaries are not yet notarized (macOS) or code-signed (Windows), so a first run may be blocked:
- macOS: the
curl … | shinstaller runs without a prompt (and strips the quarantine flag). If you downloaded the archive in a browser and Gatekeeper says "unverified developer", clear it once:xattr -dr com.apple.quarantine ./leveler(or right-click → Open, or System Settings → Privacy & Security → Open Anyway). - Windows: SmartScreen may warn — "More info → Run anyway", and if the
.zipwas browser-downloaded, Properties → check "Unblock" first. - Linux: no signing gate. For full sandboxing install
bubblewrap(sudo apt install bubblewrap); without itlevelerstill runs but the sandbox degrades —leveler doctorreports what is available.
On Windows, set a persistent Leveler home and create the config from PowerShell:
$levelerHome = Join-Path $HOME ".leveler"
[Environment]::SetEnvironmentVariable("LEVELER_HOME", $levelerHome, "User")
$env:LEVELER_HOME = $levelerHome
New-Item -ItemType Directory -Force $levelerHome
notepad (Join-Path $levelerHome "config.toml")On macOS/Linux, create ~/.leveler/config.toml. Put the following content in
the file:
default_model = "deepseek/deepseek-chat"
[providers.deepseek]
base_url = "https://api.deepseek.com"
api_key_env = "DEEPSEEK_API_KEY"
[models."deepseek-chat"]
provider = "deepseek"
context_window = 131072
max_output_tokens = 8192
streaming = true
tool_calling = true
structured_output = trueSet the API key for the current shell:
# PowerShell
$env:DEEPSEEK_API_KEY = "..."# macOS / Linux
export DEEPSEEK_API_KEY="..."A plaintext api_key = "..." is also supported in a local config file. Prefer
an environment variable on shared machines or for configuration stored in Git.
leveler doctor
leveler model probe deepseek/deepseek-chat
cd path/to/your/project
levelerOr run a one-off task without opening the TUI:
leveler run "find the cause of the failing tests and fix it"The default assisted permission profile asks before higher-risk actions. For
your first run, use a clean Git worktree so every change is easy to inspect or
discard.
| Need | Command |
|---|---|
| Work interactively (TUI) | leveler |
| Browser UI (same runtime) | leveler web |
| Run one task | leveler run "add validation to the order endpoint" |
| Resume previous work | leveler resume <session-id> |
| Long task until done | TUI /goal …, or leveler run "…" --collaboration goal |
| Stricter delivery gates | --work-mode delivery or TUI /work-mode delivery |
| Parallel multi-agent edits | leveler run "…" --parallel 3 (worktrees) |
On macOS/Linux, a long-running interactive session can use leveler serve in
one terminal and leveler in another. The TUI reconnects to the
repository-local runtime instead of tying the work to one terminal process.
leveler web attaches to the same runtime contract (in-process or via
leveler serve --tcp). Windows supports persisted sessions and resume, but
the daemon socket transport is not available there yet.
- Understand — search the repository, inspect symbols and relevant files, and establish a plan when the task needs one.
- Change — apply typed file operations and run commands within the active permission and workspace boundaries.
- Verify — discover or use configured format, build, and test commands; failures can trigger bounded repair attempts.
- Hand off — keep the diff, transcript, verification result, and session state available for review or resume.
CodeLeveler can modify files and execute local commands, so its safety boundary is explicit rather than implicit.
| Platform | Process control | Restricted command execution |
|---|---|---|
| Windows | Job Objects | AppContainer and ACL restrictions when available |
| macOS | Process-group cancellation | Seatbelt profiles |
| Linux | Process-group cancellation | Bubblewrap |
leveler doctor reports the capabilities actually available on the machine.
Restricted modes fail closed when a required isolation backend is unavailable;
process-tree control alone is never reported as a full sandbox.
Permission rules and hooks can be defined per user or per repository. Start with the configuration guide, permission example, and hook example.
- Documentation index
- Project configuration example
- Provider and model configuration schema
- Architecture
- Evaluation harness
Run leveler --help or leveler <command> --help for the CLI reference. Use
leveler upgrade --check to check for a newer release.
The command surface and configuration format may change before 1.0. Cross- platform CI covers Windows, macOS, and Linux, but OS-level isolation still depends on capabilities installed and enabled on each machine.
Contributions are welcome. Read CONTRIBUTING.md before opening a pull request. Report vulnerabilities through the private process in SECURITY.md, not a public issue.
Apache License 2.0. See LICENSE-APACHE.