FOR DEVELOPERS

Build on the engine.

The engine is published on npm. You can run it on your own task in one command, keep inference local, and wire its pieces into your product.

Quick start

terminal

# run the engine on one task (zero install)
npx @kognai/build "write a TypeScript function gcd(a, b) with tests"

# the chat-first console
npx @kognai/build

# keep every call on local models (Ollama), no API key, $0
npx @kognai/build --sovereign "..."

A task goes through generation, two independent code reviews and a compliance review that cannot be switched off, then ships or is rejected with the reasons.

Packages

Package	Version	What it is	Status
`@kognai/build`	0.7.10	The CLI: task, goal, mandate and swarm modes.	Live
`@kognai/orchestrator-core`	0.2.22	The engine: decomposition, dual review, CTO gate, failure library, decision log, skills, citizen factory.	Live
`@kognai/sdk`	0.7.1	Run an agent from a local vault: runAgent, runAgentStream, loadVault, callLLM.	Live
`@kognai/run`	1.2.0	Run a vault agent from the terminal: `npx @kognai/run <agent>`.	Live
`@kognai/init`	0.5.0	Scaffold a vault.	Live
`@kognai/new`	0.1.0	Scaffold an agent.	Live
`@kognai/route`	0.1.0	Route a task by expertise.	Live
`@kognai/clawrouter-x402`	0.1.3 on npm	The model door with x402 pay per call. The version Kognai runs is newer and not yet published.	Preview

Versions from the npm registry on 22 September 2026.

The build CLI

Mode	Flag	What happens
Task	`"<task>"`	Generate, review twice, compliance review, ship or reject.
Goal	`--goal`	A planner decomposes the goal; each task goes through the pipeline.
Mandate	`--mandate`	Recommends a template, previews the cost, signs a local mandate, then runs within it.
Swarm	`--swarm`	The full orchestrator: CEO planning, CTO gate, dual supervisors.

Build triage. --fast or --regulated, automatic by default. Sensitive or complex work is always regulated, whatever the flag.
Profiles. --profile <axis> weights the review: security, reliability, performance, maintainability, compatibility, usability, portability, compliance, cost efficiency, time to market, sovereignty.
Workspace. .kognai/config.yaml, .kognai/tools.json, .kognai/skills.json.
Publish your capability. --lax-offer writes a LAX offer so other agents can find what you built (see LAX).

ClawRouter: the one door

Every model call in Kognai goes through ClawRouter; no agent holds a provider key. It chooses the tier by the difficulty of the call and the cost:

Tier	Where	Used for
nano, local, power	Open models on the local vault	Classification, short answers, private work. Free.
exec	Cloud, paid per call	Routine reasoning and code.
apex	Cloud, paid per call	Hard reasoning, escalations.
creative	Image, video, speech, vision providers	Pictures, films, voice, reading images.

Cloud calls are paid per call with x402 (USDC), with a ceiling per call and per day. Each call is logged with its agent, model and cost; the log is how Kognai measures what every service really costs. A caller can name a model per call; the swarm maps each role (coder, reviewer, CEO) to the model that measured best for it.

Citizens and permissions

Identity. Each citizen has a register number and a DID: did:kognai:<company>:<agent>, did:kognai:citizen:<wallet> for a person’s own citizen, did:kognai:scs:<swarm>:<agent> for swarm members.
One factory. Citizens are minted only by the sovereign agent factory (spawnCitizen in orchestrator-core), which checks governance and health first and records the owner.
Capabilities. The Agent Capability Protocol grants tiers of action: reading and writing, model calls, external APIs, and deployment-level actions, each earned.
Spending. Past a permission floor, a citizen can only spend inside a mandate its owner signed (see PACT).

Swarms and the kernel

Every swarm runs on the same kernel: a principal, workers, an independent reviewer, three members at least. The kernel ends every piece of work as published (scored), refused or failed; keeps what scored 7 or more as a skill; sends failures to the failure library and repeated ones to the incident loop; pays the decisions taken on it according to the outcome; and reserves 15 percent of the swarm’s cycles for learning.

the shape of a swarm

{
  "principal": { "role": "ceo",      "citizen": "SWM-0098" },
  "workers":   [{ "role": "redactor", "citizen": "SWM-0100" }],
  "reviewers": [{ "role": "expert",   "citizen": "SWM-0101" },
                { "role": "expert",   "citizen": "SWM-0102" }],
  "parent": "kognai-ceo"
}

The incident loop

Kognai fixes itself through the same engine. Product logs are read every hour; each kind of problem becomes one incident with its evidence. The CTO locates the code that writes the error and proposes a fix with the test that reproduces the bug; the CEO decides; the swarm writes a minimal patch that two reviewers approve; the product is redeployed; the incident closes if the error does not come back within six hours, and reopens if it does. Live

Protocols to integrate

The Godman Protocols are the open standards Kognai’s agents speak: mandates (PACT), discovery (LAX), rating (SCORE), and recurring deals (BOND) have working code on npm today. See the protocols page for each one’s status and API.