“Org chart as code” usually means a versioned file that says who exists, who answers to whom, and what each worker may do — read by the system that runs them rather than drawn for people to look at. For a crew of AI agents, that file already exists, and it is less grand than the phrase suggests. It is the crew’s configuration: which personas are on the roster, where each one posts, which engine login it runs on, what it does and when, who may approve its proposed changes, and what it may do without asking.
Klingbar has no separate org chart file, no hierarchy of units, and no chart designer. It has one configuration document per crew, kept on klingbar.com and versioned there. This guide covers what that document holds, what it deliberately leaves out, how to review a change to it, and when you need very little of it.
Where the document lives
A crew is a roster of personas that watch a business and report in Slack. It runs on a box — a Linux machine you control — and klingbar.com holds the record of what the crew is.
You edit the configuration on klingbar.com, through forms, and every save becomes a new numbered version. klingbar.com renders each version to TOML, and the box writes it to disk as crew.toml in that crew’s directory. Nobody edits that file on the box. It is output, not source: a hand edit there is replaced by the next version from the web.
The box is the judge of whether a version works. Its own loader parses every rendered file before it replaces the running one, and the box reports what happened. A version reads pending until that report arrives, then either applied — by which box, and when — or rejected, with the loader’s own error. A rejected version never becomes the running configuration; the box keeps the last good file until a version it can load arrives. klingbar.com never assumes a file it sent was accepted.
Because every save is a new version, the history is complete. You can open any version, read the exact TOML the box received, see a line diff against the version before it, and restore it. Restoring does not rewind: it saves the old document again as a new version, so the version that was wrong stays in the history beside the one that fixed it.
The crew’s standing rules — the crew-wide text every prompt carries — are versioned the same way, with the same diff and restore, and the box reports when it has applied each version. Prompts are versioned too: every save of a persona or task prompt is a new version, with its author and time.
What belongs in it
Here is a trimmed example of the shape a box receives. It is illustrative rather than complete; the real file also carries box-local facts, such as where each engine’s binary lives.
[crew]
tz = "America/Chicago"
approvers = ["U0123ABCDE"] # Slack user ids
approval_expiry_hours = 72
[accounts.claude-a]
engine = "claude"
config_dir = "~/.claude-a"
[accounts.codex]
engine = "codex"
[personas.revenue]
display = "Revenue"
icon = ":chart_with_upwards_trend:"
channel = "#revenue"
account = "claude-a"
model = "opus"
effort = "high"
secondary = "codex" # standby seat, another engine
secrets = ["ANALYTICS_READ_KEY"] # names, never values
[personas.revenue.policy]
git_in_workspace = "card"
send_ceiling = "draft_only"
[personas.revenue.tasks.morning-review]
cron = "0 7 * * *"
timeout = "30m"
Read top to bottom, that answers “who is on this crew, and what are they allowed to do”.
The crew. Its time zone, its approver list, and how long a card waits for a decision before it expires. The approver list is Slack user ids, and it is the one field in the file that decides who can say yes to a change.
Accounts. Named engine logins on the box. An account is a label for a login you performed on the box yourself, not a credential in the file.
Personas. Each gets a display name and icon for its posts, the Slack channel it reports in, and a seat: the account, model, and effort it runs with. A seat can name a secondary — a standby taken when the primary login cannot run, for example because it hit a usage limit. A standby on a different engine is the shape that works; two accounts on the same login share one limit, and the web does not offer that pairing.
Policy. The default for every persona is that reads are free and every change is a card — a proposed change an approver decides in Slack or on the web. Policy adjusts that per persona. git_in_workspace = "free" lets a persona commit and push to one named branch inside its own workspace, because that branch’s history is the undo. send_ceiling = "draft_only" means anything addressed to a person outside the crew is composed and never sent, even after approval.
Tasks. What each persona runs and when: a cron schedule or on demand, a timeout, optionally a different channel for that task’s findings, and optionally a turn ceiling (max_turns) for the engines that take one.
Secrets, by name. A persona lists the secrets its runs may use, and only those reach its environment. The file carries names; the values are sealed in your browser to the box’s own key and never pass through the document.
The daemon reads the policy and writes the matching rule into every prompt that persona runs. That is worth knowing in both directions: the configuration is what the persona is actually told, and it is an instruction to the persona rather than a sandbox around the engine.
What does not belong in it
Behavior. How a persona does its job — what it looks at, how it decides, what done looks like — goes in its prompt. The prompt is prose a reviewer reads; the configuration is structure the box parses. A configuration that absorbs instructions stops being reviewable at a glance, and the glance is the point. The guide to writing an AI agent job description covers the prompt side.
Secrets. No token, key, or password belongs here, and in Klingbar there is no field that could hold one: the document names a secret, and the value travels separately as ciphertext klingbar.com cannot open. The mechanics are in sealing agent credentials.
Runtime state. Which runs are in flight, which cards are open, what last week’s runs spent. That lives on the box and reaches klingbar.com as events, where the runs, approvals, and questions pages show it. Mixing it into the configuration would produce a document that changes every minute, which destroys the review property that justified versioning it.
Reviewing a change
The value of a versioned configuration is that a change becomes a diff someone reads. Most lines in a diff are harmless; a few change what the crew is allowed to do. Read for those first.
- Who can approve changed? An edit to
approversis the highest-risk line in the document and often the smallest. On a crew’s own Slack app an empty list means any human who can reach a card can decide it, which is worth knowing before you save one; on Klingbar’s Slack app, klingbar.com refuses to save one. - Whose policy loosened?
git_in_workspacemoving fromcardtofree, a newpush_branch, orsend_ceilingmoving fromdraft_onlytononeeach widen what a persona does without asking. - Did a persona gain a secret? A new name in a persona’s
secretslist hands that credential to its next run. - Is there a new channel? A new channel changes who reads the findings, and a task-level channel can route one task’s posts somewhere its persona’s never went.
- Did a seat move to a different engine? A different engine is a different model with different habits, and a different subscription paying for the runs. That can be exactly right for a standby and surprising for a primary.
- Did a schedule or a limit change? A cron that went from weekly to hourly is a bigger change than one line suggests, and so is a longer timeout or a removed turn ceiling.
After you save, read the verdict. A rejected version tells you, in the box’s own words, what it could not load.
When you do not need much structure
Most crews start with one persona doing one job — a revenue review every morning, an error-log sweep every night. For that crew the configuration is a dozen lines: one approver, one account, one persona with one channel and one task, and the default policy. There is nothing to design, and nothing is lost by keeping it that small.
Structure earns its place when a real problem asks for it. Add a second persona when a job needs a different channel, a different seat, or a different policy — not to model seniority, because personas do not have careers. Add a secondary seat once you have seen a usage limit stop a run. Loosen a policy when you have approved the same kind of card often enough that the card has become ceremony, and not before.
Where to start
Write the smallest configuration that is true: the persona you actually need, an approver who is going to read the cards, the default policy, and one task on a schedule you would be glad to read. Save it, and wait for the box to say applied.
The conceptual case for writing the shape of a team down is on the page about an AI org chart. What exists in Klingbar is narrower and, for a small team, more useful: one document per crew, versioned, diffed, restorable, and checked by the box that has to run it. How the pieces fit together end to end is on how Klingbar works.