- Page index — every active doc and the question it owns.
An agentic operating system that runs as an organization. Persistent AI employees work in departments under heads, led by a CEO, governed by a charter and supervised by you, the Chair. Every piece of work leaves the organization smarter: lessons accumulate in employees, recur across colleagues, and are promoted into department and company knowledge that every later brief carries. Authority to approve is earned from verified results and lost on failures.
Most agent systems hire anonymous contractors that do a job and vanish; nothing adds up. Holon employees keep an identity, roles, a manager, a memory and a record, so the organization compounds: departments get measurably better at their jobs, and the feedback loops between employees, departments and the company keep evolving how the work itself is done (docs/INTENT.md).
- Persistent employees, portable bodies. Identity and memory belong to the organization, so an employee can change harness and keep its career.
- Checked, not trusted. Every CLI call is authenticated, every result is judged against a rubric, every machine-checkable claim is actually checked, and the audit trail is hash-chained.
- Harness-agnostic. The kernel names no harness (
holon lintenforces it); bodies plug in through adapters. - Zero dependencies. Python ≥ 3.11 standard library and SQLite ≥ 3.35.
- Self-healing. Leases, retries and incidents: a stage that keeps failing opens work for the
IT department;
holon doctorchecks live state on every heartbeat.
Requirements: Linux with Python ≥ 3.11 and SQLite ≥ 3.35. Nothing else.
One line (bootstraps the checkout, then hands off to install.py):
curl -fsSL https://raw.githubusercontent.com/ishan-parihar/holon/main/install.sh | bashor from a checkout:
git clone https://github.com/ishan-parihar/holon && cd holon
python3 install.py # instance at ~/holon (SQLite + Chair key, 0600), `holon` on PATHinstall.py checks the dependencies, creates or migrates the instance, puts a holon launcher
in --bin-dir (default ~/bin), and ends with holon doctor and an onboarding runbook: which
adapter to install, whom to hire, how to run and approve your first task. --systemd --heartbeat installs the 2-minute holon tick timer; --notion-* wires the Notion dashboard
(see below). A pip install also works: pip install . then HOLON_HOME=~/holon holon init.
Give the employees a body — any OpenAI-compatible model endpoint — then hire. With the jcode adapter (any of the four below works the same way):
python3 adapters/jcode/install.py --holon-home ~/holon \
--base-url http://localhost:8000/v1 --model <model> --api-key-file ~/.config/holon/model.key
holon adapter test jcode # conformance: a few real runs in a scratch organization
export HOLON_HOME=~/holon
holon hr hire --dept executive --slot ceo --name Ada --title CEO \
--driver jcode --jd @jd/ceo.md --reason "founding CEO" --status active
holon dept create it --name "IT" --mission "Keep hosts, tools and credentials healthy" --profile light
holon hr hire --dept it --slot lead --name Bo --title "Head of IT" \
--driver jcode --jd @jd/head-of-it.md --reason "founding head"
holon task add "Free disk space on the file server" --intent "Get / under 75% used" --dept it
holon schedule add --kind wake --cron "*/10 * * * *" --as <employee-id>
holon tickWork then flows through the pipeline, and you steer it:
holon status # what needs you
holon plan approve <id> --note "…" # or: holon plan reject <id> --note "what to change"
holon task tree <id> # the holarchy under a piece of work
holon metrics --dept it # the feedback loops' sensors
holon lint && holon doctor # integrity: artifacts and live state
holon help # every command, and who may run itwork ─► research? ─► shape? ─► plan ─► approve ─► execute ─► verify ─► done
(bylaws rules decide) (graded G0–G4, routed to the lowest approver whose
earned authority covers it: head → CEO → Chair)
A plan may split work into child work in any department; rework appends execute#2 / plan#2;
failures and repeated rejections queue a retro whose actions become new work.
| Adapter | Harness | Notes |
|---|---|---|
adapters/zeroclaw |
ZeroClaw | sandboxed agent aliases per scope; Holon as native MCP tools |
adapters/hermes |
Hermes | one-shot sessions; see its README for read-only limits |
adapters/jcode |
jcode | about 3 MB per headless session |
adapters/operant |
Operant | Rust harness; the organization runtime (its docs/agentic-os/ has the integration plan) |
adapters/claude-code |
Claude Code | driver only; not yet through conformance |
adapters/deepseek-harness |
DeepSeek Harness | native bundle (brief, skills, typed submit, policy guard) over an isolated headless profile; an operator Command Center UI (dashboard/) for the Chair |
Anything else: copy holon/execution/drivers/generic-shell.toml into your instance's
config/drivers/ and point it at whatever runs one agent turn — or use pull mode: any agent
runtime claims work with holon claim and hands in results with holon submit or the MCP
server (holon mcp, run-token authenticated). The full contract for harness authors is
docs/CONTRACT.md.
- Lanes. Work runs cheapest-first: a script the kernel runs, one fast session for operation work, the full pipeline when it is needed. Each operation has a rubric, and its last verified run is its gold standard, shown to the next executor and its judge.
- Learning loops. Every stage's learnings consolidate into employee memory; failures and metrics open department retros whose actions become work; playbooks (a job's protocol and rubric as a versioned skill) refine themselves from evidence after verified runs.
- Security. Agents run as their own OS user and reach the organization only through a broker; run tokens authenticate every call; the Chair key never reaches a harness; observe stages are read-only, enforced by driver posture and fingerprinted workdirs.
- Notion mirror (optional).
adapters/notionmirrors departments, employees, work and runs live, and takes your decisions, notes, answers and new work back (adapters/notion/README.md).
State lives in the instance, never in this repo:
$HOLON_HOME/
holon.toml configuration (docs/BYLAWS.md §6)
skills/[@<dept>/]<skill>/ skills tailored for the organization or one department
bylaws/<profile>.toml instance bylaws profiles
config/drivers/*.toml harness drivers (adapters install them)
execution/runtime/work.db organization, work graph, runs, outputs, messages, audit trail
execution/runtime/runs/<run>/ BRIEF.md, brief.json, identity.md, context.md, result.json, driver.log
capabilities/memory/memory.db institutional memory
capabilities/strategy/trajectory.db goals tree (read-only to the kernel)
capabilities/logbook/logbook.db the Chair's logbook (read-only to the kernel)
Docs: INTENT · BYLAWS (departments, roles, every config key) · CONTRACT (for harness authors) · ARCHITECTURE (how the kernel, the instance and the agents fit together) · COMMANDS (every command, generated from the registry) · the skills library · adapter READMEs, which record what each real harness does · STATUS (the live index: where Holon sits, standing decisions, what is next) · the design corpus (dated records and how to read them) · the register (what is open, one row per item, with its owner and its evidence) · the archived gaps outline (archived 2026-11-05; its rows are closed or carried by the register).
See CONTRIBUTING.md. The gates: python3 -m unittest discover -s tests -t .
and python3 -m holon --home "$(mktemp -d)" lint --strict (Python 3.11 and 3.13 in CI). A
defect found by a real run gets a guard test and a regression-ledger row in the same commit; this
repository stays free of instance and operator specifics (AGENTS.md).
MIT © 2026 Ishan Parihar