agents_Inc

A corporate org chart for AI agents: you ask, the session you talk to dispatches a Lead model, and the Lead runs cheaper Worker models. The aim is more checked work from the AI subscriptions you already pay for.

Table of Contents

1. Status & Roadmap
2. Why it exists
3. Installation
4. Quick start
5. How it works
6. Limitations
7. Documentation
8. Citation and license

1. Status & Roadmap

Version 0.4.1. The project is experimental and pre-MVP. The governed path (WORKERBEES_GOVERNANCE) is off by default. Changes per release are in the CHANGELOG. The build plan and cut line are in docs/PLAN-MVP.md. Open work is tracked in the issues.

• Now: measure the token cost of delegation against doing the work in one session.
• Next: let a Worker launched by a broker lead its own Workers (#73).
• Later: route work by data classification, so unpublished work reaches only approved providers (#19).

2. Why it exists

Delegated model work can look done while it is wrong. A flat pool of agents has no way to catch that. agents_Inc borrows a corporate org chart. The CEO is you. The CoS (chief of staff) is the session you talk to. A Lead manages one run, and a Worker reports to a Lead.

Cheap models take routine work, and costlier models manage. An author never grades its own work: the Lead checks what its Workers report before anything moves up. Savings are not yet measured, so none are claimed (docs/PLAN-MVP.md).

3. Installation

Requirements: Python 3.10 or later, Bash 3.2 or later, jq, curl, and the Claude Code CLI signed in to an Anthropic subscription. The Codex CLI is optional; when present, it serves the Codex rungs and cross-vendor review.

pip install agents-inc
agents-inc install     # skills ship in the package; no checkout needed
agents-inc doctor      # first line prints READY when the install works

Restart Claude Code (and Codex, if used) after the install. agents-inc install --without-codex skips Codex on purpose. To install from a git checkout instead, pass --source <checkout>. Optional Gemini, Mistral and OpenRouter keys, the setup decision tree and key storage rules are in docs/START-HERE.md.

Hooks this installs

agents-inc install adds these hooks to ~/.claude/settings.json. It prints the list when it runs.

• SessionStart: loads the delegation mandate into each session.
• PreToolUse on Agent/Task, dispatch-shaped Bash and DelegateAgent: adds a routing nudge, warns on duplicate dispatches, blocks persona impersonation, and runs the agent gate.
• PostToolUse on Agent/Task: marks the dispatch done.
• UserPromptSubmit: routes @alias side questions.

Agent gate. Claude's Agent tool skips agents-inc routing, prompt lint, the ledger and verification. The gate decides what happens to those calls.

• Switch mode: agents-inc repair --agent-gate enforce|advisory|off. The choice lives in ~/.config/agents-inc/settings.json.
• One session only: launch with AGENTS_INC_AGENT_GATE=off claude (or enforce).
• Check: agents-inc doctor prints agent gate: <mode> (<source>).
• Remove every agents-inc hook: agents-inc unwire. Other hooks stay. agents-inc repair adds them back.

Using agents-inc without the gate.

• Use Agent only for read-only, foreground scouts.
• Send anything that writes files, runs long, nests or belongs in the ledger through agents-inc dispatch.
• Naming a model chooses the rung, not the route. "Use sonnet" still means agents-inc dispatch --model sonnet.
• Subagents get no SessionStart mandate. If an Agent prompt may delegate, say in it: sub-delegate only via agents-inc dispatch.
• Verify what an Agent call returns yourself, as for any delegate.

4. Quick start

Name your models in plain English. The ladder decides who manages whom, and the rest fills in. You do not hand-pick every model or write JSON.

Write the request to the CoS as <task>. <models>., for example:

"Fix the parser. opus, haiku."

The higher rung manages and the lower rung reports to it, so opus is the Lead and haiku is its Worker. Defaults fill the rest: effort medium, gates derived from the task, and the home repo from the consumer's AGENTS.md. Each extra word, such as an effort level, overrides one default.

The CoS then runs one command. It renders the prompt, lints it, snapshots the tree, launches the delegate and checks the report:

agents-inc dispatch --slots slots.json --model sonnet --dry-run   # drop --dry-run to launch
agents-inc models chain supervisor=opus                            # change the default REPORTING CHAIN

Every dispatch prompt carries a REPORTING CHAIN line derived from the ladder, and every launched dispatch writes one dispatched row to the ledger. Codex delegates can write to --cwd by default, the same as a Claude subagent; the slot CODEX_WRITE: no makes one read-only. A worked slots file is in skills/workerbee/slots.md.

Two more entry points need no dispatch. PYTHONPATH=. python3 tools/governance_demo.py --fake, run from a checkout, shows routing, policy checks and ledger records with no provider keys. @haiku <question> inside any Claude Code session sends one side question to a cheaper model before the session model runs (docs/at-route/AT-ROUTE.md).

5. How it works

• Routing. A router picks the vendor and rung for each task from a written policy (agents_inc/routing.json). Rung names are cost classes, not job titles; the reporting chain sets the role.
• Grilling and speckit. The CoS grills you one question at a time until the request is sharp, then a speckit pipeline gates it through spec, plan, tasks and review.
• Verification. A deterministic verifier checks cited claims with no model call. A reviewer from a different vendor then checks the meaning. A Worker's own PASS never decides acceptance.
• Ledger. An append-only JSONL and SQLite ledger records every dispatch, return, review and acceptance decision.
• Models. Each Codex alias is pinned to one slug. agents-inc models reports drift. Model sync promotes new Codex slugs in approve or auto mode and skips pinned aliases.

The full description, including the delegation limits, the 14-element prompt contract, the verification flow and the comparison with other tools, is in docs/HOW-IT-WORKS.md.

6. Limitations

• Cost savings and accuracy against a baseline are not measured. Passing local tests show that the code behaves as written, not that it is reliable in production.
• The governed path is off by default, so a fresh install does not run the enforced cross-vendor review.
• Cross-vendor review catches disagreement between models. It does not catch a blind spot that both vendors share.
• Deterministic checks cover what a script can express, such as a file, a quote or an exit code. They do not replace human judgment on scope or design.
• Free-model capacity varies: a probe on 2026-09-29 found 429 or capacity errors on several free models (docs/BENCH.md). Artifacts stay local; remote publication (Bindle Backend B) is not built.

Updates: new sessions and agents-inc doctor tell you when a newer release is on PyPI (one check a day; AGENTS_INC_NO_UPDATE_CHECK=1 turns it off).

Found a bug or want a feature? agents-inc report bug --title "..." --body "..." (or report feature) prints a draft issue with your version, doctor result and OS; home paths become ~. Add --submit to file it on GitHub with your own gh login.

7. Documentation

8. Citation and license

The DOI for all versions is 10.5281/zenodo.22670100. GitHub's "Cite this repository" button reads CITATION.cff.

agents_Inc is licensed under the PolyForm Small Business License 1.0.0, with one added term that forbids use for AI or machine-learning training. The full terms are in LICENSE.