An org chart as code is a versioned text file that declares which workers exist, which unit each belongs to, who approves their work, and what each may spend — read by the system that runs them, rather than drawn for people to look at. The distinction is not stylistic. A diagram describes an organization; a file that the runtime consults before it acts constitutes one.
For a team of humans that difference is mostly academic, because humans read the diagram and then behave. For a team of bots it is the whole game. A bot does not absorb an organizational norm by osmosis; it does what its configuration permits. If the shape of your organization lives in a slide, the shape your bots actually have is whatever fell out of the order you configured them in.
This guide covers what such a file has to declare, what a minimal one looks like, how it grows, how to review a change to it, and — the part most teams get wrong — what does not belong in it.
What the file has to declare
Four things, and they are not interchangeable.
Units. The groups work is organized into. A unit is the smallest thing a budget or a reviewer can attach to, which is why “one unit per bot” is usually a mistake: it leaves you with no level at which to say “research may spend this much in total”.
Members. The bots that exist, which unit each sits in, and the role each one holds. The role is separate from the bot on purpose. Roles outlive individuals — you replace the bot, swap the engine underneath it, and the role’s standards stay where they were.
An approver identity. The human the organization answers to. This is the field that turns a gate from a suggestion into a control, because “someone should check this” is not enforceable and “this identity must sign” is.
Budgets. What each role may spend, declared where a reviewer will see it. Money is the constraint that is easiest to leave implicit and most expensive to discover late.
Anything else you are tempted to add — prompts, API endpoints, retry counts — belongs somewhere else. See the last section.
A minimal chart
The smallest useful chart is smaller than most people expect. One unit, one member, one approver:
name = "acme"
approver = "dana@example.com"
[[unit]]
name = "research"
[[member]]
handle = "scout"
unit = "research"
role = "market analyst"
budget = "5.00 USD/day"
That is a complete organization. It declares a group, a worker in it, the role that worker holds, a ceiling on what the role may spend, and a human whose approval the gated actions route through.
Notice what is absent. There is no instruction telling the bot how to do market analysis — that lives in the role contract, a separate document. There is no engine credential. There is no schedule for a specific run. The chart answers “who is in this organization and what are they allowed to do”, and stops.
Growing it
Charts grow along two axes: more units, and deeper nesting. Both should be reactions to a real problem rather than anticipation of one.
Add a unit when two groups of work need different reviewers or different ceilings:
[[unit]]
name = "research"
budget = "40.00 USD/week"
[[unit]]
name = "editorial"
budget = "20.00 USD/week"
approver = "sam@example.com"
[[member]]
handle = "scout"
unit = "research"
role = "market analyst"
[[member]]
handle = "quill"
unit = "editorial"
role = "editor"
A unit-level ceiling binds everything inside it, so a unit budget is the control you reach for when the question is “what is the most this whole area can cost me”, and a per-member budget is the one you reach for when the question is “what is the most this one worker can cost me”. Both, together, is normal.
Nest when authority genuinely nests — when a sub-team’s work is reviewed by a lead who is themselves reviewed. Do not nest to represent seniority. Bots do not have careers, and a hierarchy that models status rather than authority just adds levels that no rule reads.
What makes a chart usable
A chart can be well-formed and still not run anything. Klingbar checks three facts before an organization can be activated, and they are facts about capability rather than about paperwork:
- The chart parses.
- Its root resolves to a declared member carrying an approver identity.
- It declares at least one unit.
That is a deliberately low bar, and the reason it is low is worth stating. An earlier version of this check graded provenance — were the live bytes the ones in the newest commit that touched the file? — which is a real question about process hygiene and says nothing at all about whether the organization could make a decision. The three facts above are the ones that determine whether it can.
The same function answers the setup checklist and the activation gate, so a checklist can never describe a bar that the gate does not actually apply. If you are building your own version of this, that property is worth more than it sounds: two implementations of “is this ready” will drift, and the one users read will be the one that is wrong.
Reviewing a change
The point of writing the organization down is that changing it becomes a diff someone reads. That only pays off if the review is structured. A checklist that works:
- Whose authority changed? Any edit touching an approver field is the highest-risk change in the file, and it is also the one that looks smallest in a diff.
- What ceiling moved? A budget increase is a decision, not a configuration detail. It should be as visible in review as a new member.
- Did a member change units? Moving a bot moves it under a different budget and a different reviewer at the same time. Those are two effects from one line.
- Is this reversible? Restoring a previous chart should be restoring bytes. If undoing a restructure requires reconstructing state that lives elsewhere, the chart is carrying something it should not.
In Klingbar the approval a human gives is bound to a hash of exactly the parameters being approved, and it is single-use, so a yes given to one version of an edit cannot be spent against a version that moved afterwards. That property is what makes “review the diff” more than an honour system; the mechanics are covered in the guide to human approval workflows.
Editing it without hand-writing TOML
A chart is a file whose exact bytes a human signs, which constrains what an editor may do to it. An editor that parsed the file and re-serialised it would reformat comments, reorder tables, and generally hand back a document that is semantically identical and byte-different — and the signature was over the bytes.
The way out is to treat every edit as a splice over spans of the original. Moving a member between units rewrites the span that describes that member and leaves every other byte untouched, so your comments, your ordering, and your formatting survive an edit made in a browser. Klingbar’s editor does exactly this, refuses to guess when it cannot map an edit to an unambiguous span, and falls back to a raw-text editor that is never taken away. The visual layer sits on top of markup that already works without it, which is also what keeps the whole edit-to-approval path reachable from a keyboard.
The editor deliberately does not validate, either. Validation belongs to the thing that will actually load the file: a browser-side check that disagrees with the runtime is worse than no check, because it teaches people to trust the wrong arbiter.
What does not belong in the chart
This is where charts rot. Three categories to keep out:
Behaviour. How a bot does its job belongs in its role contract — duties, boundaries, definition of done, when to escalate. A chart that starts absorbing instructions becomes a file nobody wants to review, and an unreviewed authority file is the failure this whole approach exists to prevent.
Secrets. No key, token, or credential should appear in a chart, and ideally your platform should make that structurally impossible rather than merely discouraged. In Klingbar a credential is sealed in the browser to the runner’s own public key and travels as ciphertext the control plane cannot open; there is no command in the vocabulary that carries key material as a flag. If you are self-assessing a platform on this, the question is not “are secrets encrypted” but “is there a code path where a secret could arrive in the clear at all” — a topic covered in the page on self-hosted agents.
Runtime state. Which bot is currently busy, when the last run happened, how much has been spent this month. The chart declares what is permitted; state describes what occurred. Mixing them produces a file that changes constantly, which destroys the review property that justified writing it down.
Where to start
Write the smallest chart that is true: one unit, the bots you already have, an approver who is actually going to read the diffs, and a ceiling low enough that hitting it is informative rather than catastrophic. Add structure when a specific problem asks for it.
The conceptual case for this approach, and the five topologies worth knowing before you pick one, are laid out in the page on an org chart written as code. The mechanics of the file are only half of it; the other half is being disciplined about what you refuse to put in it.