MIT · the developer codex
◆ You are in The Codex — What went wrong?

Code that tells you when it is wrong

An agent will finish a task, report success, and be completely wrong - not because it lied, but because nothing in its loop could ever have found out. Every law here is one way a system was made able to find out. All twenty-three were a real failure first.

Get started View source
bash
# read it online, or take it with you
git clone https://github.com/Aitherium/awknowledge.git

# or offline, in your terminal, with the rest of the family
pip install awkno && awkno law 5
23laws
10chapters
MITlicense
0dependencies

The codex, in full

Ten chapters to get from nothing to a working setup, then twenty-three laws. Filter by part, or search for the failure you are actually looking at. Every row opens the document.

laws/33 of 33
Welcome to Aither Worldwhat this is, before you install anythingstart hereInstall awdkone command, then proof it workedstart hereYour first local brainan open model on your own computer, offlinestart hereTalk to itone question, then a conversationstart hereBuild your first agenta brain plus tools plus a jobstart hereAgent packsa whole agent in one commandstart hereYour own hardwareCPU, GPU, laptop, rackstart hereDeploy on awniximmutable Linux for machines where agents write softwarestart hereMany agents, one repoleases, a call graph, messaging, memorystart hereThe omniboxyour terminal answers youstart hereA rule nothing asserts is a suggestionthe first law, and the one every other law depends onenforcementMake it a check, not a ticketa mechanically-detectable defect must never be discharged by writing it downenforcementWatch your gate faila checker nobody has seen fail is not a gateenforcementMutate the test, not just the codea fixture that cannot fail proves nothingenforcementDesign for the silencethe expensive failures do not raisesilenceA check that cannot run must not passsilence is not a verdictsilenceThe symptom names the innocentfollow the wire, not the error textsilenceA checker in the wrong place found nothingand that is indistinguishable from a clean passsilenceDetection without delivery is not detectionthe alert path is the one thing you cannot verify by using itsilenceA gate that floods gets switched offbeing right too loudly is how a rule diesadoptionOpen green, ratchet downa gate that opens red gets bypassed, not satisfiedadoptionMeasure it againevery number in your docs is decaying right nowadoptionWritten is not deployedask the running thing, never the sourcedeploymentYou wrote it; that does not mean it shipsa file is tracked when the tooling says sodeploymentGenerate, never copya comment asking people to keep two copies in step is not a gatedeploymentThe defect lives in the unionevery file is individually correctdeploymentFail closed, then prove the happy patha gate that denies everything passes every denial testtrustNever trust the caller for an authorization decisionthe payload is not evidencetrustCount the closure, not the edgean import count is not a portability measurementtrustA platform you cannot ship to is not supportedthe OmniOS lawdeploymentA cap that does not survive a restart is not a capthe persistence lawconfigurationCoordinated decisions need a channel humans can readthe audit trail lawconfigurationA mixture-of-experts model has two budgets, not onethe resource coupling lawscaling

How to read it

The laws are grouped into seven parts. If you only have time for one, read Silence - those five cost the most per incident, because nothing tells you they happened.

start

Start here

Never used a coding agent? Ten chapters, about an hour, ending with one real verified change on your own repository. Covers local models and how to give an agent hands.

I

Enforcement

A standard nothing checks is a preference. How a preference becomes a property of the codebase - and why a checker nobody has watched fail is not a gate.

II

Silence

The expensive failures do not raise. They return 200, render correctly, log nothing, and leave the container healthy. A missing thing is indistinguishable from a thing nobody wanted.

III

Adoption

A gate only works while people keep it switched on. Most gates die of being right too loudly - so narrow the rule, pin the count, ratchet down.

IV

Deployment

The gap between the code you wrote and the code that is running. A build can succeed and ship nothing; a live mount makes the file current and leaves the process stale.

V

Trust

Patterns no linter will catch, because they are semantic: the gate that fails open, the decision keyed on input the caller chose, the count that measures the wrong thing.

VI

Configuration

A setting is only real if it survives a restart and reaches the process that reads it. A cap in a file nothing loads is a wish; a decision several agents make together needs a channel a human can read.

VII

Scaling

Where the numbers stop meaning what they used to. A mixture-of-experts model has two budgets, not one, and a plan that adds capacity without asking which one it feeds adds nothing.

Quick start

The codex is markdown. Clone it, read it, or point your agent at it - the laws are written to be loaded by an agent as easily as by a person.

bash
git clone https://github.com/Aitherium/awknowledge.git
cd awknowledge

# the reading path
ls path/

# the twenty-three laws
ls laws/

# the same corpus, offline, searchable
pip install awkno && awkno search silence
The laws are descriptive, not aspirational. Every number here was counted on a running system on the day it was written, and several of the incidents are ones where the first diagnosis was also wrong. Where a law contradicts something you know about your own stack, believe your stack and re-measure - that is literally law twelve.

The whole method is four steps

Not a reading list. The laws exist to be installed, and this is the loop that installs them. A codebase run this way gets harder to break over time without anyone having to be careful.

1 · Something breaksA real failure, in production or in review. Not a hypothetical.
2 · You fix itRoot cause, not a workaround. A workaround that cannot be avoided gets recorded with a date and a severity.
3 · You ask one questionCould a check have caught this? This is the step everyone skips, and it is the only one that compounds.
4 · If yes, the check IS the workWrite it. Watch it fail on purpose. Wire it somewhere unattended. Do not write a ticket - a ticket is the cheapest possible response to finding a defect, and it is why the same class recurs for weeks.

One estate, 8 doors

These projects are organs of the same system — the same identity plane, the same agent runtime, the same operational discipline. Follow any of them.

the osaitherium.comThe Living OS these four repos are cut from. Open, no login.pythonAither ADKBuild AI agent fleets — 3 lines, any backend, local or cloud.markdownawskillsPortable agent skills — self-contained procedures an agent loads on demand.markdownawknowledgeHow to run a coding agent so the result survives — the laws, with evidence.cudaaitherkvcacheNear-optimal KV cache quantization for LLM inference — sub-byte compression.powershellAitherZeroPowerShell 7+ automation framework — numbered, self-describing scripts.writingThe BlogHow all of it is actually built, measured and operated.pythonawrunA priority-aware queue and dispatcher for agentic runs and ad-hoc CI builds. It also judges whether the runner pool is big enough for the queue it is draining, and can ask a host to grow it -- reserving capacity is zero-sum, so a saturated pool needs more of it, not a different share of it.

The ecosystem this belongs to

Every Aitherium repository publishes an aither-manifest.json beside its page, and each surface reads all of them — so the network is browsable from any node in it. A repository that publishes nothing shows as unknown, never as zero.