metacodes

Metacodes is an embeddable, low-resource agent core and coding CLI written in Zig.
It owns a fixed agent loop, deterministic provider projection, permission and
sandbox enforcement, durable tool-result artifacts, Lean-backed governance, and
optional TinyKG memory/task coordination. Hosts can extend tools, provider
dialects, UI, MCP, and process plugins without replacing those kernel boundaries.
The release unit is complete on every supported platform: the TUI, TinyKG (CLI
and daemon) and both Lean governance kernels under libexec/metacodes/, each
pinned into the executable (release/LAYOUT.md). Runtime resolution checks the
environment-variable pair first, then the adjacent file with its compiled-in
digest, and metacodes doctor reports every runtime asset and the state root.

Repository status: public review, pre-1.0 (version declared in
build.zig.zon). The repository currently includes an MIT license. Release
readiness is still tracked as milestones and remaining owner decisions in
OPEN_SOURCE_READINESS.md and ROADMAP.md.

Why metacodes

• One native binary, no language runtime, fast startup, and explicit allocators.
• A built-in coding agent loop rather than a framework that delegates correctness
  to arbitrary hooks.
• Immutable plugin generations and append-only provider context, preserving prompt
  cache stability when the effective model-visible configuration is unchanged.
• Tool results share one typed inline/artifact/error data plane across CLI,
  plugins, MCP, and AgentCore embedding.
• Formal decisions stay in the kernel; TinyKG stores governed memory, task DAGs,
  receipts, and provenance but does not become the agent loop.
• Source-level Zig embedding and a source-free C ABI bundle for C, C++, Zig, Rust,
  Go, and other native hosts.

Install

macOS (aarch64) and Linux (x86_64), the latest release:

curl -fsSL https://raw.githubusercontent.com/metask-ai/metacodes/main/scripts/install.sh | sh

This installs into ~/.local/opt/metacodes with a metacodes launcher in
~/.local/bin, the AgentCore SDK included; rerunning it upgrades in place and
keeps the state. | sh -s -- --version X.Y.Z picks a release, --help lists
the rest. From a checkout, scripts/install.sh --dev builds the release unit
from source and installs it beside the released one: the main checkout as
metacodes-dev (~/.local/opt/metacodes-dev), a linked worktree as
metacodes-dev-<worktree directory>, each with a state root of its own. An
install is a copy, so rebuilding or removing the checkout leaves it running;
--dev --uninstall removes it again. Nothing needs starting by hand: the first
session of an install sets up and starts its TinyKG service in the background.
A downloaded archive installs the same way:

sh scripts/install.sh metacodes-<version>-<target>.tar.gz

powershell -ExecutionPolicy Bypass -File scripts\install.ps1 metacodes-<version>-x86_64-windows-gnu.zip

Each install is self-contained and isolated: it keeps its state (config,
credentials, TinyKG store, sessions, plans, Lean rules) in its own state root,
<prefix>/state unless --state-dir says otherwise, recorded in
<prefix>/etc/metacodes/install.json. Several installs coexist on one machine;
give each its own --prefix and launcher name (--link-name). --sdk adds the
AgentCore SDK under <prefix>/sdk/agentcore/ (include/metask/agentcore.h,
lib/, Zig and Rust bindings). The scripts only unpack (and refuse a
downgrade for a release up to 0.5.0, whose own install does not); the install is
bin/metacodes install (--help lists its options), which ends with the
installed doctor --strict; --upgrade replaces another version of the same
product (the scripts always pass it) but not a newer one with an older one
unless --allow-downgrade, --force also foreign files and another launcher.
A launcher name held by another install is refused with that install's prefix
and version. A process picks its state root from --state-dir,
then METACODES_HOME, then the install record, then ~/.metacodes
(doc/INSTALL_DESIGN.md).

Build

The checked-in toolchain contract currently requires Zig 0.16.0 or newer within
the 0.16 development line used by CI.

git clone https://github.com/metask-ai/metacodes.git
cd metacodes
zig build
./zig-out/bin/metacodes --help

The default build does not download or compile TinyKG. It selects one
manifest-pinned CLI from the checked-in cross-platform binary bundle and stages
it beside Metacodes. highlight-zig remains the only checked-in source
dependency. See TinyKG integration for the supported
matrix, provenance contract, explicit override, and manual update procedure.

Common gates:

zig build test
zig build test:lib -Doptimize=ReleaseSafe

With a Lean toolchain (elan) on the machine, zig build test also builds both
governance kernels from this checkout (kernels:stage, cached on the Lean
sources) and runs every kernel-gated test against them; -Dlean-kernels=on
turns a missing toolchain into a failure, off skips the kernels. On Windows
the kernel scripts run under Git for Windows' bash, never WSL's. A release
unit from source is zig build kernels:stage --prefix <u> followed by
zig build release:verify -Drelease-layout=true --prefix <u> $(python3 scripts/kernel_pins.py <u>); <u>/bin/metacodes install --prefix <dir> then
installs it. scripts/install.sh --dev does all three, plus the AgentCore SDK.

The AgentCore bundle and its native consumption gates (agentcore:test,
agentcore:bundle, agentcore:gate) are documented once, in
sdk/README.md.

On Windows the same suite runs natively; keep the job count bounded because
the default is one LLVM codegen per core and the test binaries are large:

zig build test -j6

The Python suites need Python >= 3.9 (the macOS system python3 suffices) and
PyYAML: python3 -m pip install -r requirements-dev.txt. zig build test runs
python3 (python on Windows) from PATH, and scripts/tests/test_python_floor.py
keeps every script parseable at that floor.

Line endings are pinned to LF by .gitattributes (embedded prompt templates
take part in SHA-256 contracts), and a few gates are POSIX-only by design and
skip with a stated reason: the paid budget journal, dir_fd-anchored artifact
publication, and the anonymous-descriptor memory runtime smoke (see
scripts/eval/tests/posix_only.py). CI runs this leg in the windows-gates job.
To exercise the POSIX-only paths from a Windows box, clone the commit into a
WSL ext4 home (not /mnt/..., where every file reports as executable) and run
the Python suite there.

Maintainers can audit a candidate binary instead of the bundled one:

tinykg_bin=/absolute/path/to/tinykg
tinykg_sha=$(shasum -a 256 "$tinykg_bin" | awk '{print $1}')
zig build test \
  -Dtinykg-bin="$tinykg_bin" \
  -Dtinykg-sha256="$tinykg_sha"

Normal tests use the native bundled artifact automatically. No build, test, or
release gate searches PATH, downloads TinyKG, inspects a sibling checkout, or
uses an old zig-out artifact.

Supported surfaces

Start at doc/API.md. The normative AgentCore ABI contract is
doc/AGENTCORE_BINARY_ABI.md; the plugin contracts
are indexed in doc/README.md.

Metask OAuth

metacodes login --provider metask uses Metask's JSON device authorization
flow. It prints METASK_VERIFICATION_URI=... and METASK_USER_CODE=... to
stderr (use --no-browser on a headless machine), then stores the access and
rotating refresh tokens plus gateway/model URLs in
$HOME/.metacodes/oauth/metask.json. Set METASK_SITE_URL for a local control
plane (http://localhost:3000); METASK_GATEWAY_URL overrides the gateway
origin for local development. METACODES_OAUTH_DIR changes the OAuth store.

Gateway requests use both Anthropic Messages and OpenAI Chat routes. A request
that receives 401 with code=token_expired is refreshed once and replayed;
invalid_token, invalid_api_key, and balance errors are never refresh-looped.
Each request is recorded after completion in
$HOME/.metacodes/ledger/metask.ndjson (override the directory with
METACODES_LEDGER_DIR), and metacodes ledger metask prints those JSON lines.
The ledger uses server-reported token usage only and includes both local and
X-Metask-Request-Id request identifiers.
Records are schema version 1 NDJSON with unix-millisecond ts; failed or
interrupted responses use zero token counts rather than estimates.

For compatibility, --api-key or an explicitly set METASK_API_KEY can still
select the historical napi.metask-ai.com API-key route. A stored device-flow
session supplies its authenticated gateway by default; use --base-url or
METASK_GATEWAY_URL when deliberately testing a different gateway.

Architecture

Host / CLI / Web / native SDK
              |
      immutable Runtime generation
              |
  +-----------+--------------------+
  | fixed AgentLoop and Conversation|
  | permission / sandbox / budget   |
  | tool artifact and durable effect|
  | Lean governance / TinyKG boundary|
  +-----------+--------------------+
              |
  tools / MCP / plugins / provider dialects

The model-visible request is a deterministic projection of effective tools,
conversation state, and provider dialect. Plugin ids, load paths, generations,
timestamps, journals, and TinyKG receipts do not enter the prompt. An equivalent
runtime replacement therefore keeps provider-visible bytes stable; only a real
capability or context change invalidates the cache prefix.

TinyKG boundary

TinyKG is a separately maintained executable and storage engine. Metacodes owns:

• when memory or task evidence is proposed;
• Lean/policy admission and re-observation;
• commit, rollback, budget, and user-visible receipts;
• runtime transport selection and degraded behavior.

TinyKG owns its binary/storage implementation, authenticated daemon protocol,
generation/CAS primitives, and graph persistence. Metacodes never imports TinyKG
source and never silently falls back from the daemon to a shared raw store.

Benchmarks

doc/BENCHMARKS.md indexes how metacodes is measured: local
performance gates, the internal paired-evaluation control plane and its
receipt-bound results so far, and the external WorkBuddy-Bench mainline
(pinned framework, anti-contamination cohorts, W0–W10 ladder with current
status). No external quality score is claimed until the corresponding ladder
stage has actually run; paid evaluation runs are never part of the default
development loop.

Contributing and security

Read AGENTS.md before changing code, then
CONTRIBUTING.md. Security reports must follow
SECURITY.md, not public issues. Paid benchmark runs require explicit
authorization and are never part of the default development loop.

中文简介

metacodes 是一个可嵌入、极低资源占用、内置 coding agent loop 的 Zig agent core。
插件可以扩展工具、MCP、provider 方言和宿主形态，但不能绕过权限、预算、形式化判定、
TinyKG 治理与因果边界。TinyKG 采用独立维护、跨平台、哈希锁定的二进制 bundle，
不再把源码复制进本仓库，也不会在构建时下载或隐式寻找开发目录。
项目目前处于 public review、pre-1.0 阶段；仓库已包含 MIT 许可证，但开源发布门禁仍未全部完成，详见 OPEN_SOURCE_READINESS.md。