╭─────────────────────────────────╮
                         │  ╔╗ ╔═╗╦═╗╔═╗ ╔═╗╔═╗╔═╗╔╗╔╔╦╗   │
                         │  ╠╩╗╠═╣╠╦╝╠╣  ╠═╣║ ╦╠╣ ║║║ ║    │
                         │  ╚═╝╩ ╩╩╚═╚═╝ ╩ ╩╚═╝╚═╝╝╚╝ ╩    │
                         │   think ──→ act ──→ observe     │
                         │     ↑                  │        │
                         │     └──────────────────┘        │
                         ╰──╮──────────────────────────────╯
                            ╰── the brain, without the bloat

Lightweight agent primitives. Zero required deps — optional bareguard peer for one-gate governance.

bare-agent started as primitives for building agents by hand: your code is the deterministic body, an LLM call sits in wherever you need judgment — the LangChain / CrewAI / AutoGen job, provider-agnostic, without a framework.

LLMs got good at wiring things themselves, so the same primitives are now offered as tool calls too: the model wires them up, bare-agent runs the loop, retries, budgets, and governance underneath. It's what bareloop and fwdloop run on.

Some things an LLM can't judge about its own work. Building a harness or an external arbiter? Every primitive is listed in primitives.json — when to use it, import, signature, failure modes, a runnable example — plus a decisive return-time judge and the Jev gut-check tier.

Start here

• Building by hand → npm install bare-agent, then hand your assistant bareagent.context.md (ships in the package — the complete contract).
• AI agent / tool-calling → read primitives.json first (unpkg.com/bare-agent/primitives.json before you install, or require('bare-agent/primitives.json')); generated from source, never drifts.
• Harness / judge builder → primitives.json + judge + Jev + wire bareguard.

Fast gut check — Jev

An LLM call is slow, deliberate thinking (System 2). Jev, from TypeSafe, is the fast gut check (System 1): a classifier that returns a typed decision with a calibrated probability — far faster and cheaper than an LLM call. bare-agent's JevProvider covers all three shapes — yes/no, pick-one, score — so your automation calls it like any other step: act when it's confident, escalate when it isn't. Injection-hardened by default; also usable as the jev check in the Evaluator.

Break big tasks down — RLM

recurse brings Recursive Language Models (RLM) to your code in one call: split a hard task into smaller ones, run each in a fresh context window, check the result, and stitch it back together. The model decides when to split (or you force a fixed count), and over a large set of documents it picks the path by question shape — scan everything for "how many", search for a needle. Totals are counted by code, and a dead worker comes back incomplete, never a faked pass. Cost is open by design: run it under a budget cap (bareguard) or set maxDepth: 1.

What's inside

Every piece works alone — take what you need, ignore the rest. No required deps — the core imports nothing.

| Area | Component | What it does | |---|---|---| | Act | Loop | think → act → observe until done, any provider, opt-in policy/assemble/trim seams | | Act | Planner + runPlan | break a goal into a step DAG, run steps in parallel waves | | Act | assessComplexity | rate a goal from its text alone, no LLM — gates whether to plan | | Act | recurse | RLM in one call — decompose → fan-out → verify → synthesize (see above) | | Act | Memory | persist and recall across sessions — JSON, SQLite, or litectx in a one-line swap | | Act | StateMachine | task lifecycle: pending → running → done / failed / waiting / cancelled | | Act | Scheduler | cron or relative triggers, survives restarts | | Act | Checkpoint | human approval gate, bring your own transport | | Act | Spawn | fork a child agent, sharing one audit log and budget | | Act | Defer | queue an action for a waker to fire later, governed on emit and on fire | | Act | Retry · CircuitBreaker · Fallback | backoff with jitter, fail-fast, provider failover | | Act | Stream · Errors | structured JSONL events, typed error hierarchy | | Verify | Evaluator + refine | judge output by predicate, rubric, an agentic critic, or the Jev tier; refine loops generate → evaluate → regenerate | | Verify | judge | a decisive return-time check of the result against the original request | | Verify | remember | distill durable facts out of a finished run | | Verify | SkillRegistry | surface extra tools on demand instead of loading them all upfront | | Verify | stash | compact finished work out of the live context window, restorable | | Verify | JevProvider | fast, cheap, calibrated yes/no · pick-one · score decisions — the System-1 gate (see above) | | Govern | wireGate → bareguard | one policy, one audit log, one budget cap over every call; stops the spin on repeated denials or a stuck call | | Hands | Browsing · Mobile · Shell · MCP Bridge | barebrowse, baremobile, cross-platform shell, and auto-discovered MCP servers — all as tools | | Providers | OpenAI-compatible, Anthropic, Gemini, Ollama, CLIPipe, Fallback | swap freely, or bring your own with one generate method; CLIPipe runs the loop over a CLI subscription instead of the metered API |

It tells you the truth

• A cut-off, refused, or over-context answer is an error, not a success — and its half-written tool calls never run.
• A cost it can't price is null, never a silent $0.
• A dead worker or broken check returns incomplete, never a faked pass — and counts are done by code, not by the model.
• Stuck loops stop: repeated denials or the same failing call end the run cleanly instead of burning the budget.

The bare ecosystem

Local-first, composable agent infrastructure. Same API patterns throughout — mix and match, each module works standalone.

Core — the brain, the gate, the memory.

• bareagent — the think→act→observe loop. Goal in → coordinated actions out. Replaces LangChain, CrewAI, AutoGen.
• bareguard — the single gate every action passes through. Action in → allow / deny / ask-a-human out. Replaces hand-rolled allowlists and scattered policy code.
• litectx — tree-sitter code + memory graph with activation decay, plus lightweight context engineering (write · select · compress · isolate). Query in → ranked context out.

Optional reach — give the agent hands.

• barebrowse — a real browser for agents. URL in → pruned snapshot out. Replaces Playwright, Selenium, Puppeteer.
• baremobile — Android + iOS device control. Screen in → pruned snapshot out. Replaces Appium, Espresso, XCUITest.
• beeperbox — 50+ messaging networks via one MCP server (headless Beeper Desktop in Docker). Chat in → unified message stream out. Replaces Twilio, per-platform bot APIs.

What you can build:

• Headless automation — scrape sites, fill forms, extract data, monitor pages on a schedule
• QA & testing — automated test suites for web and Android apps without heavyweight frameworks
• Personal AI assistants — chatbots that browse the web or control your phone on your behalf
• Remote device control — manage Android devices over WiFi, including on-device via Termux
• Agentic workflows — multi-step tasks where an AI plans, browses, and acts across web and mobile

Why this exists: Most automation stacks ship 200MB of opinions before you write a line of code. These don't. Install, import, go.

Docs

• Integration Guide (bareagent.context.md) — the complete contract: every option, the full API, wiring recipes. Ships in the package.
• Primitives manifest (primitives.json) — every primitive as machine-readable JSON. Ships in the package, generated from source.
• Error Guide — what each error means and how to react to it.
• CHANGELOG — release history. Not on Node? See contrib/ for wrappers in Python, Go, Rust, Ruby, and Java.

License

Apache License, Version 2.0 — see LICENSE and NOTICE.