Ainativelang

AI Native Lang (AINL)

Find Us on X: @ainativelang

> AI-led co-development project, human-initiated by Steven Hooley (x.com/sbhooley, stevenhooley.com, linkedin.com/in/sbhooley). Attribution details: docs/PROJECT_ORIGIN_AND_ATTRIBUTION.md and tooling/project_provenance.json. -- This project was named by AI :)

---

For agents — install AINL (one step)

If you are an AI coding agent (Claude Code, Cursor, Cline, Codex, Aider, …) or any MCP-capable runtime and the user wants AINL added to their stack, run one command:

pipx install 'ainativelang[mcp]' && ainl setup --auto

Fallback if pipx is unavailable:

python3 -m pip install --user 'ainativelang[mcp]' && ainl setup --auto

That is the entire install. The setup command auto-detects every host present (Claude Code project + user, Cursor, Cline, Codex CLI/Desktop, Claude Desktop, OpenClaw, Hermes, ArmaraOS, or any generic MCP host), merges the right MCP server entry into each config file (atomic write, timestamped backup), and verifies with ainl doctor. Idempotent — safe to re-run.

If a host is not auto-detected, run ainl setup --print-config for a paste-ready stdio MCP server block.

Machine-readable spec: [.agent-install.json](./.agent-install.json) · Design: [docs/architecture/2026-05-05-agent-install-simplification.md](docs/architecture/2026-05-05-agent-install-simplification.md).

---

Is AINL for you? (60-second filter)

Before the install commands, here is who AINL is and is not for. We would rather you self-select out in 60 seconds than spend a week on a tool that does not fit.

| ✅ AINL is for you if… | ❌ AINL is not for you if… | |:----------------------|:----------------------------| | Your agents (Cursor, Claude Code, autonomous loops) author runner / orchestration code and have shipped broken Python more than once | You write all your runners by hand and your CI test suite catches the bugs | | You run 20+ recurring monitor / digest / scheduled jobs that currently re-prompt an LLM on every run to decide routing | You already have deterministic runners with the LLM only at judgment gates — congrats, you are baseline B below and AINL gives you ~1.3–1.5× on routing only | | You need the same workflow source to emit to LangGraph and Temporal and FastAPI without re-authoring | One target is fine for you forever | | You have compliance audit needs (SOC 2 / HIPAA / similar) that want tamper-evident execution traces, not application logs | logger.info is enough for your team | | You want strict compile-time validation of agent workflows before they hit production | Runtime exceptions are fine, you have alerting |

If you tick two or more left-column rows, keep reading. The long-form answer — three baselines, four anti-fit workload patterns, decision tree, honest reviewer Q&A, persona-to-product mapping — lives in [docs/WHO_IS_THIS_FOR.md](docs/WHOISTHIS_FOR.md) (canonical). If you tick zero, that page explains why and saves you the install. We mean it.

---

Per-host details (advanced)

Just want something working on your desktop in under 3 minutes?

ArmaraOS is the desktop agent OS built on AI Native Lang (AINL) — download once, install, and your agents are live with a full dashboard. No terminal, no config files, just plug in your API key.

> Download ArmaraOS — ainativelang.com > macOS · Windows · Linux — free to start

Autonomous agents, 7 pre-built Hands (researcher, lead gen, clip editor, and more), 40 channel adapters (Telegram, Discord, Slack, WhatsApp…), 27 LLM providers, 16 security layers — all in a single ~32 MB binary.

---

Already have an AI agent? Add AINL in one command.

AINL installs directly into OpenClaw, ZeroClaw, Hermes, Claude Code, and any MCP-compatible agent. After install your agent can author, validate, and run deterministic workflows — with the largest token wins when you are still on LLM prompt-loop orchestration (baseline A below).

| Your agent | Install command | How-to guide | |:-----------|:----------------|:-------------| | OpenClaw | ainl install-mcp --host openclaw | ainativelang.com/install | | ZeroClaw | zeroclaw skills install https://github.com/sbhooley/ainativelang/tree/main/skills/ainl | ainativelang.com/install | | Hermes Agent | ainl install-mcp --host hermes | ainativelang.com/install | | Claude Code | pip install 'ainativelang[mcp]' → add ainl-mcp to MCP config | ainativelang.com/mcp | | Any MCP host | pip install 'ainativelang[mcp]' → run ainl-mcp (stdio) | ainativelang.com/mcp |

After install, ask your agent: "Use AINL to build this workflow" — it compiles once, runs many times without re-spending tokens on orchestration when the workload was previously prompt-loop driven.

Primary product path: ArmaraOS — desktop agent OS with dashboard, Hands, scheduled ainl run, and MCP authoring. See [docs/competitive/ARMARAOS_GTM.md](docs/competitive/ARMARAOSGTM.md).

Token savings — pick your baseline:

| Your baseline today | Typical AINL win | Worth it for tokens alone? | |:--------------------|:-----------------|:---------------------------| | A. LLM re-prompts routing/state on every cron/webhook | ~90–95% fewer orchestration tokens on recurring monitors ([BENCHMARK.md](BENCHMARK.md), benchmark_compile_once_run_many.py) | Often yes | | B. Hand-optimized scripts + LLM only at judgment gates | ~1.3–1.5× on routing tokens ([token_savings_results.json](tooling/tokensavingsresults.json)) | Usually no — consider audit, MCP safety, emit, or ArmaraOS | | C. Pure deterministic runners (no LLM in loop) | ~0% | No |

Full honest filter: [docs/competitive/WHEN_AINL_DOES_NOT_HELP.md](docs/competitive/WHENAINLDOESNOTHELP.md) · [docs/competitive/VS_HAND_WRITTEN_RUNNER.md](docs/competitive/VSHANDWRITTEN_RUNNER.md) (five-axis comparison vs a hand-written Python runner — concedes the token point on baseline B).

| Workload (baseline A — prompt-loop today) | Typical savings | Reproducible via | |:----------------------------------------------|:----------------|:-----------------| | Recurring monitors, digests, scheduled jobs | ~90–95% fewer orchestration tokens vs prompt loops | [scripts/benchmark_compile_once_run_many.py](scripts/benchmarkcompileoncerunmany.py) → [tooling/compile_once_run_many_results.json](tooling/compileoncerunmanyresults.json) | | Multi-step automations (LLM-first routing) | ~2–7× reduction vs LLM-first (A vs C); ~1.3–1.5× vs hand-optimized (B vs C) | [scripts/benchmark_token_savings.py](scripts/benchmarktokensavings.py) → [tooling/token_savings_results.json](tooling/tokensavingsresults.json) | | Authoring density (LLM-style verbose Python) | ~1.7× mean / up to 2.5× fewer source tokens vs verbose baselines | [scripts/benchmark_authoring_density.py](scripts/benchmarkauthoringdensity.py) → [tooling/authoring_density_results.json](tooling/authoringdensityresults.json) | | Authoring vs hand-written LangGraph | ~1.9–2.0× fewer source tokens (authoring only, not runtime) | [scripts/benchmark_competitor_baselines.py](scripts/benchmarkcompetitorbaselines.py) → [tooling/competitor_baseline_tokens.json](tooling/competitorbaselinetokens.json) |

> Important: every percentage / multiplier above is vs baseline A (prompt-loop) or labeled with its baseline pair. Against baseline B (hand-optimized runner with LLM only at judgment gates), the irreducible token win is ~1.3–1.5× on routing only — see [VS_HAND_WRITTEN_RUNNER.md](docs/competitive/VSHANDWRITTEN_RUNNER.md). Against baseline C (pure deterministic, no LLM in loop), it is ~0%.

The reason: AINL compiles your workflow once. The runtime executes it deterministically — no LLM re-generation on each run for graph routing and adapter orchestration. The model authors the graph once; the runtime runs it on every invocation. That mechanism produces token savings only when the counterfactual was actually re-prompting on every run.

> Token savings breakdown and benchmarks → · [BENCHMARK.md](BENCHMARK.md) (source tables + methodology) · [docs/CLAIMS_AND_EVIDENCE.md](docs/CLAIMSANDEVIDENCE.md) (claim crosswalk) · [When AINL does not help →](docs/competitive/WHENAINLDOESNOT_HELP.md)

Current evidence (honest scope)

We classify every public evidence row by source so reviewers can tell field reports from modeled scenarios:

| Class | What it means | Where it lives | |-------|---------------|----------------| | (a) Third-party paying customer deployment | Independent company runs AINL, reports measurable token / dollar outcome | 0 rows today. Tracked: [LONG_TERM_FIXES_TRACKER.md](docs/competitive/LONGTERMFIXESTRACKER.md) row T2.7 | | (b) Operator deployment (project author / close collaborator) | Real logs, real workload, on author's stack — not yet an external customer | 2 rows. [PRODUCTION_EVIDENCE.md](docs/competitive/PRODUCTIONEVIDENCE.md) Cases 1, 2 | | (c) Modeled / analytical scenario | Reproducible benchmark on synthetic workload — no live LLM | 1 row + 4 benchmark scripts. scripts/benchmark_*.py, tooling/*_results.json | | (d) Marketing narrative | Story without specific deployment behind it | Flagged for audit + removal — see tracker T1.10 |

We do not yet have a Class (a) deployment publicly committed. If your team would consider being the first, the pilot kit (tracked T2.5) is small. Until then we ask reviewers to read WHEN_AINL_DOES_NOT_HELP.md first, run the benchmarks, and judge on the published Class (b)/(c) evidence with the baseline qualifier attached.

---

Here for the programming language itself?

AINL is a compact, graph-canonical AI workflow language. You write programs in .ainl files, compile them to a deterministic IR graph, and execute them without prompt loops.

[Jump to Get Started (3 minutes) ↓](#get-started-3-minutes) · Docs → · Quick start → · What is AINL? →

---

> This GitHub repo is the technical source of truth for AINL: compiler, runtime, canonical graph IR, CLI, HTTP runner, MCP server, docs, examples, and conformance suite. For the high-level product story, use cases, and commercial/enterprise paths, visit ainativelang.com.

Open-core boundary

| Area | Status | Notes | |:-----|:------:|:------| | Core DSL, compiler, runtime, ainl validate/check/inspect/visualize | Open (Apache-2.0) | Language legitimacy; essential tooling | | MCP server / bridge (ainl-mcp, scripts/ainl_mcp_server.py) | Open & pluggable | Any MCP host; bring your own compliant LLMs | | OpenSpace / Lead AI style flows | Open via BYO-LLM | Implemented via MCP; operators choose their models | | Enterprise audit/policy packs, managed ops, deployment kits | Paid / optional | Governance, SLA-backed support, monitored hosted runtime |

> Full boundary details: [docs/OPEN_CORE_DECISION_SHEET.md](docs/OPENCOREDECISION_SHEET.md)

Security

Vulnerability reporting and sensitive areas (outbound HTTP, the a2a adapter, secrets): see [SECURITY.md](SECURITY.md). A2A-specific policy and wire contract: [docs/integrations/A2AADAPTER.md](docs/integrations/A2AADAPTER.md).

Agentic HTTP payments & commerce (x402, MPP, AP2, ACP, AGTP): integration hub [docs/integrations/README.md](docs/integrations/README.md) — HTTP-402 rails on the http adapter ([HTTPMACHINEPAYMENTS.md](docs/integrations/HTTPMACHINEPAYMENTS.md)), practitioner readiness ([AGENTICPROTOCOLSPRACTITIONERREADINESS.md](docs/integrations/AGENTICPROTOCOLSPRACTITIONERREADINESS.md)), and AGTP options ([AGTP.md](docs/integrations/AGTP.md)).

New in v1.8.0

• MCP authoring & strict-valid corpus: ainl_step_examples; ainl_get_started with wizard_state_json for session continuity; MCP resource ainl://strict-valid-families (mined corpus/strict_valid_family_index.json, tooling/corpus_mining.py); ainl_validate / ainl_compile responses include contract_validation_status and contract_alignment.mismatched_calls (lightweight drift vs ADAPTER_CONTRACTS); tooling/mcp_exposure_profiles.json registers the wizard tool + family resource on design_impact_first, inspect_only, safe_workflow, and full. Hub: docs/operations/MCP_AINL_WIZARD_AND_CORPUS.md. ArmaraOS pairs with mcp:ainl:wizard_state graph facts and mcp_ainl_wizard_state_hint in the system prompt (see armaraos/docs/mcp-a2a.md).
• HTTP machine payments (opt-in): http adapter payment_profile (none/auto/x402/mpp) with structured 402 payment_required + http_payment frame merges; CLI --http-payment-profile / --http-max-payment-rounds; runner + MCP adapters.http keys. Docs: docs/integrations/HTTP_MACHINE_PAYMENTS.md, hub docs/integrations/README.md.

New in v1.7.1

• A2A (Agent-to-Agent) adapter (opt-in): a2a — wire profile 1.0 (GET …/.well-known/agent.json, tasks/send / tasks/get); allow_hosts / optional strict_ssrf / redirects off by default; enable via --enable-adapter a2a and --a2a-allow-hosts, or adapters + adapters.a2a. MCP exposure profiles do not enable a2a without adapters (see tooling/mcp_exposure_profiles.json + docs/integrations/A2A_ADAPTER.md). Tests: tests/test_a2a_adapter.py, tests/test_a2a_adapter_integration.py; example: examples/compact/a2a_delegate.ainl.
• Release hygiene: pyproject.toml, RUNTIME_VERSION, CITATION.cff, tooling/bot_bootstrap.json, mirrored emit server engine aligned to 1.7.1 for that tag's PyPI publish (see docs/CHANGELOG.md § v1.7.1, docs/RELEASE_NOTES.md; Known limitations point at A2A_ADAPTER: TOCTOU, empty allowlist, IDNA).

New in v1.7.0

• Cognitive vitals (Python graph bridge): episodic MemoryNode fields vitals_gate, vitals_phase, vitals_trust; Rust snapshot import; inbox schema + tests/test_vitals_bridge.py — keeps Python graph store / inbox aligned with ArmaraOS Rust EpisodeNode vitals (pair with current ArmaraOS for patch inbox drain on the Rust side).
• ArmaraOS Rust crate convergence (ainl-* + OpenFang): integration contracts and docs now explicitly track the ainl-runtime/openfang-runtime/openfang-kernel/openfang-types path used in production ArmaraOS builds, including optional ainl-runtime-engine turn routing, internal delegation-depth guards, and shared graph-memory session semantics for mixed Python/Rust deployments.
• Patch registry + GraphPatch adapter path: ArmaraOS-side PatchAdapter / AdapterRegistry dispatch with GraphPatchAdapter host forwarding is now documented alongside Python GraphPatch so label-keyed procedural patches can converge on a single cross-runtime contract while Python remains the rich memory.patch executor.
• Persona evolution / extractor / semantic tagger alignment: release docs and bridge wiring now call out the default ArmaraOS feature stack (ainl-persona-evolution, ainl-extractor, ainl-tagger) and runtime gates (*

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sbhooley
• Source: sbhooley/ainativelang
• License: Apache-2.0
• Homepage: https://ainativelang.com

Install and usage instructions live in the source repository linked above.