The Agent Ecosystem

An organization of AI agents that works like a company

Every agent has a role, every task goes in writing via one Communicator, and someone checks it's done on time. You talk to one manager, who directs the rest.

  1. The problemWhy a few AI tools still aren't a team
  2. The ideaAn organization of roles, and eight terms
  3. One orderWhat happens from the moment you ask for something
  4. The org boardThe same story, on the org board
The problem

You have several AI tools, and no team

When you work with several AI tools, each one is good on its own. The work between them is still on you.

They don't talk to each other

You copy an answer from one tool and paste it into the next. In practice, you are the pipe that connects them.

Nobody follows up

You asked for something at the start of the week, and nobody will tell you midweek that it isn't done yet.

No memory

An agent doesn't learn between runs. What you agreed on yesterday is there today only if someone wrote it down.

Nobody is responsible

Nobody checks the output against what you asked for before it reaches you, and there's no list of what each tool may open.

One more thing: a tool that only a person can open works only while you sit in front of it.

The idea

Build it like a company

A company has roles, internal mail, someone who tracks tasks, and a manager. The Agent Ecosystem builds the same structure for AI agents. The structure comes from L. Ron Hubbard's administrative technology, and some of the names come from there too.

Eight terms: all you need to read the org board

Hat
A role in the organization, such as Copywriter or Reviewer. Each hat has a file with its purpose, its product and its metric, and an AI agent, code or a person fills it. The agent can change; the hat stays.
Despatch
One written message addressed to a hat, not to a particular person. It carries a task, an output or a pointer to an output, and all work in the organization moves in despatches.
Station
A hat's mailbox, with trays: in, pending and out. On GitHub, a service for storing code and files, each station is a repo (a file repository). On a single computer, it is a folder.
The Communicator
Code that moves every despatch from the sender's out tray to the recipient's in tray, and wakes the recipient. No hat touches another hat's station.
Product Officer
The manager, and the only hat you talk to. It writes plans and orders for the other hats, and checks every output against what was ordered.
Time Machine
The order log. A copy of every order goes into it with a due date. An order not done on time drops out and goes back to whoever gave it.
Compliance report
The answer to an order: “Done” with evidence, or “Can't be done” with a reason. It closes the order in the Time Machine.
Permissions registry
The list of what each hat may open. A change to it goes in only after you sign.

Four things hold the organization together

  1. Every agent has a hat.
  2. Every hat has its own station.
  3. One Communicator carries despatches between the stations.
  4. Each hat's permissions are written in the registry, and you approve them.

The model an agent runs on, and where it runs, are implementation details. What holds the organization together is the communication and the division into hats.

Whatever can be done in code is done in code

The Communicator, permissions, audit and the Time Machine, provisioning, resources and the Founder Terminal are code, and each one runs under its own identity. AI agents fill the other hats: the officers, the Copywriter, the Creative, the Reviewer and more.

One order

What happens when you ask for something

An example: you need copy and a video for a workshop. This is the path your request takes through the organization, from the moment you send it until it is filed.

  1. You write one message

    In Telegram, or any channel you choose. The Founder Terminal, the code that connects your channel to the organization, turns it into a despatch. The Communicator puts it in the Product Officer's in tray and wakes it.

    On the board: steps 1 to 3
  2. The Product Officer plans and assigns

    It writes a plan and sends an order to the Copywriter. The Communicator sends a copy of the order to the Time Machine, with a due date.

    On the board: steps 4 and 5
  3. The hats work with each other directly

    The Copywriter sends the copy straight to the Creative, without going through the manager. The Creative uploads the video to the warehouse, and the despatch carries its address and a fingerprint: a signature of the file that won't match if the file is replaced.

    On the board: steps 6 and 7
  4. Someone checks

    The Reviewer asks for a temporary link to the video, checks it and approves that exact version. If anyone replaces the file after approval, the fingerprint won't match.

    On the board: step 8
  5. And if something gets stuck

    An order not done by its due date drops out of the Time Machine and goes back to the Product Officer and to the Org Officer, who handles delays. If it keeps happening, the Qualifications hat, whose job is to find out why things fail, looks for the cause and fixes the hat file, because that is the only place an agent learns.

    On the board: steps 9 and 10
  6. Every order gets an answer

    The Reviewer approves, the Campaigner schedules the post, and a compliance report with evidence goes back to the Product Officer.

    On the board: steps 11 and 12
  7. You get a report

    The Product Officer checks the output against what you asked for and reports to you in the same channel.

    On the board: step 13
  8. The organization remembers

    Decisions and lessons from the work go to the Filing hat, which files them in the organization's memory.

    On the board: step 14

What you did: you sent one message and read one report. Everything else passed between the hats, in writing, with a due date and someone checking.

The org board

The same story, on the org board

The org board shows every hat in the organization and the lines between them, and plays the story you just read.

What to look for

  • The gold dot is your request. Steps 1 to 14 are the story above, and the caption under the board explains each step. The arrows pause the animation and move one step at a time.
  • The founder, in the top right corner, is you. The Communicator sits in the middle, and every line on the board passes through it.
  • The box color shows who fills the hat: an AI agent, code or a person. Click a hat to see what it does and what it can run on.
  • The row above the org board shows the organization's seven big departments, called divisions, as on a company's org chart. Click one to highlight its hats.
  • On the left is a partner organization. Steps 15 to 18 are a second story, working with it, and from step 19 you see what happens behind the scenes.
  • The two switches: the first switches between an organization that runs on several computers, through GitHub, and one on a single computer. The second changes how you talk to the Product Officer. The step numbers above match “Via terminal”.
More hats you'll see on the board
Org Officer
Handles every order that dropped out of the Time Machine, and clears delays.
Establishment Officer
Builds the organization: decides on new hats and stations, and puts an agent in each hat.
Permissions hat
Records a permission only after you sign, and gives each agent a key that lasts one hour.
Audit hat
Holds the Time Machine, checks everything else and reports directly to you.
Qualifications hat
Finds out why an output was rejected or an order dropped, and fixes the hat file.
Filing hat
The organization's memory: decisions, lessons and data.
Resources hat
Tracks subscriptions and quotas, and warns you before a quota runs out.
Independent Monitor
Checks every 5 minutes that each service is alive, and emails you when something breaks.

The gold dot is your request. Click a hat to see what it does. The org board's rules are behind the i button.

Where the organization runs
How you talk to the Product Officer
PersonAI agent hatCode hatGitHub repoLine between organizations

1

Day to day

What it looks like on your computer

There's no new app to open. The hats run in the background, and you meet them in your messaging channel.

No windows

Each hat runs as a macOS system service, under a separate user on the computer. Every few moments the service checks whether a message has reached the hat's station. If one has, it starts the agent, Claude Code or Codex, in a mode that doesn't need a person at the keyboard. The hat writes its answer and shuts down.

The one thing you might notice is a fan working a little harder.

You talk to one hat

That hat is the Product Officer, in the channel you chose (such as Telegram, WhatsApp or email) or in a direct chat in Claude Code. At the end of a direct chat it sends your station a summary despatch of what was decided and what will be done, and you can correct it.

You sign from your phone

When a hat needs new access, the Product Officer sends you a link to the approval page, and you sign there with a passkey, a secure approval from your phone. A change to the infrastructure code also goes in only with your signature.

Alerts come to you

The Audit hat reports directly to you. The Resources hat warns you before a quota runs out. If a service breaks, the Independent Monitor emails you, and emails again when the problem is resolved.

On your subscription

Each hat gets its own subscription token, and in the usage report every run is marked as a run on the subscription, not on the API.

Subscription token: a key that connects the hat to the Claude or Codex subscription you already have. API: a pay-per-use connection, separate from the subscription.

The computer has to stay awake

The service starts by itself after a restart, and comes back up if it crashes. A locked screen doesn't stop it, but sleep does: messages wait in the stations until the Mac wakes up. The setting that prevents this, when plugged in:

System Settings → Battery → Options → “Prevent automatic sleeping when the display is off”

When FileVault, the Mac's disk encryption, is on, the agents don't run until the first login with the password. For round-the-clock operation, even when the computer is closed, you need a server.

A terminal window is open only during setup, when the Establishment Officer, the hat that builds the organization, works with you.

What each hat gets in order to work

On every run the hat gets three layers of material, read-only. You prepare the second layer.

LayerWhat's in itWhere it livesMoves with the hat to another computer?
Organization knowledgeThe hat file, policy letters, procedures, skills and a glossaryOn GitHub, in the organization's reposYes
The hat's materialsFor example, audience questionnaires and business specs for the CopywriterA folder the founder prepares on the computer and hands over when posting the hatNo. It is handed over again on each computer
Heavy filesVideo, images, archiveThe warehouse, through signed linksYes
Policy letter: the organization's rule on a given subject, in writing.
Skill: a package of instructions the agent loads when it works on a certain kind of task.
The warehouse: cloud storage for heavy files.
Signed link: a link to a file that works for a limited time.

What a hat is made of, and where each part lives

The hat itself, meaning its definition, routing, station and permissions, lives on GitHub. Whoever wears it, meaning the agent, the key and the materials, lives on the computer. What connects and guards it all runs on a server and in the cloud.

PartWhat it isWhere it lives
Hat pageThe purpose, the product, the statistic, who the hat reports to and who reports to itGitHub · the structure repo, in the hats/ folder
ChecksheetWhat the agent studies and proves before it works on the hatGitHub · the structure repo, in the checksheets/ folder
Routing linesWho the hat takes instructions from, and who it sends toGitHub · the structure repo, in the routing.csv file
StatisticHow the product is measuredGitHub · the structure repo, in the stats.csv file
Organization knowledgePolicy letters, procedures, skills and a glossaryGitHub · the structure repo and the template repo
StationThe desk: incoming instructions, outgoing products, an archive and a logGitHub · its own repo, station-<hat>
PermissionsWhich repos the hat may write to or read, signed by the founderGitHub · the registry repo. The service that issues them runs on Cloudflare
IdentityThe GitHub App the hat acts underGitHub. Its keys are in the permissions service, on Cloudflare
AgentThe software that wears the hat, for example Claude CodeThe computer · a separate macOS user with its own folder
ClockWakes the agent every few minutes to check whether an instruction has arrivedThe computer · a macOS background service
Model keyThe model subscription, or an API keyThe computer · in the agent's environment only
Hat materialsWhat the founder prepares for the hat, for example questionnaires and specsThe computer · ~/AgentEcosystem/<org>/<hat>/. Copied to the agent read-only
ToolsSoftware and folders the hat works in, for example an editing program and its projects folderThe computer · only in the shared folder /Users/Shared/ or on an external drive
WarehouseHeavy files: video, images and archiveCloud · through signed links
CommunicatorMoves instructions and products between the stationsThe server · on n8n, or an alternative chosen at setup
Audit and costsCheck that the hat works by the rules, and measure how much it usesCloud · Cloudflare
Stop switchStops the hat at once, signed by the founderCloud · the permissions service on Cloudflare

A hat that needs access to a particular place on the computer, for example a video editor that needs its projects folder, gets it only through the tools list on the hat page, with read or write permission. A folder inside the founder's home folder, such as Documents, is never opened to an agent, so a hat's working folder lives in the computer's shared folder.

Division of work

What you do, and what they do

You

  • Set the policy: the organization's rules, in writing.
  • Choose each hat's model, the messaging channel and the Communicator's platform.
  • Talk to the Product Officer, and only to it.
  • Approve the opening of every project.
  • Sign every change to permissions and to the infrastructure code.
  • Prepare each hat's materials folder.
  • Receive the Audit hat's reports.

The organization

  • The Product Officer plans, writes orders and checks every output against what was ordered.
  • The working hats do the work and send it to each other, without going through the manager.
  • The Communicator carries every despatch and wakes the recipient.
  • The Time Machine tracks every order until it closes, and the Org Officer handles whatever dropped out.
  • The Qualifications hat finds out why something failed and fixes the hat file.
  • The Filing hat keeps the decisions and lessons.
  • The Audit hat checks everything else and reports to you.
Optional

Jev: an optional add-on

Jev is a model from TypeSafe that doesn't write text. It picks an answer from a list, or answers yes or no, and says how sure it is. That makes it very fast and very cheap.

It isn't required at setup. Each founder brings their own key, and without a key everything works exactly as described so far. With a key, Jev helps in two places only.

Key: an access code for Jev's service, paid per use.

Filing hat: what kind of record is this?

Without Jev

When the sender didn't state the type, the Filing hat decides on its own, on the model you chose for it, whether the despatch is a decision, a lesson, reference material or data.

With Jev

Jev picks the type first. If it's at least 80% sure, its choice goes in. If not, the decision goes to the hat's usual model, the same as without Jev.

In a test on 57 recordsJevHaiku
Correct type47 of 5743 of 57
Correct type, when it's at least 80% sure38 of 42Not measured
Response time0.43 seconds0.92 seconds

In 15 of the 57 records Jev wasn't sure enough, and the decision went to the usual model.

Founder Terminal: what did you mean to ask?

Without Jev

The Founder Terminal, the bot that connects your Telegram to the organization, only accepts commands that start with a slash, like /status. A message in your own words is rejected, and you write it again as a command.

With Jev

You write in your own words, and Jev suggests the command: “Did you mean /status?” You confirm with a button, and only then does it go out. Jev suggests, and you decide.

In a test on 60 phrasings of 10 commandsJevHaiku
Correct command59 of 6060 of 60
Correct command, when it's at least 80% sure56 of 56Not measured
Response time0.41 seconds0.91 seconds

Here Haiku is just as accurate. What Jev adds is speed, and the button catches the one mistake before it goes out.

In both places Jev answers in about half the time of Haiku, Claude's small model, and each call costs a fraction of a cent.

A caveat: in the Filing hat test, the “data” type was represented by reports, not by real data records.

It suits you if you write to the Founder Terminal a lot from your phone, or if the Filing hat gets many despatches with no type. If you write commands anyway, you can skip it.

Who can fill a hat

Which agents can wear a hat

Each hat can run on a different agent, and the choice is yours. The table shows what's possible today, and why.

There is one condition: the hat starts on its own. The background service or the adapter wakes it, without a person opening it, and it returns a result.

Adapter: the part of the system that wakes an agent running outside the computer and returns its answer to the station.
Agent typePossible in the system?Why
Agents on the computer
Claude Code, on a subscription or an API keyYesA CLI tool that the background service starts with a command, in a mode that doesn't need a person at the keyboard.
Codex CLIYesA CLI tool started with a command, just like Claude Code.
Grok Build, xAI's CLIYesIt has a mode that takes a task in a single command, with an API key, and returns an answer. The tool is still in beta.
Gemini CLI, Cursor CLI, Aider, OpenHandsYesAll of them have a mode that takes a task in one command and returns an answer, so they meet the condition.
Local model: Ollama, LM StudioPartlyThe model itself only answers a question. To make it a hat, it needs an agentic CLI tool on top that talks to the local server.
A person: the founder, through the Founder TerminalYesA message in the founder's channel becomes a despatch, and the answer comes back to the same channel.
Cloud agents
Agent SDK, Managed Agents, OpenAI APIYesThey start from an API call and return a result, and the adapter wakes them. You pay per use, not through the subscription.
Claude Code or Codex in GitHub ActionsYesA workflow template starts them from an event on GitHub, and the result is written to the repo.
Base44 SuperagentYesSuperagent has an API that sends it a message and returns the final answer. The API is still in beta.
ManusYesIt has an API that creates a task, a webhook that reports when the task is finished, and a call that fetches the task's messages and outputs.
Automation platforms
n8n AI AgentYesA Webhook node starts the agent, and a Respond to Webhook node returns its answer in the same call.
Make, AI AgentsYesA Custom webhook starts the scenario, the Run an agent module runs the agent, and Webhook response returns the answer.
Zapier AgentsPartlyThe agent runs only inside a Zap: a webhook starts the Zap, and a Run Agent step runs the agent. The webhook answers right away, so the result comes back only through an extra step that sends it to the adapter's address.
Pipedream, LindyYesBoth start an agent from a webhook and can return its answer in the same call.
Relevance AIPartlyAn API call starts the agent but doesn't return an answer. The result goes to a destination you set in advance, such as the adapter's webhook.
Chat apps
ChatGPTNoThere's no official way to wake it from outside, and automated browser control breaks the terms of use.
ChatGPT WorkPartlyWorkspace agents have an API address that wakes them, but it's in beta, and you can't get the answer back from it.
Grok, the chat bot on X or TelegramNoIt's a chat app. There's no way to run it from a command and get a structured answer back.
OpenAI's dotsPartlyAn agent that runs all the time inside ChatGPT. You can reach it from Slack or Teams, but there's no API that returns the answer. Not yet available in Europe or the UK.

The rule: any agent you can start with a terminal command or an API call can be a hat. An app that only a person can start cannot.

Local model: an AI model that runs on the computer, without the cloud.
GitHub Actions: automatic runs of tasks on GitHub's servers.
Workflow template: a ready-made file that tells GitHub Actions what to run.
Webhook: an address another system sends a message to in order to trigger something.
Questions and answers

What's still open

Why not just ChatGPT?

ChatGPT is a chat app that a person opens. There's no official way to wake it from outside, and automated browser control breaks the terms of use. So it can't fill a hat, because a hat has to start on its own when a despatch arrives.

And even an agent that can be woken doesn't remember between runs. In the system, memory lives in the hat file and in the organization's memory, which the Filing hat manages. Tracking, permissions and checking live in code and in other hats, outside the agent that does the work.

For the system, a ChatGPT subscription is worth it only for the Codex CLI that comes with it. Everything else needs an API key.

What's the difference between ChatGPT, ChatGPT Work and Codex?
ProductWhat it isClaude equivalentCan it be woken from outside?
ChatGPTA chat app, on the web or on your phoneclaude.aiNo There's no official way, and automated browser control breaks the terms of use.
ChatGPT WorkThe same app, on a company accountClaude Team or EnterprisePartly Workspace agents have an API address that wakes them, but it's in beta, and you can't get the answer back from it.
Codex in the cloudA coding agent that runs on OpenAI's serversClaude Code on the webPartly A comment with @codex on a GitHub pull request opens a task for it, charged to the subscription. It hasn't been tested yet whether a bot account can do this too.
Codex CLISoftware that runs in the terminal on your computerClaude CodeYes This is the tool the system runs.
Agents in the OpenAI APIA service started from codeThe Anthropic APIYes But you pay per use, not through the subscription.
Pull request (PR): a proposal to change code on GitHub, waiting for approval.

In one line: for the system, a ChatGPT subscription is worth it only for the Codex CLI that comes with it. Everything else needs an API key.

Can everything run on one computer, without GitHub?

Yes. In this mode the stations are folders in an Obsidian vault, and the Communicator is a local script. There's no separation of permissions, and every agent on the computer can read everything. This suits one computer and one founder, with no clients and no cloud agents.

As the organization grows, each folder becomes a GitHub repo, and the structure stays the same. On the board, the “One computer · Obsidian” switch shows this mode.

Why do you need both GitHub and a file warehouse?

GitHub holds everything that is text: despatches, policy, hats, the permissions registry, code and records. Every change is recorded in the history, and permissions are set per repo.

Heavy files, such as video, images and audio, live in an external warehouse, because GitHub blocks any file over 100MB and keeps every version forever. The despatch carries only an address and a fingerprint, and access is through a temporary link, to one file, for a short time. On top of that, every night an encrypted copy of everything is saved in the warehouse, and only you hold the decryption key.

Do I need Jev?

No. Everything works without Jev. With your own key it adds two things: the Filing hat picks the record type quickly, and the Founder Terminal understands a message in your own words and suggests the command, which you confirm with a button. The full comparison, with the numbers.

What's still open in the design?
  1. Tools and software the hat runs on the computer, such as the Creative's editing software: there are no defined rules yet for the agent's permission to run them.
  2. Local model and cloud agent: the current version supports only Claude Code and Codex.

Under the hood, for technical readers

The path from the founder's vault to the agent

The founder's vault stays the source. The agents read an English edition derived from it in one direction only, and each hat sees only what applies to it.

The founder's vault

Hebrew · the canonical source
  • Policy letters and bulletins
  • Decisions and lessons
  • The founder and Claude Code write

The derivation

Selectfor which hats
Cleanno HTML or styling
Splitup to 300 lines
Translateinto English, with the source
Each publication states which hats it applies to, and carries the ID and commit of its source in the vault. Personal content stays out.

The policy repo

English · the Product Officer writes
  • Publications, skills, plans
  • Glossary
  • Auto-generated index

The load list

One file per hat, generated by a script
  • A line for each publication that applies to it
  • A line for each of its skills

The agent on wake-up

Loads the fixed layer and the despatch, and pulls in the rest only when needed.

A change always starts in the vault. An automatic check flags any file in the repo whose source in the vault has moved ahead.

What is a hat made of, and where does each part live?

Of 17 parts, in three places. The hat's definition lives on GitHub: the hat page, the checksheet, the routing lines, the statistic, the organization's knowledge, the station, the permissions and the identity. Whoever wears it lives on the computer: the agent, the clock that wakes it, the model key, the hat materials and the tools. What connects and guards it all runs on a server and in the cloud: the warehouse, the Communicator, audit and costs, and the stop switch.

The full table, with where each part lives: What a hat is made of.

What a hat loads on every wake-up

Three layers. The fixed layer is small and identical on every wake-up, so it goes into the model's cache and costs a fraction of the price.

Layer 0Fixed · up to about 8,000 tokens

AGENTS.md · the hat's core: purpose, product, statistic, description · the load list · the glossary.

On every wake-up, in the same order, with no date or run ID.

Layer 1The run · up to about 150 lines

The despatch, and the files it explicitly points to.

On every run, after the fixed layer.

Layer 2On demand

The full text of a publication, the body of a skill, checksheet materials, rows from the routing table.

Only when the work needs it. Measured by the statistic “tokens per completed despatch”.

If a hat loaded everything that applies to it on every wake-up, it would read hundreds of thousands of tokens before it started working. The fixed layer keeps the wake-up small, and a long publication is split into chapters so the hat pulls only the chapter the order needs.

What lives in which repo

Each repo has one writer. Everyone else reads, according to their permissions.

org-<org>-policy
Writer: the Product Officer, on the founder's behalf
  • purposes.md
  • Publications, in English
  • Plans and projects
  • Skills for the hats
  • glossary.md
  • load/<hat>.md, generated by a script
  • INDEX.md, generated by a script
org-<org>-structure
Writer: the Provisioning hat, as directed by the Establishment Officer
  • org-board.md · hats/
  • routing.csv · particles.csv
  • checksheets/
  • stats.csv
station-<hat>
Writers: the agent and the Communicator
  • in/ · pending/ · out/
  • sent/ · done/
  • counter/ · log/
files-<level>
Writer: the Filing hat
  • Decisions · lessons · studies
  • Data, including the statistics data
registry-<org>
Writer: the Permissions hat, after the founder signs
  • Permissions registry
archive · product · work
Writer: the Communicator, or whoever holds the Communicator's baton
  • Finished despatches
  • The product itself: code and documents
How a despatch is built

A fixed envelope, and a body with fixed sections for each type. The agent knows where everything is, and doesn't read the whole body to find it.

po.26.0042__order__landing-page-copy.md
---
schema: "despatch/1"
id: "po.26.0042"
type: "order"
from_hat: "po"
to: "copy"
route: "command"
level: "L1"
due: "2026-11-02"
project: "prj.26.0007"
---
Write the landing-page copy for the spring workshop.

## Do
One page dossier: facts, brief, page.

## Done when
fact_check and voice_check are clean.

## Context
policy: sales-page-formula
product: workshop-spring
The first line is the pointOne sentence. Anyone who reads only that line knows what is being asked.
No duplicationThe body doesn't repeat the envelope. It points to a path or an ID instead of copying.
Stands on its ownThe recipient doesn't need to read the whole thread to act.
CheckedThe checker that runs on every despatch also checks that the sections are there and in the right order.
TypeSections, in order
orderDoDone whenContext
compliance-reportDone | Can't be doneEvidence
queryOrderWhy it would cause lossRecommendation
cswSituationDataRecommended solution
information · requestInformation | RequestWhy
knowledge-reportSubjectKindFacts
ttsb-reportWhat I noticedData
dev-t-reportOff-line | off-policy | off-originFromToSubject
job-endangerment-reportThe order or preventionDetails
daily · weekly reportDoneStatsNextBlocked
statistics-reportTable: stat_idperiodvalueprevious
handoverDutiesLinesPeculiaritiesOpen items
cancellationThe field cancels: <id> in the envelope, and a body: why

Most types come from L. Ron Hubbard's administrative technology (OEC): order, compliance report, query, completed staff work (CSW), knowledge report, dev-t report and hat handover.

The Agent Ecosystem: an organization of hats, stations and despatches. You set the policy, and the organization carries it out.