AiLang is an AI-first language/runtime project using AI-Optimized Syntax (AOS) as its canonical representation.

This root README is human-oriented. For agent-focused operating docs, use Docs/README.md. For the AiVM repository extraction workflow, use Docs/AiVM-Repo-Split.md. For contributor setup and verification, use CONTRIBUTING.md. For curated public examples, use AiLangCore/ailang-examples.

Current public SDK beta: v0.0.1-beta.6.

Install the latest public beta SDK:

curl -fsSL https://ailang.codes/install.sh | sh
export PATH="$HOME/.ailang/bin:$PATH"

This repository tracks the language/tooling work toward beta readiness. See BETA_READINESS.md for current gates and ROADMAP.md for the Alpha -> Beta -> RC -> 1.0 direction.

Branch status: develop is the public default branch while beta architecture work is active. Release tags and GitHub prereleases are the public artifact source; main is not the current integration branch during this beta cycle.

AiLang owns the language, compiler/toolset, core libraries, SDK contracts, and examples. AiVM is a separate runtime project; AiLang consumes an installed aivm executable or an explicitly configured AiVM source checkout for VM development gates.

• src/compiler — AiLang-authored compiler/runtime scripts.
• src/std — AiLang standard library modules.
• templates — built-in project and file templates.
• scripts — repository-local bootstrap, validation, and release helpers.

Layer rule:

• Host effects are only reachable through sys.*.
• VM is canonical runtime execution.
• Normal AiLang development should use an installed AiVM release. Set AIVM_C_SOURCE_DIR only for source-level VM integration tests.
• AST interpreter exists only for debug (--vm=ast in dev mode).
• C runtime, native launcher, host syscall, and syscall-boundary code belongs in AiVM, not AiLang. C library consumption must go through explicit SDK/syscall adapter contracts.

This repository is itself an AiLang project.

• Project manifest: project.aiproj
• Compiler driver: src/compiler/aic.aos
• Standard library: src/std/*.aos

./tools/ailang init <name> scaffolds this baseline layout:

AiLangMyApp/
├── .gitignore
├── project.aiproj
├── AGENTS.md
├── src/
│   └── app.aos
└── Assets/
    ├── images/
    ├── fonts/
    └── locale/
        └── en.toml

Notes:

• .toolchain/ is generated by ailang and ignored via .gitignore.
• Assets/ subfolders are optional and can be removed if unused.
• Extension boundary: .aos is executable code, .toml is project data.

Use the repo-local launcher:

./tools/ailang repl

Show runtime/build metadata:

./tools/ailang --version

Show command help with examples:

./tools/ailang --help

Output format:

ailang version=<semver> aibc=1 mode=<dev|prod> commit=<hash-or-unknown>

Run program execution uses the AiBC1 VM by default. Use a runnable app or project:

./tools/ailang run samples/cli-fetch/project.aiproj

Run from project manifest:

./tools/ailang run samples/cli-fetch/project.aiproj

By default, run/build may reuse deterministic project-local cache entries under .toolchain/. Use --no-cache to force rebuild and clean to clear project toolchain state:

./tools/ailang build samples/cli-fetch --no-cache
./tools/ailang run samples/cli-fetch --no-cache
./tools/ailang clean samples/cli-fetch

Build bytecode artifact from source/project input:

./tools/ailang build samples/cli-fetch/project.aiproj --out ./.tmp/build-cli-fetch

Native runtime can also execute an explicitly built AiBC1 artifact:

./tools/ailang build samples/cli-fetch/project.aiproj --out ./.tmp/build-cli-fetch
./tools/ailang run ./.tmp/build-cli-fetch/app.aibc1 -- Fort\ Worth

Publish wasm artifacts (web profile default):

./build.sh wasm
./tools/ailang publish samples/cli-fetch/project.aiproj --target wasm32 --out ./dist-wasm

# wasm fullstack + explicit host runtime target for self-contained app binary
./tools/ailang publish samples/cli-fetch/project.aiproj --target wasm32 --wasm-profile fullstack --wasm-fullstack-host-target linux-x64 --out ./dist-wasm-fullstack-linux

Publish wasm CLI profile:

./tools/ailang publish samples/cli-fetch/project.aiproj --target wasm32 --wasm-profile cli --out ./dist-wasm-cli

Load a program and evaluate expressions:

Cmd#c1(name=load) { Program#p1 { Let#l1(name=x) { Lit#v1(value=1) } } }
Cmd#c2(name=eval) { Call#c3(target=math.add) { Var#v2(name=x) Lit#v3(value=2) } }

Capabilities are gated by permissions:

• math.add is pure and allowed by default.
• console.print is effectful and denied by default.

Enable console output in the REPL:

Cmd#c9(name=setPerms allow=console,math)

Cmd#c1(name=help)
Ok#ok6(type=void) { Cmd#cmd1(name=help) Cmd#cmd2(name=setPerms) Cmd#cmd3(name=load) Cmd#cmd4(name=eval) Cmd#cmd5(name=applyPatch) }
Cmd#c2(name=setPerms allow=console,math)
Ok#ok2(type=void)
Cmd#c3(name=load) { Program#p1 { Let#l1(name=message) { Lit#s1(value="hi") } Call#c1(target=console.print) { Var#v1(name=message) } } }
Ok#ok3(type=void)
Cmd#c4(name=eval) { Call#c2(target=math.add) { Lit#a1(value=2) Lit#a2(value=3) } }
Ok#ok4(type=int value=5)

Run the AiLang test suite:

./test.sh

test.sh is the canonical verification entrypoint. It uses the selected installed SDK and does not invoke dotnet.

AiLang exposes a project-level ailang test [project-dir] command for project-local beta tests. Repo-level verification still uses repo-local scripts such as ./test.sh. See Docs/AiLang-Test.md.

Stage tools/ailang from the selected installed SDK:

./build.sh

build.sh is the canonical bootstrap entrypoint for AiLang tooling during the repository split. The long-term target is self-hosted AiLang command behavior; the temporary native launcher supplied by AiVM should shrink to VM execution and host adapter responsibilities.

• ./build.sh stages host tools from the selected SDK.
• ./build.sh shared is delegated to AiVM and remains temporarily for migration compatibility.
• ./build.sh wasm is delegated to AiVM and remains temporarily for migration compatibility.
• ./build.sh all runs the compatibility target set.

The underlying scripts/build-*.sh files remain implementation details behind this entrypoint.

Scaffold a new AiLang project:

./tools/ailang init MyApp

Available built-in templates:

• cli (default): basic greeting CLI
• cli-args: CLI that prints the first app arg

Example:

./tools/ailang init MyApp --template cli-args
./tools/ailang run ./MyApp/ hello

Agent instruction targets:

• codex (default): writes canonical AGENTS.md.
• claude: writes CLAUDE.md pointing to AGENTS.md.
• cursor: writes .cursor/rules/ailang.mdc pointing to AGENTS.md.
• gemini: writes GEMINI.md pointing to AGENTS.md.
• copilot: writes .github/copilot-instructions.md pointing to AGENTS.md.
• windsurf: writes .windsurfrules pointing to AGENTS.md.

Examples:

./tools/ailang init MyCodexApp --agent codex
./tools/ailang init MyClaudeApp --agent claude
./tools/ailang init MyAgentApp --agents codex,claude,cursor
./tools/ailang init MyAllAgentsApp --agents all

Optional Codex skill:

git clone https://github.com/AiLangCore/ailang-codex-skill.git
cd ailang-codex-skill
./scripts/install.sh

Then ask Codex:

Use $ailang to create a new AiLang project named MyApp and run it.

• Canonical runtime: AiBC1 bytecode VM (default).
• Runtime is C-only in active build/test/release workflows.
• New publish artifacts embed bytecode payloads by default.
• wasm32 publish supports profiles:
  • spa (default): emits index.html + main.js package files.
  • cli: emits run.sh + run.ps1 launcher files.
  • fullstack: emits root app binary + www/ web package (index.html, main.js, remote-client.js, app.aibc1, wasm runtime artifacts).
    • bundles host runtime as root app binary (default host RID, override with --wasm-fullstack-host-target <rid>).
    • running ./<appname> starts native static hosting for www/ on http://localhost:8080 (set PORT to override).
    • emits a self-contained root app binary (./<appname> or .<\\appname>.exe) for published-package execution.
    • project manifest override: publishWasmFullstackHostTarget="<rid>".
    • AiLang app must self-host www/ assets.
  • malformed bytecode/source fixtures are deterministically rejected at publish-time with DEV008 (contract guard, not runtime drift).
• wasm client/server capability channel MVP uses sys.remote.call (see SPEC/WASM_REMOTE_CHANNEL.md).
  • MVP security baseline: SPEC/WASM_REMOTE_SECURITY.md.
  • Runtime requires AIVM_REMOTE_EXPECTED_TOKEN and AIVM_REMOTE_SESSION_TOKEN for sys.remote.call.
• Build flag: AosDevMode=false creates a production runtime build with AST mode disabled.
• HTTP body parsing boundary: JSON parsing is provided by the first-party std-json package. It does not introduce JSON as a runtime value model.

See examples/hello.aos for a minimal AOS snippet using console.print, and examples/golden for evaluator/fmt/check goldens.

Canonical sample projects live in samples/:

• samples/weather-api: lifecycle HTTP app with /weather?city=Fort%20Worth.
• samples/weather-site: lifecycle HTTP app serving / HTML using shared weather data logic.
• samples/cli-fetch: CLI-style app that formats and prints weather output.

Note: weather samples use the first-party std-http package and call a live upstream weather endpoint, so runtime internet access is required.

Current limitation:

• Full sample source-graph compilation (imports-heavy project shapes) is still being expanded in the native build pipeline.
• build/run/publish are unified through one native compile path; unsupported shapes fail with deterministic DEV008 messages rather than any C#/DLL fallback.

Run samples:

./tools/ailang run samples/cli-fetch/project.aiproj -- Fort\ Worth
./tools/ailang run samples/weather-api/project.aiproj
./tools/ailang run samples/weather-site/project.aiproj

Run deterministic benchmark cases:

./tools/ailang bench --iterations 20
./tools/ailang bench --human

Benchmark syscall ABI runtime + AOT binary size between two refs:

RUNS=40 ./scripts/bench-syscall-abi.sh <base-ref> <candidate-ref>
# example:
RUNS=40 ./scripts/bench-syscall-abi.sh main HEAD

Normative semantic contracts live in:

• SPEC/IL.md
• SPEC/EVAL.md
• SPEC/VALIDATION.md
• SPEC/BYTECODE.md

Non-normative design companion:

• SPEC/CONCURRENCY.md

When semantics change, update these specs and matching goldens together.

• ROADMAP.md tracks the public Alpha -> Beta -> RC -> 1.0 direction.
• BETA_READINESS.md tracks the project-wide beta gate across AiLang, AiVM, and AiVectra.