# Ainativelang

> AINL helps turn AI from "a smart conversation" into "a structured worker." It is designed for teams building AI workflows that need multiple steps, state and memory, tool use, repeatable execution, validation and control, and lower dependence on long prompt loops. AINL is a compact, graph-canonical, AI-native programming system for (READ: README)

- **Type:** MCP server
- **Install:** `agentstack add mcp-sbhooley-ainativelang`
- **Verified:** Pending review
- **Seller:** [sbhooley](https://agentstack.voostack.com/s/sbhooley)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [sbhooley](https://github.com/sbhooley)
- **Source:** https://github.com/sbhooley/ainativelang
- **Website:** https://ainativelang.com

## Install

```sh
agentstack add mcp-sbhooley-ainativelang
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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**:

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

Fallback if `pipx` is unavailable:

```bash
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/WHO_IS_THIS_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](https://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](https://ainativelang.com/install) |
| **ZeroClaw** | `zeroclaw skills install https://github.com/sbhooley/ainativelang/tree/main/skills/ainl` | [ainativelang.com/install](https://ainativelang.com/install) |
| **Hermes Agent** | `ainl install-mcp --host hermes` | [ainativelang.com/install](https://ainativelang.com/install) |
| **Claude Code** | `pip install 'ainativelang[mcp]'` → add `ainl-mcp` to MCP config | [ainativelang.com/mcp](https://ainativelang.com/mcp) |
| **Any MCP host** | `pip install 'ainativelang[mcp]'` → run `ainl-mcp` (stdio) | [ainativelang.com/mcp](https://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](https://ainativelang.com/armaraos)** — desktop agent OS with dashboard, **Hands**, scheduled **`ainl run`**, and MCP authoring. See **[`docs/competitive/ARMARAOS_GTM.md`](docs/competitive/ARMARAOS_GTM.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/token_savings_results.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/WHEN_AINL_DOES_NOT_HELP.md)** · **[`docs/competitive/VS_HAND_WRITTEN_RUNNER.md`](docs/competitive/VS_HAND_WRITTEN_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/benchmark_compile_once_run_many.py) → [`tooling/compile_once_run_many_results.json`](tooling/compile_once_run_many_results.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/benchmark_token_savings.py) → [`tooling/token_savings_results.json`](tooling/token_savings_results.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/benchmark_authoring_density.py) → [`tooling/authoring_density_results.json`](tooling/authoring_density_results.json) |
| Authoring vs hand-written LangGraph | **~1.9–2.0×** fewer source tokens (authoring only, not runtime) | [`scripts/benchmark_competitor_baselines.py`](scripts/benchmark_competitor_baselines.py) → [`tooling/competitor_baseline_tokens.json`](tooling/competitor_baseline_tokens.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/VS_HAND_WRITTEN_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 →](https://ainativelang.com/benchmark)** · **[`BENCHMARK.md`](BENCHMARK.md)** (source tables + methodology) · **[`docs/CLAIMS_AND_EVIDENCE.md`](docs/CLAIMS_AND_EVIDENCE.md)** (claim crosswalk) · **[When AINL does not help →](docs/competitive/WHEN_AINL_DOES_NOT_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/LONG_TERM_FIXES_TRACKER.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/PRODUCTION_EVIDENCE.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 →](https://ainativelang.com/docs) · [Quick start →](https://ainativelang.com/quickstart) · [What is AINL? →](https://ainativelang.com/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](https://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/OPEN_CORE_DECISION_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/A2A_ADAPTER.md](docs/integrations/A2A_ADAPTER.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 (**[HTTP_MACHINE_PAYMENTS.md](docs/integrations/HTTP_MACHINE_PAYMENTS.md)**), practitioner readiness (**[AGENTIC_PROTOCOLS_PRACTITIONER_READINESS.md](docs/integrations/AGENTIC_PROTOCOLS_PRACTITIONER_READINESS.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](https://github.com/sbhooley)
- **Source:** [sbhooley/ainativelang](https://github.com/sbhooley/ainativelang)
- **License:** Apache-2.0
- **Homepage:** https://ainativelang.com

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sbhooley-ainativelang
- Seller: https://agentstack.voostack.com/s/sbhooley
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.