CodeLeveler

A local-first coding agent that works in your repository and leaves reviewable changes when code needs to change.

中文 ·

Harness is an amplifier of model capability, not a constraint on it.

The model defines what is possible; the Harness determines how fully that capability can be realized.

CodeLeveler aims to maximize each model's own capabilities—not to narrow performance gaps between models or make their behavior converge. Context, tools, execution, and feedback should amplify the model's reasoning and autonomy, not replace them.

Give CodeLeveler a task. It can read the repository, edit files, run builds and tests, and use Git. Conversations, approvals, events, and changed files remain available when a session stops. Session state is stored on your machine, and model requests go to the provider you configure.

The terminal UI (leveler), Web UI (leveler web), and headless CLI (leveler run) use the same runtime. CodeLeveler currently targets macOS, Linux, and Windows.

cd your-project
leveler
# or
leveler run "find the failing tests and fix them"

What it does

• Produces repository changes you can inspect instead of treating an agent's completion claim as proof.
• Persists sessions so you can close the UI and continue with leveler resume.
• Supports Zhipu BigModel (GLM Coding Plan), DeepSeek, Moonshot/Kimi, OpenAI, Anthropic, and other OpenAI-compatible endpoints.
• Provides an explicit /develop workflow for Analyze → Coding → Verify → Review.
• Offers optional browser automation, web search, custom agents, and parallel candidate worktrees.

Install

Install script (macOS, Linux)

curl -fsSL https://raw.githubusercontent.com/dengmengmian/CodeLeveler/main/install.sh | sh

It picks the archive for your platform from the latest stable release, refuses to install unless the SHA-256 checksum matches, and puts leveler in ~/.local/bin (override with LEVELER_BIN_DIR). LEVELER_VERSION=v1.0.0 pins a version.

Homebrew (macOS, Linux x86_64)

brew install dengmengmian/tap/leveler

Update with brew upgrade leveler. The built-in updater does not know about Homebrew and would replace the binary behind Homebrew's back, so a Homebrew install should set auto_update = false under [update] (see Updates).

Release archive

Every release publishes archives with a SHA-256 checksum for the supported platforms:

Download the archive for your platform from the releases page, download its .sha256 sibling, verify it, extract leveler, and put it on your PATH:

shasum -a 256 -c leveler-v1.0.0-aarch64-apple-darwin.tar.gz.sha256
tar -xzf leveler-v1.0.0-aarch64-apple-darwin.tar.gz
mkdir -p ~/.local/bin && mv leveler-v1.0.0-aarch64-apple-darwin/leveler ~/.local/bin/
leveler --version

On Windows, extract the .zip and keep leveler.exe and leveler-confine.exe in the same directory.

From source

With Rust 1.90+, Node.js 22+, npm, and Git:

npm --prefix crates/leveler-web/web ci
npm --prefix crates/leveler-web/web run build
cargo install --path crates/leveler-cli --locked
leveler --version

The frontend must be built before cargo install because its output is
embedded in the leveler binary at Rust compile time.

On Linux, install bubblewrap before running agent commands:

sudo apt install bubblewrap

CodeLeveler can start without it, but commands that require Linux isolation fail closed instead of running unsandboxed. Run leveler doctor to inspect the capabilities available on the current machine.

Development

Daily commands are ./dev. ./dev fmt formats only the Rust files owned by the current task and does not run cargo fmt --all. Release eligibility is the external lab: release_check.py, then rc_check.py. ./dev invokes those scripts and does not replace them. Run ./dev help for the command list.

Releasing

./dev publish is one release transaction: it bumps the version and commits it, then runs four stages and stops at the first failure.

Each stage records the inputs it decided on and a digest of the evidence it accepted. ./dev publish --resume re-earns only the stages whose inputs changed and keeps the version already in progress, so a fix after a failed stage 3 still ships as the same version. --status reports where the transaction stands, --report rewrites the report, --dry-run prints the plan, and --stop-after <1..4> stops early.

A release is only RELEASED in the report once the tag, the GitHub release and the published assets have been verified; a dispatch is never treated as a result. Reports are written to .dev/release/<version>/RELEASE_REPORT.md and release.json, and archived next to the dogfood evidence when there is a run.

Mirrors (AtomGit, GitHub proxies)

Every stable release is also published on AtomGit (atomgit.com/dengmengmian/CodeLeveler),
so a network that reaches one host but not the other still has a source.

leveler update and install.sh prefer the GitHub URL and fall back to mirrors,
and the SHA-256 checksum always decides: a mirror that serves anything else
fails verification instead of being installed. Two kinds of mirror are supported,
both optional and both comma-separated:

# A proxy that takes the whole canonical URL appended to its own path
# (ghproxy-style): https://mirror.example/https://github.com/...
LEVELER_UPDATE_MIRRORS="https://mirror.example/"

# A host that stores our files under its own layout and takes the bare asset
# name. `{version}` is substituted with the release being fetched.
LEVELER_UPDATE_ASSET_BASE="https://atomgit.com/dengmengmian/CodeLeveler/releases/download/v{version}/"

The canonical GitHub URL is always tried first; mirrors only add candidates.

Updates

CodeLeveler keeps itself on the latest stable GitHub release. At start-up it checks at most once per check_interval_hours, and when a newer release exists it downloads it, verifies its SHA-256, replaces the running binary, and restarts. A failed check never blocks start-up: the current version runs normally and the reason is logged.

Manual update:

leveler update            # install the latest stable release
leveler update --check    # exit 2 when an update exists
leveler update --version v1.0.8

Inside the TUI:

/update

/update is refused while a task is running, so the binary is never replaced under active work.

Configuration, in ~/.leveler/config.toml:

Start-up auto-update is enabled by default. The first-run login guide writes these settings to the config file:

[update]
auto_update = true           # false disables start-up checks; manual update still works
check_interval_hours = 1     # hours between successful checks (minimum 1)

Only stable releases are tracked. Pre-releases are installed only when named explicitly with --version.

First run

leveler                    # choose a language, then run the same first-run setup as login
leveler login              # or run it explicitly
leveler doctor
cd your-project
leveler

leveler login supports Zhipu BigModel (GLM Coding Plan), DeepSeek, Moonshot/Kimi, OpenAI, and Anthropic. When the provider supports model discovery, it lists the models exposed to the supplied key. The command writes ~/.leveler/config.toml; on Unix it restricts that file to mode 0600. Skip the menu with leveler login bigmodel, leveler login deepseek, or leveler login moonshot.

DeepSeek Flash is configured as deepseek/deepseek-flash. Replace the retired pre-release reference deepseek/deepseek-v4-flash in existing configs.

For another OpenAI-compatible endpoint, run leveler init and edit ~/.leveler/config.toml. configs/example.yaml is an annotated schema reference only; that YAML file is not loaded as configuration.

Thinking level

How hard a model thinks is one vocabulary on every model:

auto     no override; the provider's own default
off      turn extra reasoning off where the model can be asked
minimal  the lowest usable amount
low      light reasoning
medium   balanced reasoning
high     deep reasoning (the global default)
max      the strongest level this model has

The global default is high. Per-model settings take priority; /thinking reset clears only the session override and returns to that configured default. Explicit auto leaves the provider's reasoning intensity unchanged. Unsupported or fixed models do not apply an adjustable High setting.

To change it for one session, from the TUI:

/thinking high
/thinking reset     # back to the configured default

To change a default, write it in ~/.leveler/config.toml:

# every model
thinking = "high"

# one model, overriding the global value
[models.deepseek-chat]
provider = "deepseek"
thinking = "low"

Use the default high for deep reasoning, auto to leave intensity to the provider, low for lighter reasoning, or max for the most the current model can do.

high and max are not the same: max means "the strongest this model has", so it tracks the model instead of pinning a provider's parameter, and a config file holds max rather than a string one provider happens to read. The provider's own values (an xhigh, a token budget) are a capability the model declares, not a setting a user writes. Which levels a model can distinguish is decided by what it declares; leveler doctor lists them per model.

A clean Git worktree is recommended so changes remain easy to inspect or discard.

Commands

/develop runs Analyze → Coding → Verify → Review in one session. Without [develop].model, its reading stages use the session model. A configured model must be written as provider/model; an invalid value is an error, not a fallback.

--parallel is a separate workflow, not runtime sub-agent delegation. It requires --collaboration goal, a clean, committed Git tree; it creates isolated worktrees and branches, commits verified candidates, and integrates successful candidates into the current branch. chat and plan are refused, because neither is guaranteed to produce the committed candidate edit that integration merges.

On macOS and Linux, leveler serve keeps the runtime alive behind a local Unix socket after a UI closes. Windows has no local Unix-socket daemon; persisted sessions and resume still work.

In the TUI, click the footer's background summary (↗) to open the job list, then click a job's [Stop] button to stop only that job. The detail page also has a [Stop] button. Keyboard controls are ↑↓ to select, Enter for details, and x to stop. Esc only returns; it does not stop work. When connected to a daemon, closing the terminal window does not stop background jobs either.

Permissions and isolation

The default permission profile is assisted. Ordinary repository writes, builds, tests, network actions, and commands such as git push or package publishing may run automatically inside the available OS sandbox. Deletion outside the workspace, a deletion whose target is not a literal relative path, privilege escalation, and host-escape operations require approval. rm and rmdir of a literal path inside the workspace run directly. Use request-approval when you want a stricter approval boundary.

leveler doctor reports the effective host capabilities. If a restricted mode needs an isolation backend that is missing, execution fails instead of pretending to be sandboxed.

TUI editing and terminal diagnostics

In the input area, Ctrl+Z undoes an edit, Ctrl+Shift+Z or Alt+Z redoes it, and Ctrl+Y restores recently killed text. Undo restores paste blocks, file references, and the original image attachment bindings. Submission and session changes end the draft's edit history. Each undo/redo stack is bounded to 100 entries and 8 MiB.

Ctrl+R searches submitted input history. Enter restores the selected entry to the draft for editing without sending it; Esc or Ctrl+C closes search and preserves the original draft. /help searches commands, shortcuts, and descriptions.

/doctor shows local terminal diagnostics. leveler doctor also reports terminal, SSH/tmux, color hints, newline keys, and clipboard routes. Diagnostics do not change clipboard contents or terminal settings; capabilities without evidence remain unknown.

In an ordinary local terminal, copying selected conversation text prefers the native clipboard with readback verification. Over SSH, the remote host's native clipboard is skipped in favor of OSC52. Since a tmux server cannot establish its current client's location, tmux also skips the native clipboard, writes the tmux paste buffer, and sends OSC52. Successful OSC52/tmux writes are reported as sent with local clipboard delivery unverified. Clipboard forwarding or passthrough may need to be enabled in your terminal. OSC52 text is limited to 64 KiB, with an explicit error above the limit.

Browser and web search

Each goal starts with the base coding tools. The model loads optional capabilities when needed; the runtime exposes their tools only when they are available and permitted.

• Chrome, Edge, or Chromium: CodeLeveler starts a dedicated automation session. browser_tab, browser_act, and browser_inspect can navigate, interact, and inspect console, page-error, and network records.

• Safari: opt in with default = "safari" under [browser] in ~/.leveler/config.toml, then enable Safari Remote Automation. Safari supports tabs and interaction, but its WebDriver backend cannot provide console, page-error, or network inspection.

• Web search: the backend is configured independently of the conversation model, in ~/.leveler/config.toml:

  [web.search]
  provider = "deepseek"          # deepseek | tavily
  api_key_env = "LEVELER_SEARCH_API_KEY"
  max_results = 5
  timeout_ms = 15000
  # base_url = "https://api.deepseek.com/v1/tools"
  

  DeepSeek search calls POST https://api.deepseek.com/v1/tools/search once per tool call, with no auxiliary model request. Any configured model can use it, and switching models never changes the search provider. A model provider's base_url is never reused as the search endpoint. Supported search providers are deepseek and tavily. This section is the only way to enable search: without it, web_search is unavailable, and setting LEVELER_SEARCH_API_KEY alone does not turn it on (the legacy implicit fallback was removed). web_search performs one HTTP request, honors the configured timeout, and does not retry or fall back to browser automation.

TUI /web and links opened from the UI still use the operating system's default browser.

Custom agents

A custom agent is a directory containing agent.yaml (declared capabilities) and instructions.md (working instructions). Create one through CodeLeveler, through Settings → Agents in the Web UI, or by committing .leveler/agents/<name>/.

The coding harness resolves the definition, while capability admission and host authority enforce its boundaries. Instructions cannot grant extra tools or write access. See Custom agents.

Experimental mobile client

apps/leveler-mobile is a frozen source preview, not a distributed product. The current evidence covers an iOS simulator pairing flow. Android builds, physical-device and cellular testing, TestFlight, and Play distribution have not been completed.

Remote control sends session traffic through the configured relay. Messages are signed, but end-to-end AEAD encryption is not implemented yet; the TLS terminator can read session traffic. Self-host the relay if you evaluate this feature. See the mobile status before using it.

Documentation

• Architecture
• Custom agents
• Release notes
• Changelog
• Documentation index
• Security policy

Run leveler --help for the complete command list. See Updates for staying current.

Security vulnerabilities belong in the private process documented in SECURITY.md, not in a public issue.

Apache License 2.0. See LICENSE-APACHE.