Nudge

Nudge

Don't parse your agents. Nudge them. A typed, replayable, budget-aware programming language for LLM agents — compiles to Python & TypeScript.

---

Why Nudge exists

Production agents in 2026 are still held together with Python glue: prompt chains parsed by hand, tool calls wrapped in try/except, no replay, no cost control, no regression tests. Libraries patch symptoms. Nudge fixes the layer where the problem actually lives: the language.

Nudge is an open-source AI agent programming language with deterministic replay (every run emits a trace; every trace replays as a test at zero token cost), LLM cost control (compile-time budgets and a static cost report), typed tool use over MCP (Model Context Protocol), A2A agent-card export, an LSP language server for editor diagnostics, and OpenTelemetry span export — one .ndg file in, production-grade agent infrastructure out.

| Pain | Libraries | Nudge | |---|---|---| | Untyped LLM output | validate at runtime | schema is a type — proven at compile time | | Hidden side effects | invisible | uses LLM, Tool, IO in every signature | | No regression testing | record/replay bolted on | every run emits a trace; every trace is a test | | Cost surprises | dashboards after the fact | budget is a contract, enforced by compiler + runtime | | Async fan-out spaghetti | manual asyncio | par map / race / all, race safety proven |

A taste

type Finding = { claim: string, source: Url, confidence: float @range(0, 1) }

fn analyze(q: string, hits: [SearchResult]) -> [Finding] uses LLM {
    llm"""Extract verifiable findings about {q} from: {hits}"""
    with { schema: [Finding], model: "anthropic:sonnet-4.6",
           budget: 0.03 USD, retry: 2 with repair }
}

test "stays within budget on recorded trace" {
    let t = replay("traces/demo.jsonl")
    assert t.cost_usd ` continues a crashed run from its last checkpoint (design §7). **v0.3a reducer state landed:** `l | merge r` joins dicts (union) and lists (append-dedup) for CRDT-style state writes (design §7). **v0.3b–d landed:** multi-server MCP routing via the `NUDGE_MCP_SERVERS` registry (design §8), a TypeScript backend (`nudgec build-ts` + `runtime/nudge_runtime.ts`), and OTel span export (`NUDGE_OTEL`). **v0.4 landed:** `nudgec cost` reports llm call sites statically at flat fake pricing (design §13), and `route{ cheap: "m1" when cond, strong: "m2" otherwise }` picks a model per call, recording the chosen label in the trace (design §4.4). **v1.0 landed:** the v1 trace schema is frozen with a `nudgec trace-check` validator (design §6), `nudgec a2a` exports A2A agent cards (design §9), and `nudgec lsp` serves the Language Server Protocol over stdio for editor diagnostics (design §10).

## The name

*Nudge* — a small, intentional push. That is what a well-typed prompt really is: you don't command an LLM and parse whatever comes back, you nudge it into a schema and let the language enforce the rest. Files use the `.ndg` extension.

Documentation is in English; Simplified Chinese docs are planned after v0.1.

## Documentation

- [Language design](docs/design.md) — types, effects, replay, budgets, compiler architecture
- [Roadmap](docs/roadmap.md) — MVP plan and v0.1→v1.0 milestones
- [Examples](examples/) — the self-testing research agent

## License

MIT — see [LICENSE](LICENSE).

## Source & license

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

- **Author:** [NekomyaDev](https://github.com/NekomyaDev)
- **Source:** [NekomyaDev/nudge](https://github.com/NekomyaDev/nudge)
- **License:** MIT

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