lugh
Lugh can connect to a GitHub MCP server (and ships a simulated GitHub MCP server in its playground) so agents can call GitHub tools under a policy gate, with each tool's effect derived from its MCP annotations and approvals or denials enforced before the call is sent.
Lugh can connect to a Notion MCP server using the same config format as Claude Desktop, exposing Notion tools to agents with policy enforcement applied before any call is sent.
Lugh can connect to a Slack MCP server alongside other MCP servers, letting agents invoke Slack tools while policy rules decide whether each call is allowed, requires human approval, or is blocked.
Ships an embedded SQLite database adapter with db.exec and db.query statements, enabling agents to create tables, insert records and query data as part of a Lugh program.
Lugh
A programming language for AI agents that work through the infrastructure that already exists — APIs, websites, shells, files, SaaS apps and desktop software.
Lugh is named for the Irish god Samildánach, "skilled in all the arts". A Lugh program declares what an agent may touch, how much it may spend, and when a human must approve — and the runtime enforces all of it on every single action.
agent FlightScout
use http, fs, shell, llm
budget time 2m, calls 20
policy
allow read, write
ask human before send, spend, submit
deny delete
goal "Find the cheapest Delhi to Dublin fare under 45000 INR"
let fares = attempt
http.get "https://api.flights.example/search?from=DEL&to=DUB" as json
otherwise
fs.read "examples/fares.json" as json
let best = pick lowest price from fares
ensure best.price < 45000 else stop "Nothing under budget"
ask human "Book {best.airline} at INR {best.price}?" -> ok
when ok
send console "#travel" "Booking {best.airline}"Try it
In your browser: the Lugh Playground runs Lugh compiled to WebAssembly, with nothing to install.
From a terminal, no install:
npx lugh-lang run program.lughruns a program in the same sandbox and prints a policy log (test,checkandsandboxwork too).For AI agents, over MCP:
npx lugh-lang mcpis an MCP server, listed in the MCP Registry asio.github.Ashutosh3142857/lugh. An agent can read the language reference, write a program, check it and dry-run it, then show you the policy log:{ "mcpServers": { "lugh": { "command": "npx", "args": ["-y", "lugh-lang", "mcp"] } } }Locally:
lugh playgroundserves the same page on http://127.0.0.1:8000.In VS Code: the extension adds highlighting, snippets, live error checking and run commands.
In the playground, adapters act on a simulated world: a few files, an HTTP API
and four MCP servers (notes, GitHub, payments, mail), created fresh for every
run. Nothing real is touched, but every call still passes the policy gate, so
allow, ask and deny behave exactly as they do when installed, and each run
ends with a policy log. Choose whether approvals are answered yes or no, share a
program as a link, or run the same sandbox from a terminal or an agent with
npx lugh-lang. Every run has a 10-second
budget that also stops runaway computation.
Related MCP server: MIDAS
Why a new language
Agent frameworks keep the things that matter most — permissions, spending limits, human approval, recovery from failure, an audit trail — outside the code, in config files and prompts. Lugh makes them syntax, so they are checked before a program runs and recorded while it runs.
Concern | In Lugh |
What the agent may do |
|
Runaway cost or loops |
|
Human approval |
|
Brittle integrations |
|
Proof of what happened | Every effect written to an audit log |
Quick start
Python runtime: Python 3.9+, no dependencies. Native runtime: Rust 1.70+ to build.
git clone https://github.com/Ashutosh3142857/lugh-lang.git
cd lugh-lang
# Native runtime (Rust)
(cd core && cargo build --release)
./core/target/release/lugh examples/research_desk.lugh --yes --eval
# Reference runtime (Python)
python lugh.py examples/flight_scout.lugh --check # list every action and its policy
python lugh.py examples/flight_scout.lugh # run, approving actions as you go
python lugh.py examples/flight_scout.lugh --yes # run with auto-approvalOptional:
pip install playwright && playwright install chromiumenables thebrowseradapter.Set
ANTHROPIC_API_KEYsothinkuses a real LLM instead of the local stub (LUGH_MODELselects the model).
What's new in v0.2
Primitives drawn from the foundational ML literature (details):
let urgent = attend to inbox by "invoice overdue" top 2 # attention
let deadline = point to "payment due by date" in mail.body # grounded extraction
remember "deadline" = deadline keep 7d # gated memory
let found = recall like "northwind deadline" # content-addressed memory
let matched = pairs i from invoices, p from payments where i.amount == p.amount
let fare = consensus # ensemble agreement
pick lowest price from fs.read "a.json" as json
pick lowest price from fs.read "b.json" as json
let quote = attempt auto # learned route order
http.get "https://api.example.com/quote" as json
fs.read "cache.json" as json
refine note with think "Improve this" with fare until count note > 20 rounds 2
let plan = simplest of plans # minimum description length
let fresh = novelty fare # compression novelty
each m in matched parallel 4 # pipelined loopRun the full demo:
python lugh.py examples/research_desk.lugh --yes --evalAgents that write their own programs
lugh plan "Add a passport photos reminder and list my visa notes" --use mcp --runAn LLM writes the Lugh program, the compiler checks it (sending any error back for the model to fix), and you see the program and a report of everything it can touch before it runs. Generated programs run under plan safety: only reads happen without asking you, and deletes are always blocked.
Lugh connects to any MCP server (GitHub, Slack, Drive, Notion and thousands more) with the same config format as Claude Desktop. Each tool's effect comes from its MCP annotations, and policy decides before the call is sent. See MCP and plan.
use mcp
policy
allow read
ask human before submit
deny delete
...
mcp.call "notes" "add_note" {title: "Biometrics"} # asks you first
mcp.call "notes" "delete_note" {title: "x"} # blocked by policy, never sentStandard library
Lugh Core ships with what most projects pull in from the Python and JavaScript ecosystems: strings and regex, collections, maths and statistics, dates, JSON and CSV, hashing and UUIDs, schema validation, templates, SQLite, a test runner, scheduled jobs and token auth. See the standard library reference.
let cheap = filter f in fares where f.price < 44000
let ranked = sort cheap by price
let errors = schema.check(request.body, {title: "text 2..80", amount: "number 0.01..1000000"})
db.exec "INSERT INTO expenses VALUES (?, ?, ?)" [uuid(), e.title, e.amount]
let report = csv.text(db.query "SELECT * FROM expenses")
test "only cheap fares"
expect count(cheap) == 3./core/target/release/lugh examples/stdlib_test.lugh --test # 13 passed, 0 failedexamples/ledger.lugh puts it together: an expense
tracker with a database, validation, token auth, an hourly job, CSV export and
a web UI, in about 50 lines.
Full-stack apps: routes, pages and a human in the loop
One .lugh file can be an API, a web UI and an approval workflow
(example, reference):
route POST "/api/book"
let b = request.body
ensure b.price < 45000 else respond 422 "Over budget"
ask human "Book {b.airline} at INR {b.price}?" -> ok # waits in the web inbox
when ok
respond 201 b
otherwise
respond 403 "Rejected"
page "/" title "Fare desk"
stat from "/api/best" field price label "Lowest fare (INR)"
table from "/api/fares" columns airline, depart, price
form to "/api/book" fields airline, price submit "Request booking"./core/target/release/lugh examples/fare_desk.lugh --serve 8080
# open http://127.0.0.1:8080 and the approvals inbox at /_lugh/inboxask human inside a route pauses that request until someone clicks Approve or
Reject in the inbox. Pages are server-rendered HTML (about 6 KB each, including
styles and script) with no build step.
Two runtimes
Python reference ( | Lugh Core ( | |
Use it for | Prototyping, the browser adapter | Production, scale, embedding |
Install | Python 3.9+ | One 5.9 MB binary (SQLite included), libc only |
Adapters | http, fs, shell, browser, llm | http, fs, shell, db, mcp, llm |
Web (routes, pages, inbox, auth, jobs) | — | Yes |
Standard library, | Core language only | Yes |
Both runtimes produce identical results on the bundled examples.
Benchmarks
Measured with python bench/gen.py && python bench/run.py (Linux x86-64, mean of
repeated runs; peak memory of the measured process alone):
Workload | Python | Lugh Core | Speed-up | Memory |
Startup ( | 79 ms, 22.3 MB | 2.9 ms, 4.8 MB | 27× | 4.6× less |
1,000,000 relational comparisons + attention over 3,000 emails ( | 1,925 ms, 26.2 MB | 321 ms, 14.9 MB | 6.0× | 1.8× less |
Numbers vary by machine. An agent's wall-clock time is usually dominated by network and model latency; Core's advantage is cheap startup, a small footprint and real parallelism when many agents run at once.
Effects and policy
Every action belongs to one of seven effect types. Policy is written against these, so reviewing an agent means understanding seven words rather than every API it calls.
Effect | Meaning | Default when not listed |
| Observes, changes nothing | ask human |
| Changes local or draft state | ask human |
| Commits an action in another system | ask human |
| Reaches another person | ask human |
| Moves money | ask human |
| Runs code or commands | ask human |
| Irreversible removal | ask human |
Anything not explicitly allowed requires approval, so a missing policy line makes an agent more cautious, never less. Policy denials and budget overruns cannot be caught by attempt, so an agent cannot route around its limits.
Adapters
Adapter | Reaches | Status |
| REST / JSON APIs | Working |
| Local files | Working |
| Installed CLI tools | Working |
| Any website (Playwright) | Working |
| Reasoning via | Working |
| SaaS apps via Model Context Protocol | Planned (v0.3) |
| Desktop software via OS accessibility APIs | Planned (v0.5) |
An adapter is one class: a map of verb → effect and a call(verb, args) method.
Documentation
From research to runtime: how 30 foundational papers map to Lugh
MCP and
lugh plan: connecting to MCP servers; letting a model write programs you approveStandard library: every module, mapped to its Python and JavaScript equivalents
Lugh Core: the native Rust runtime
Roadmap
Learn (v0.2) ✓ — research-derived primitives, adaptive routing, evaluation
Native (v0.3) ✓ — Lugh Core: Rust runtime, compile-once execution, benchmarks
Full stack (v0.4) ✓ — routes, pages, approvals inbox, end-to-end tests
Standard library (v0.5) ✓ — 100+ functions, SQLite, tests, jobs, auth, object literals
Connect (v0.6) ✓ — MCP client,
lugh planwith self-repair and plan safetyReach (v0.7) ✓ — browser playground (WebAssembly), VS Code extension, multi-line lists and objects, CI
Compile (v0.8) — bytecode VM, field access compiled to fixed slots
Ecosystem (v0.9) — package manager, language server, multi-agent message passing
Desktop (v0.10) — desktop app adapter, screen fallback, spend metering
Trust (v1.0) — TLS, user accounts and roles for served apps, signed audit logs, shareable policy packs, automatic fallback ladder
Platform — hosted runtime, adapter marketplace, team approvals
Support Lugh
Lugh is free and open source. If it's useful to you, you can support its development:
Network | Address |
Bitcoin |
|
Ethereum |
|
Please send each coin only on its own network.
Contributions of code, examples, adapters and bug reports are just as welcome.
License
MIT © 2026 Ashutosh Pandey
Available Tools
5 toolslugh_checkCheck a Lugh programARead-onlyIdempotent
Compile a Lugh program without running it. Reports syntax errors, unknown functions and adapters, and counts goals, tests, routes and pages.
Inputs: code (required).
lugh_referenceLugh language referenceARead-onlyIdempotent
Syntax and semantics of Lugh, a programming language for AI agents where permissions (policy), budgets and human approval are part of the code. Read this before writing a program.
Inputs: no named parameters.
lugh_runDry-run a Lugh program in the sandboxARead-onlyIdempotent
Run a Lugh program's goals in a sandbox. fs, http, mcp and shell act on a simulated world (see lugh_sandbox), but every call passes the real policy gate and budgets. Returns the output and a policy log of every action and its decision (allowed, approved, declined, denied). Use it to show a person exactly what an agent would do before it runs for real.
Inputs: code (required), approvals.
lugh_sandboxDescribe the sandboxARead-onlyIdempotent
List the simulated files, HTTP endpoints, MCP servers (with each tool's effect) and shell commands that programs run by lugh_run can use.
Inputs: no named parameters.
lugh_testRun a Lugh program's testsARead-onlyIdempotent
Run the test blocks of a Lugh program in the sandbox and report passes and failures.
Inputs: code (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool occupies a clearly distinct stage: reference (docs), check (compile only), run (execute goals in sandbox), test (execute test blocks), and sandbox (inspect the simulated world). The descriptions explicitly contrast check vs. run vs. test, so an agent can select without guessing.
All names share the consistent `lugh_` prefix with snake_case, giving a predictable namespace. Minor deviation: `reference` and `sandbox` are nouns while `check`, `run`, and `test` are verbs, so the verb_noun pattern isn't uniform.
Five tools map neatly onto the lifecycle of writing and validating a Lugh program: read docs, compile, run, test, inspect sandbox. Nothing feels padded or missing at this scope.
The surface covers the full authoring loop through simulated execution and policy logging, which is the stated purpose. Minor gaps: no lint/format or scaffolding tool, and no way to progress from sandbox to a real deployment, but agents can work around these via reference.
Maintenance
Related MCP Connectors
Pre-execution governance for AI agents. Deterministic PASS/FAIL/REVIEW verdicts, replayable proof.
Authorize AI agent tool calls before they run: policy-as-code, human approval, signed receipts.
Security gateway for AI agents: policy, approval, and audited execution, no secrets shared.
Supervised API-write gateway for AI agents with policy, human approval and execution receipts.
Related MCP Servers
- AlicenseAqualityCmaintenanceLocal zero-trust permission gateway for AI agents. Enforces policy-based tool authorization, human approvals, scoped permissions, and cryptographically verifiable audit logs.4128 PyPI5Apache 2.0
- AlicenseNot gradedqualityCmaintenanceLocal-first AI agent for approval-gated automation and verifiable LLM workflows.1MIT
- FlicenseNot gradedqualityCmaintenanceEnables controlled AI-agent access to enterprise-shaped tools with a deny-by-default gated write path, human approval, dry-run execution, and append-only audit logging.1-
- FlicenseNot gradedqualityCmaintenanceEnables AI coding agents to request bounded GitHub changes through a default-deny policy, independent human approval, one-time execution with a GitHub App credential, and verifiable receipts.1-