Skip to main content
Version: 0.1.36

Agent quickstart (learn X07 from scratch)

This page is a single entry point for LLM agents. Use the published agent portal endpoints as the canonical source of schemas/skills/examples (see Agent contracts).

If you want a single copy/paste prompt to bootstrap a new project, use: Agent initial prompt.

If you find a documentation gap, check the toolchain source directly in GitHub:

0) The mental model​

  • X07 source is x07AST JSON (*.x07.json), not text.
  • The toolchain is JSON-first: diagnostics, patches, and reports are structured.
  • Programs run in worlds (fixture or OS); OS worlds are run-os and run-os-sandboxed.

High-level primitives to learn early (the “one whole system”):

  • Streaming pipes: std.stream.pipe_v1 (deterministic, budgeted streaming composition)
  • Branded bytes: bytes@B + std.brand.* (typed boundary encodings)
  • Structured concurrency: task.scope_v1 (no orphan tasks; slots/select)
  • Record/replay: std.rr + rr scopes (OS → deterministic cassette)
  • Budget scopes: budget.scope_v1 (localize cost contracts; arch-driven budgets)
  • Contracts tooling: x07 arch check, x07 schema derive, x07 sm gen (pinned contracts → deterministic checks/generation)
  • Property-based testing: x07 test --pbt + x07 fix --from-pbt (counterexample → deterministic regression)
  • Function contracts + verification: requires / ensures / invariant + x07 verify --bmc|--smt (bounded proof artifacts)
  • Review + trust artifacts: x07 review diff + x07 trust report (human reviewable “intent-level” diff + trust report)

1) Install and verify the toolchain​

  • Install with x07up (recommended).

Prerequisites (macOS / Linux):

  • sh + tar
  • curl or wget (used for downloads)
  • a sha256 tool (sha256sum, shasum, or openssl) for installer verification
  • for OS worlds / native deps (for example ext-curl-c): a C toolchain and libcurl headers (x07 doctor reports missing deps)

macOS / Linux (CI-safe, no profile edits, JSON report):

curl -fsSL https://x07lang.org/install.sh | sh -s -- \
  --yes \
  --channel stable \
  --no-modify-path \
  --json
export PATH="$HOME/.x07/bin:$PATH"

If you are not in CI, you can omit --no-modify-path and the installer will attempt to persist the PATH change.

Verify:

x07 --help
x07 run --help
x07up show --json
x07 --cli-specrows

If you plan to use OS worlds (run-os*) with native deps (for example ext-net / ext-curl-c / ext-sockets-c), run:

x07 doctor

See also: Install.

2) Create a project (canonical starting point)​

mkdir myapp
cd myapp
x07 init

x07 init creates both the project skeleton and the agent kit:

  • x07.json (with os and sandbox profiles)
  • x07.lock.json
  • x07-toolchain.toml (pins stable and declares docs + skills)
  • AGENT.md (self-recovery guide + canonical commands)
  • .agent/docs/ (offline docs; linked to the installed toolchain when available)
  • .agent/skills/ (skills pack; linked to the installed toolchain when available)
  • src/ (a minimal program)
  • tests/tests.json + tests/smoke.x07.json (a harness smoke test)

x07.json notes (common failure mode)​

  • The root world field is required (it’s used as a fallback when no run profile is selected).
  • For multi-profile projects, set the root world to the solve-* world you want for deterministic lint/repair (for example solve-pure), and run OS worlds via profiles (run-os*).

Contracts-by-example (copy/paste)​

If your project uses pinned rr policies, archive policies, DB migrations, or arch-driven budgets, start from a schema-valid example arch/ tree:

  • docs/examples/contracts_project/ (copy its arch/ into your project root)

If you are creating a publishable package repo (for x07 pkg publish), use x07 init --package instead of x07 init.

See also: Available skills.

3) The core loop: run → test (auto-repair)​

Run:

x07 run

x07 run runs the canonical auto-repair loop by default (format → lint → quickfix, repeatable). Use --repair=off when debugging, or --repair=memory to stage repairs without editing source files.

See: Running programs.

Diagnostics tip: many compiler errors include ptr=/... (a JSON Pointer into your x07AST) and sometimes moved_ptr=/... for ownership errors. Use x07 ast get --in src/main.x07.json --ptr /... to extract the failing node without manually counting indexes.

If you hit a compiler budget error (for example Budget: max locals exceeded or Budget: AST too large), see: Compiler limits.

Dependency tip: when compilation fails due to a missing module and prints hint: x07 pkg add ... --sync, x07 run can apply the hinted package add automatically and retry.

Run report tip: in run-os, the rr_* counters in x07 run --report ... are record/replay adapter stats and are not a count of real OS network requests.

If your program expects CLI arguments via argv_v1, pass them after -- and x07 run will encode them into input bytes:

x07 run -- tool --help

Run the deterministic harness (repo-defined suites):

x07 test --manifest tests/tests.json

For non-mutating, whole-project validation (full import graph + typecheck + backend-check, no emit), run:

x07 check --project x07.json

If the suite includes property-based tests, run:

x07 test --all --manifest tests/tests.json

If PBT finds a counterexample, convert it into a committable regression test:

x07 fix --from-pbt target/x07test/pbt/<...>/repro.json --write

See: Property-based testing and PBT repro → regression test.

4) Repairs: quickfixes and patches​

Two canonical repair mechanisms:

  • Quickfixes: x07 fix applies the tool-provided quickfix JSON patches deterministically.
  • Explicit patches: x07 ast apply-patch applies RFC 6902 JSON Patch.

Note: x07 run, x07 build, and x07 bundle apply quickfixes automatically by default (--repair=...). Use the explicit loop below when you want raw diagnostics or tighter control.

Example loop:

x07 lint --input src/main.x07.json
x07 fix --input src/main.x07.json --write
x07 lint --input src/main.x07.json

See: Repair loop.

If you need a human-reviewable artifact for an agent patchset, use:

  • x07 review diff (semantic diff; HTML)
  • x07 trust report (budgets/worlds/nondeterminism summary)

See: Review & trust artifacts.

5) Learn the language​

Key x07AST shapes:

  • expression call: ["head", arg1, arg2, ...]
  • identifier: "std.bytes.len"

6) Packages (external dependencies)​

Discover packages and versions:

Add a dependency:

# Add the latest non-yanked version from the index:
x07 pkg add NAME --sync

# Or pin explicitly:
x07 pkg versions NAME
x07 pkg add NAME@VERSION --sync

# Remove a dependency:
x07 pkg remove NAME --sync

Notes:

  • x07 pkg add edits x07.json. With --sync, it also updates x07.lock.json.
  • Canonical project manifests use x07.project@0.3.0. x07.project@0.2.0 is accepted for legacy manifests, but project.patch requires @0.3.0.
  • x07 pkg add NAME@VERSION is safe to re-run: if the same dep+version already exists, it succeeds as a no-op. If the dep exists at a different version, pick a version explicitly and update the project deps.
  • If a module import fails and you don’t know which package provides it, use x07 pkg provides <module-id>.
  • If you’ve added a package but don’t know which modules it exports, use x07 doc <package-name> (example: x07 doc ext-net).
  • For builtin std.* modules (file: <builtin>), use x07 doc std.<module> (example: x07 doc std.bytes).
  • For package-provided std.* modules, run x07 doc <module-id> --project x07.json after adding the package (example: after x07 pkg add ext-net --sync, run x07 doc std.net.tcp --project x07.json).
  • For special forms (pipes, task.scope_v1, budget.*) and non-module builtins (example: std.brand.*), use x07 guide + linked docs pages (not x07 doc).
  • For structured encodings, prefer branded bytes + validators over ad-hoc parsing (see std.brand.cast_view_v1 / std.brand.cast_view_copy_v1 in x07 guide and meta.brands_v1 in schema-derived modules).
  • For streaming transforms, prefer std.stream.pipe_v1 and std.io.bufread over manual loops (more predictable allocations; fewer borrow/ownership hazards).
  • x07 pkg lock defaults to the official registry index when fetching is required; override with --index or forbid network with --offline.
  • In CI, run x07 pkg lock --project x07.json --check.
  • When the index can be consulted, x07 pkg lock --check also fails on yanked dependencies and active advisories unless explicitly allowed (--allow-yanked / --allow-advisories).
  • If you must force a transitive dependency version, use project.patch in x07.json (requires x07.project@0.3.0).
  • Some packages may declare required helper packages via meta.requires_packages. When present, x07 pkg lock can add and fetch these transitive deps, but agents should treat the capability map + templates as canonical so the dependency set is explicit.
  • Examples of transitive helpers: ext-net pulls ext-curl-c/ext-sockets-c/ext-url-rs, and ext-db-sqlite pulls ext-db-core (which pulls ext-data-model).

If you hit a dependency version conflict, the canonical repair loop is:

x07 pkg versions NAME
x07 pkg remove NAME --sync
x07 pkg add NAME@VERSION --sync

See also: Packages & projects.

7) World selection (OS worlds)​

  • run-os: real OS adapters (disk/network/time/env/process)
  • run-os-sandboxed: policy-gated OS adapters (defaults to a VM boundary; still not a hardened sandbox if you mount secrets or enable networking)

For run-os-sandboxed, start from a schema-valid policy template instead of hand-writing JSON:

x07 policy init --template worker --out policy/sandbox.base.json --mkdir-out

Prefer profiles (x07.json.default_profile + x07.json.profiles) so agents usually run:

  • x07 run (project default)
  • x07 run --profile os / x07 run --profile sandbox (explicit intent)

See: OS worlds.

8) Machine-first discovery surfaces​

  • CLI surface: x07 --cli-specrows
  • Schemas: spec/*.schema.json (and the synced copies on x07lang.org under /agent/.../schemas/)
  • External packages index: GET /agent/latest/packages/index.json on x07lang.org
  • Offline docs: x07up docs path --json
  • Local module inspection: x07 doc <module-or-symbol> (example: x07 doc std.bytes)
  • Local package inspection (project deps): x07 doc <package-name> (example: x07 doc ext-net)
  • Built-in reference guide: x07 guide

9) Known-good reference projects (copy/paste)​

The x07 repo ships CI-gated example projects under docs/examples/agent-gate/:

  • cli-newline (pure CLI payload parsing)
  • cli-ext-cli (CLI args via ext-cli + argv_v1)
  • web-crawler-local (sandboxed OS networking + --allow-host, against a local fixture site)

For the canonical package-focused set (examples + scenarios), see: Agent workflow.

See also: Patch-based recipes.

10) By-example tutorials (long-form)​