mcode

A native C++23 coding-agent harness with a Luau extension layer.
One native binary. No runtime. A scripting ecosystem that costs nothing until you use it.

Our philosophy:

native core, scripting ecosystem
context is a budget, not a buffer
enforce invariants in the harness, not the prompt
fail closed on authority, fail open on capability
boring technology, spent novelty budget
measure or it did not happen

The interesting number is how much the harness can do at that size. A tool is a Lua table, and a provider is a descriptor.

$ mcode

❯ refactor the config loader to return std::expected

✻ The loader returns bool and swallows the error code, so callers cannot tell
✻ which failure they got. std::expected carries it without changing the call sites.

✓ read src/mcode/support/config.cxx  0.3s
✓ grep "return false"  0.2s

  Three call sites need the new return type, then I'll build.

✓ edit src/mcode/support/config.cxx  0.4s
✓ edit src/mcode/cli/session.cxx  0.3s

mcode wants to run:
    cmake --build build/Release
  rule: default: exec
  [y] allow once   [a] always allow (saved to this project's store)
  [n] deny once   [d] never allow (this session)   [?] details

✓ bash cmake --build build/Release  8.1s

> /context
▸ /context        Show context-window usage: used, capacity and percent
  /model          Show the model this session runs
  /export         Write the session transcript to a Markdown file
  /mention        Pick a workspace file to mention as @path

combo/deepseek ▸ 12.4k tok 8% ▸ $0.031 ▸ 4.2s

-- ext.toml: permissions = ["fs_read"]

mcode.tool.register({
	name = "todo_scan",
	description = "Find TODO markers in the workspace",
	schema = { type = "object", properties = { path = { type = "string" } } },
	permission = "read",
	run = function(args)
		local hits = mcode.fs.grep({ pattern = "TODO", path = args.path or "." })
		return { count = #hits, hits = hits }
	end,
})

vs. Node and Python harnesses. They are the reason a coding agent needs a runtime install, a warm start, and hundreds of megabytes resident. mcode is one binary you can spawn per invocation and pipe.

vs. Rust harnesses. Closest in spirit, and they proved the native-speed thesis. They still have no extension language, so adding a tool means shipping a build.

vs. shell-only agents. Minimal and honest, but a typed tool layer is what makes edits anchored, reads bounded, and every action permissioned by class instead of by string matching.

vs. nothing. An agent with no budget discipline burns your context window and your money at the same rate. mcode accounts for both, per turn.

One command downloads the binary for your platform, verifies its SHA-256, puts it on your PATH, and starts a setup wizard. No compiler, no Python, no Conan.

Windows (PowerShell)

irm https://raw.githubusercontent.com/immutex/mcode/master/install.ps1 | iex

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/immutex/mcode/master/install.sh | sh

The wizard picks a provider, takes an API key, and verifies the endpoint with a real turn before it writes anything. It writes exactly one file: mcode config's path, which it prints.

Then, from your project:

mcode                    # interactive session
mcode "fix the failing test"   # one task, then exit
mcode exec --json "…"    # machine-readable event stream

python -m pip install "conan==2.32.0"
pwsh -File scripts/bootstrap.ps1
cmake --build build/Release
ctest --preset windows-msvc
./build/Release/bin/mcode.exe

python3 -m pip install "conan==2.32.0"
./scripts/bootstrap.sh
cmake --build build/Release
ctest --preset linux-gcc        # or macos-clang
./build/Release/bin/mcode

The design is the authoritative specification. Where code and docs disagree, the docs win. Start at the index.

• Design index: reading order for all 43 docs
• North Star: thesis, hard budgets, principles, non-goals
• Prior art: 16 harnesses compared, plus the Lua-extension precedent
• Architecture: process model, layers, core types, extension seams
• Agent loop: state machine, termination, test-time compute
• Context engineering: budgeting and compaction
• Core tools, MCP, Skills
• Security: trust boundary, permission model, sandboxing
• CLI & TUI: renderer, theme, commit protocol
• Lua runtime, Lua API, Extensions
• Stack, Providers, Cross-platform
• Measurements: extension load, RSS, hook dispatch, measured
• Non-obvious constraints: the traps, numbered
• Roadmap: milestones and risks

CHANGELOG.md records what changed in each release.

Not built yet: OSC 52 clipboard, image input, background jobs, LSP, ACP, and the /skill, /mcp, /session, /reload commands.

Shipped in 0.1.0: the batch that connects what 0.0.x built. Eleven interfaces existed with a producer or a caller missing, each with a passing test — the defect was unconnected code, not absent code. They are wired, and the seven first-party extensions docs/23 mandates all ship: task, fs-extra (todo), skills, memory, web (web_search, fetch), git, github. Two new core API entries carry them: mcode.bash, which routes to the same core bash handler so the sandbox and the permission gate cannot be bypassed from Lua, and mcode.fetch for a URL the model chose, gated per domain and refusing private addresses. The loop now recites the goal and the plan every ten steps and after each compaction, routes by model tier (model.tier.plan|act|side), and delegates to a read-only subagent whose budget is carved from the parent's. MCP gains resources/* and prompts/*.

Shipped in 0.0.3: the repo-local extension trust gate, mcode ext install, the verification gate and its false_success_rate, the context controller, memory, read-only subagents, and MCP over Streamable HTTP. The egress proxy ships with its limits stated: it raises the cost of exfiltration and does not stop it through an allowlisted destination, and Windows network enforcement reports best-effort because WFP requires admin.

Shipped in 0.0.4: a code-quality pass over the whole tree, not a feature batch. Dead code and history-narrating comments are gone, every file is under 600 lines, and the comment rule is a CI gate (tools/comment_lint.py) rather than a convention. Three defects were fixed on the way, all found by running the code: the egress proxy sent a SOCKS5 reply with an invalid address type, mcode ext deny wrote a trust record its own parser rejected (losing every grant beside it), and five file-scope symbols in mcode::platform had external linkage despite no header declaring them.

src/mcode/
├── core/       error model, tool registry, version
├── support/    logging, JSON, TOML, Unicode, config
├── ext/        the Luau extension host
├── fs/         workspace boundary and file primitives
├── net/        SSE parser, HTTP client
├── proc/       subprocess, PTY
├── perm/       the permission engine and stores
├── mcp/        MCP client and supervisor
├── skills/     discovery, frontmatter, routing index
├── instruct/   the AGENTS.md instruction chain
├── model/      provider descriptors, request rendering, capabilities
├── tools/      the core tool set
├── tui/        terminal layer, cell buffer, renderer
├── events/     the event bus
├── agent/      loop, session budget, event log
└── cli/        command surface

Dependencies point downward only, from agent/ toward core/. The core knows four abstractions (ModelClient, Context, ToolRegistry, EventBus) and nothing about Lua, MCP, skills, or the terminal.

Everything comes from Conan 2 except Luau, which mcode builds from its own recipe. See docs/14 for why each was chosen. Size is the binding constraint: a new dependency must justify itself against measured size and compile cost, not against an arbitrary count.

Every trap that cost real time to find is recorded in docs/40, numbered, with the reason it exists. Docs cite them by number. Read the one you were sent to.

cmake --preset windows-msvc   # or linux-gcc / macos-clang
cmake --build build/Release
ctest --preset windows-msvc

Presets are defined in CMakePresets.json and consume the Conan toolchain, so conan install must run first. -DMCODE_WARNINGS_AS_ERRORS=ON for a strict build, and the dev preset turns LTO off for faster iteration.

The smoke test proves the toolchain works end to end: every dependency, the Lua boundary, the workspace boundary, and the agent loop. Its exit code is the number of failed checks, so CI gates on it directly.

./build/Release/bin/mcode --smoke

CI runs the full suite on Windows and Linux, and build + smoke on macOS. The strict warning set is on everywhere; _clgate.py also syntax-checks every translation unit against a second toolchain, because the Windows build defines _WIN32 and never parses the POSIX branches.

Windows, Linux, and macOS are all tier-1. Every abstraction that touches the OS (process spawn, PTY, sandbox, paths, file watching) is designed behind an interface, because retrofitting a platform later is how a project ends up with a Windows-shaped core.

AGENTS.md is the authoritative rule set, and it applies to humans as much as to agents. Read CONTRIBUTING.md for setup, the style rules that are load-bearing in review, and the two things CI catches that no local build will — the POSIX branches, which a Windows workstation never compiles, and the warnings-as-errors set, which is off locally and on in CI.

Two checks are worth running before every push:

python _clgate.py                     # clang++ with the CI Clang warning set, in seconds
./build/Release/bin/mcode --smoke     # exit code is the number of failed checks

Report vulnerabilities privately through GitHub Security Advisories, never in a public issue. SECURITY.md has the threat model, what is in scope, and — importantly — a table of which controls actually ship, since the design docs describe the target and the tree is at 0.0.1.

Apache-2.0, see LICENSE.

mcode embeds Luau, which is distributed under the MIT License. Luau is Copyright (c) 2019-2025 Roblox Corporation and Copyright (c) 2005-2019 Lua.org, PUC-Rio. The full text ships in the Conan package under licenses/ as LICENSE.txt and lua_LICENSE.txt, and is reproduced in THIRD-PARTY-NOTICES.md.

Upstream asks that products embedding Luau carry attribution for the language and a link to https://luau.org/ in their documentation. This section and the notices file satisfy that request.