Control infrastructure for autonomous AI agents: deciding when to act, when to ask, and when to stop.
Buddhi is the discriminative layer for autonomous agents: it decides when to act, how much effort a task deserves, when to stop, and when a human should decide.
Buddhi sits above the runtime that calls models and runs tools. It is a small, runtime-neutral kernel that allocates a bounded cognitive budget of model effort and human interruptions across a stream of work.
It neither executes nor schedules the work. It decides how much attention each item deserves, and whether the model or a person should make the judgment.
Status: alpha, under active development. Both projects are under active development and their interfaces may change. The kernel README states plainly that the API may change before 1.0; buddhi-review gives no semantic-versioning guarantees before v1.0 and has been exercised end to end but not hardened across a wide range of repositories.
Why it exists
Agent frameworks are good at making agents run. They are less good at deciding whether an agent should run at all, how much to spend on it, and when a human needs to be pulled in. BuddhiKernel is the layer that makes those decisions explicit, bounded and auditable.
Left unmanaged, a supervisor over a stream of agent work fails in three common ways.
Over-acting
Acting autonomously when human judgment was required, or spending effort on an item that should have been discarded.
Over-asking
Interrupting a human where the system could have decided for itself.
Over-iterating
Continuing after further work has stopped producing value.
Buddhi holds all three in check within one budgeting framework. It treats cognition, machine effort and human attention alike, as the scarce resource, and decides per item where that resource is spent or withheld. The design follows Herbert Simon's bounded rationality: cognition is scarce, so an agent must allocate it according to marginal value rather than attempt exhaustive optimization.
How it works
One controller, evaluate_item() in buddhi/closure.py, runs over each item and works through seven decisions in a fixed order, stopping at the first one that settles the item: whether the item deserves any attention; how much model effort it may use; whether further work has stopped adding value; whether the model can decide or human judgment is required; whether the proposed escalation is specific and answerable; whether the item was already resolved out of band; and whether the escalation clears the current admission bar, which rises as interruptions accumulate.
The first decision that terminates returns one of seven dispositions: DISCARDED, CONVERGED, MODEL_HANDLED, INVALID_ASK, RESOLVED_OOB, ESCALATED, DENIED.
The same controller is reused one level up. At the item level it decides how much attention one item receives; at the parent level it treats a child stream as an item and decides how much budget that whole stream receives. The project calls this composition the closure operator, and it is the centre of the design. Budget allocation recurses; task coordination does not.
The kernel is orchestration and depends on five seams, and it ships no production implementation of any of them: PolicyPack (one runtime-neutral policy source), Router (recommend(item)), Store (scope-keyed interrupt counters and a two-tier source-exclusion lattice), EscalationTransport (deliver(ask)), and OOBSource (can_observe_oob()). Domain adapters provide the real implementations; the repository ships only a reference pack with minimal behaviour, not production policy. Stage 0 (condition()) is a one-time pre-pass that turns raw input into typed items, and the kernel ships a 1:1 identity pass-through.
An adapter connects the kernel to a concrete runtime or domain through four operations in buddhi.adapter: ingest(), run_embedded(item, budget), escalate_async(ask) and detect_resolved(item). It supplies the substrate's I/O and lets the kernel make every decision.
The controller flow. Four variants of this diagram are served: a wide layout on desktop, a tall one on phones, each in a light and a dark version.
Apache-2.0 · Python ≥ 3.10 · no runtime dependencies · PyPI: buddhikernel 0.1.0 (2 June 2026); current source release 0.1.1
A composable supervisor kernel that rations cognition across agentic work.
For each unit of work it decides whether the item is worth acting on, how much model effort to spend, whether the stream has converged, whether to route to a model or to human judgment, and whether the spend fits inside a bounded hierarchical budget. The kernel defines the interfaces it depends on and deliberately implements none of them, so policy, routing, storage and escalation stay yours.
The published package runs the demo directly, with no clone needed. A successful run prints SMOKE PATH OK and exits 0.
MIT · Python ≥ 3.10 in practice (its own metadata says ≥ 3.9, but the buddhikernel dependency requires ≥ 3.10) · depends on buddhikernel and PyYAML · PyPI: buddhi-review 0.8.0, published 30 July 2026
A working application of the kernel: multi-vendor pull-request review.
It fans a PR out to reviewers from different labs, classifies each finding, applies fixes, and re-reviews until a round comes back clean or the round budget runs out. It maps each review finding into a kernel work item; the kernel returns a disposition, and the adapter translates that result into the matching review action: fix, ask, skip, or defer.
The package ships two Claude Code skills, /review-pr and /open-pr, which are included but not registered automatically:
pip install buddhi-review
buddhi-review install-skills
# restart Claude Code, then run:
# /review-pr setup
A health check that needs no network and no claude CLI runs the kernel-driven pipeline on built-in fixtures:
The kernel holds all judgment logic. Adapters hold I/O and nothing else. buddhi-review is the reference adapter and it is deliberately thin: it talks to GitHub, and the kernel decides what to do. PR review is one adapter of the kernel, not the definition of Buddhi; the same interface is intended for other streams of agent work, such as an issue tracker's comments, a task queue, or an agent's inbox.
The licensing follows the same split. The kernel is Apache-2.0 so it can be embedded and extended freely; the adapter is MIT.
What is demonstrated, what is asserted, what is out of scope
The repository keeps an explicit maturity ladder rather than a claim of general validity. It is reproduced here in summary; the full version is in claim and bound.
Demonstrated and runnable today
The closure reuse, meaning the supervisor runs the identical controller once per child; the seven named invariants of effort ceiling, monotone admission bar, a parent ceiling bounds total subtree spend (the bound is bar-gated: a high-stakes or at-cap ask still bypasses it), termination, exclusion dominance, Stage 0 fidelity and convergence safety; and the reduction of the hierarchical budget to a single shared pool. Each is exercised by named tests, including test_budget_reduction.py::TestReductionToSharedPool::test_generalized_matches_oracle_step_for_step for the reduction theorem and test_closure.py::test_closure_literally_reuses_evaluate_item_once_per_child for the closure property. The reference pack and the demo run end to end. In the repository's own words: “In total, 300 example-based and parametrized tests back these claims (no property-based fuzzing).”
Asserted, not yet established
Buddhi Review is one concrete external adapter, but the kernel repository's own validation is still centred on the reference pack. Generality across substantially different substrates remains a design claim, not an established result.
Out of scope
Coordination of coupled items is a boundary, not a gap to be patched. Drawing that line is what keeps the kernel a control mechanism rather than a scheduler.
Named limits
L1 · Items must be independently evaluable
The controller decides one item at a time, so coupled items, where acting on one changes whether the other is worth acting on, are out of scope.
L2 · Order-dependence within a scope
The admission bar is graduated and evaluation is sequential, so the same items presented in a different order can escalate a different subset.
L3 · Cross-level budget conservation is opt-in, not automatic
Conservation holds whenever the closure partitions children. The reference pack does not partition; it runs the degenerate single-pool case.
“[A] single composable controller that runs unchanged on one item and on a stream-viewed-as-an-item, rationing a hierarchical cognitive budget through a graduated admission bar, with judgment routing to a human as a first-class disposition.” — positioning
Documentation
The documentation is rendered from the kernel repository and is not duplicated here.
Start here
Concept — the core idea: one controller, and how the operator and the budget compose.
Architecture — the nested diagram and a component-by-component walkthrough.
Go deeper
Closure — the runnable closure centrepiece (python -m buddhi).
Decisions — the rationale for the seven decisions and five seams.
Budget — the cognitive budget, the reduction theorem, and the invariants.
Reference
Glossary — terms, including the Simon-lineage disambiguation.
Claim and bound — the maturity ladder: demonstrated, asserted, out of scope.
Limits — where it breaks: coupling, order, conservation.
Buddhi is a runtime-agnostic policy kernel that decides, per item, whether something is worth acting on and how much effort to spend under a bounded cognitive budget, and when to defer to a human. The same controller composes: the supervisor of a stream of streams is the identical operator applied one level up.
@software{srivastava_buddhi_2026,
author = {Srivastava, Manasvi},
title = {{Buddhi}: a composable controller for allocating a
bounded cognitive budget},
year = {2026},
month = jun,
publisher = {Zenodo},
version = {v0.1.0},
doi = {10.5281/zenodo.20509989},
url = {https://doi.org/10.5281/zenodo.20509989},
note = {Apache-2.0. Repository:
https://github.com/buddhikernel/buddhi}
}
The archived Zenodo deposit is v0.1.0, which is what the entry above records; the current source release is 0.1.1, and that is the version carried in CITATION.cff. To pin the exact archived deposit instead of the all-versions concept record, swap doi and url to 10.5281/zenodo.20509990. The entry uses the @software type, which requires biblatex; under classic BibTeX styles such as plain.bst, change it to @misc.
The name
In the Samkhya and Vedanta traditions of faculty psychology, the mind is analyzed into distinct faculties. Manas is the faculty of deliberation: it coordinates what the senses report and proposes alternatives. Buddhi is the discriminating faculty whose defining act is determination or ascertainment. The Katha Upanishad fixes their relation in one image: the self rides in the chariot of the body, drawn by the horses of the senses, with buddhi as the charioteer and manas as the reins. The reins channel the horses; the charioteer chooses the road. Manas proposes; buddhi decides.
A generative model is manas-like: it generates candidate interpretations and actions. Buddhi supplies the determinative layer, deciding what merits action, how much further effort to allocate, when the matter is settled, and when human judgment is required. Read more in the concept document.
Author
I am Manasvi Srivastava. I designed and built both projects on this page, and I maintain them.
If you want to argue with the design, or you think you have found a hole in it, I would like to hear from you — hello@buddhikernel.com. Issues and pull requests are welcome on either repository, and I read all of them.
BuddhiKernel
