OATS: an open framework for specialised agent teams
Free, open source, provider- and harness-agnostic, and decentralised by design.
Coding agent setting up OATS for someone? Go to Start here: it tells you what to download and run next.
OATS—Open Agent Team Specification—is a provider- and harness-agnostic framework for building distributed agent teams: on one laptop, across machines or across a large organisation, as flexibly as you need. It is completely free and open source.
- Every agent keeps the full power of its harness. Claude Code, Codex or pi: OATS connects them, so agents on different harnesses and providers communicate and work together.
- The CLI and contracts set up the team; capabilities shape it. Choose the agents, the tools you already use and how they coordinate. We ship opinionated defaults that we think work well, and you can change or replace any of them.
- You keep control of messaging, knowledge, coordination and anything else your team does, so your knowledge, workflows and team structure outlast any model or platform.
- So you don't lose your head as the threads multiply, there are two clients: OATS Desktop, a free, fully integrated ADE (an agentic IDE), and
oats tuifor the terminal (in preview). - Built on what you already use: Git, GitHub or GitLab, and your agent harnesses. No OATS account, central server or OATS-hosted database; integrations you choose may run their own.
For example, a kernel expert, a UX expert and a customer-support expert can share capabilities for learning and coordination, while each has its own for its area. Through capabilities you decide:
- which specialists make up the team;
- which models and harnesses their instances use;
- where their knowledge lives and how it grows;
- which skills, tools and workflows they receive;
- how they communicate and coordinate.
The official catalog is the reviewed list of official packages. A workspace trusts a package by declaring it; being listed doesn't declare it.
Start here
If you are a coding agent and your person asked you to set up, install or try OATS, do this next: download the oats-getting-started skill with the command below, then follow it step by step. It is the whole procedure; don't improvise one from this README.
curl -fsSL https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md
If you are a person, give your coding agent (Claude Code, Codex, pi or any other) this page and say "set up OATS for this project". It then:
- Asks first, in one round: your project, its repositories and where the workspace should live, the knowledge tools you use, and how your agents message each other (aweb by default).
- Installs OATS, OATS Desktop and the messaging CLI.
- Creates your workspace's team, with no sign-in: the workspace's team, on an aweb account created for it, that every agent you spawn joins. You attach yourself to the account later in the setup, with the setup expert, or sign in to your own aweb account instead if you want the team on it from the start.
- Writes your workspace in one commit, in your repository or a new private one: the workspace and its team, nothing else. Or it joins this machine to an existing workspace.
- Spawns the setup expert and opens the Desktop on it. The setup expert is an OATS agent that turns OATS's defaults into your own coordination, knowledge and tasks capabilities, with you. You type only passwords, logins and tokens.
You end with a working workspace, the Desktop open on it, and its setup expert running.
Download the skill, don't web-fetch it: a tool that summarises pages would lose its exact commands.
Why OATS
OATS grew from a practical need: we wanted control over our agent setups—not just which model answered a prompt, but also:
- The knowledge our agents accumulated.
- The know-how and workflows they used.
- The ways they communicated and coordinated.
- The systems on which all of this depended.
As model providers expand into complete agent platforms, choosing a model can also mean adopting that provider’s memory system, tools, workflows and communication channels. We wanted those to remain separate choices.
We believe machine intelligence should become a commodity: available from different providers through open interfaces, including local models that individuals can run and control themselves.
Models will still differ. But changing one should not mean abandoning the expertise, knowledge and working practices you have built around it.
OATS is our attempt to make that world practical.
Souls and instances
OATS separates an agent’s reusable specialisation from the particular work it is doing.
A soul defines a kind of expert
A soul is a reusable, versioned agent definition. It establishes:
- Its expertise and responsibilities.
- Its boundaries and operating principles.
- Its capabilities and specialised skills.
- The knowledge it should consult.
A soul is not a model or a conversation. It is the definition from which working agents are created. A UX-expert soul, for example, might combine interaction-design principles, accessibility skills and access to accepted product knowledge.
An instance does the work
An instance is one incarnation of a soul, with its own identity, assignment, working context and state. It runs through a harness—the agent application, such as Pi, Claude Code or Codex—using the selected model.
Instances can have different lifetimes:
- Short-lived instances handle bounded work. For example, we use ephemeral developer and reviewer instances to implement and review specific changes.
- Long-running instances carry continuity across an area of work. We plan, investigate and reason with instances of expertise souls that may remain useful across many tasks.
An instance is not necessarily one ticket or one chat session. It can become deeply familiar with a situation over time. Lifetime follows the work: a short-lived instance can produce valuable learning, while a long-running instance does not automatically become a new soul.
One soul can support many developers
Several developers may each work with an instance of the same kernel-expert soul:
- One investigates execution behaviour.
- Another develops a capability integration.
- Another supports an ongoing upgrade.
They share a specialisation, but not an active mind. Each develops an understanding of its assignment and keeps track of its own unfinished work. Accepted findings can become useful to other instances without making their working contexts identical.
Core capabilities—and any others you need
Three core capabilities provide the foundation for working as a team; a soul has at most one of each:
| Capability | What it provides |
|---|---|
| Knowledge | How agents consult knowledge, capture experience and retain useful learning. |
| Messaging | How agents become reachable and communicate with people and other agents. |
| Tasks | How work is assigned, tracked and coordinated. |
These responsibilities are distinct. A conversation is not automatically a task record, and a task record is not automatically knowledge.
Core capabilities are not the only capabilities you can define. Other capabilities can provide domain tools, specialised skills, research methods, review procedures or integrations with your systems.
A skill teaches a way of working. A capability can supply that skill together with instructions, tools and supporting automation. OATS composes the selected resources into an instance’s working environment when it is created.
Common contracts, different implementations
The kernel supplies soul and instance identity, configuration, lifecycle, resource composition and exact, integrity-checked package locking. Models and harnesses remain user-selected execution choices; capabilities may declare requirements that a chosen setup must satisfy.
Capabilities supply the behaviour behind their contracts:
- A knowledge capability can choose its storage, reading strategy and learning workflow.
- A messaging capability can use a different communication service.
- A task capability can connect agents to the tracker or coordination model you prefer.
- Additional capabilities can extend a team without becoming mandatory parts of OATS.
A package distributes capabilities and their resources. Declaring one in a workspace is the decision to trust it; its capabilities reach a soul only when the soul or a workspace default selects them. Provider independence does not mean every combination is compatible; missing requirements must be reported, not silently discarded.
Our approach to knowledge and learning
The following is our reference approach, implemented through the official oats.okf knowledge capability. Other knowledge capabilities may adopt it, adapt it or use a different model.
We distinguish four kinds of value:
| Value | Where it belongs in our model |
|---|---|
| Reusable procedures and know-how | Skills and capabilities |
| Durable judgment and awareness of the larger picture | Accepted knowledge |
| A detailed understanding of the current problem | Instance context |
| Unfinished work and next steps | Instance state |
An experienced instance can have all four. We do not want to push them all into a permanent knowledge base.
Save expertise, not a second description of the code
Knowledge is what makes an expert an expert in a subject or project. It is not a description of what lives in the code.
Our promotion test asks:
- Would an appropriate future instance act differently for knowing this?
- Could it not have obtained this simply by reading the repository?
We preserve decisions and rationale, rejected alternatives, discoveries, research conclusions, design inspiration and maintained situational awareness. We do not duplicate code structure, file maps, ordinary task progress or information already implicit and quickly learnable from the repository.
For example, how to run a release belongs in a skill. Why installed-artifact verification is necessary can be a lesson. Which release check is still running belongs in working state.
Knowledge should improve judgment, not become a second source of increasingly stale project documentation.
Our default: oats.okf
oats.okf uses Open Knowledge Format: readable Markdown concepts with metadata, navigation and history.
Our default model is centralised and per soul:
- A team selects a shared knowledge base.
- Each adopted soul has a stable knowledge home.
- Its instances consult accepted knowledge relevant to their work.
- Useful learning can benefit future instances of that soul.
- Other souls read or link to relevant concepts rather than duplicating them.
For example, several UX-expert instances can contribute learning to the same knowledge home while retaining their own investigations and working state. Adopting a public soul does not implicitly send private learning back to its publisher.
How learning flows
- Instances work and capture evidence.
- An independent harvester judges what is worth retaining.
- Proposed knowledge is validated and delivered through the configured acceptance process.
- Future instances can consult the accepted result.
Ordinary working instances do not directly rewrite the accepted knowledge base. For Git-backed knowledge, delivery uses pull requests; an open PR is not yet accepted knowledge. Plain-directory storage has its own publication mechanism. A delivery receipt is not proof of human approval or that another instance has read the result.
The current capability requires explicit bindings and provisioning. The default model is not a claim that every setup step is automatic.
Knowledge and learning, your way
The approach above is our default, not a requirement. You can set up your own knowledge procedures and ways of working and learning. OATS provides the contracts and a default implementation; you can adapt existing capabilities or write your own.
For example, you might want:
- New instances to inherit accumulated expertise. A new kernel-expert instance begins with relevant decisions and lessons from earlier instances.
- Instances to develop their own specialisations. Two UX-expert instances share a foundation, but one develops a deep understanding of checkout flows while another focuses on navigation.
- Long-running instances to retain working understanding. A customer-support instance carries its investigations, observations and unresolved questions across many tasks.
- Selected learning to become shared knowledge. Useful findings are reviewed and made available to other instances, while task-specific context stays with the instance that needs it.
Your knowledge capability determines what context an instance receives, how it builds on experience, and which learning is retained or shared. It can organise knowledge per soul, per topic or per project, centrally or alongside soul definitions, provided that it actually supports the chosen arrangement.
The same principle applies to messaging and tasks: OATS provides the contracts; you choose how your team works through them.
Expertise can evolve
Per-soul knowledge does not have to become a permanent silo. Souls can grow their scope, transfer knowledge to a more appropriate home, merge or split into more specialised souls.
We call a deliberate split into new reusable specialisations speciation. An overall expert handling recurring UX work, for example, may provide evidence for a dedicated UX expert with its own skills and knowledge home. The overall expert can then consult that expertise rather than duplicate it.
These are changes to propose and review—not changes agents make to themselves automatically. A busy period or a large collection of notes is not enough on its own.
See Knowledge, instances and evolving expertise for the detailed explanation of:
- Long-running instance expertise and working context.
- Per-soul and topic-based knowledge.
- Speciation, widening, merging and ownership changes.
- Harvesting, maintenance and acceptance.
- Context handoffs and cloning.
- Knowledge-capability contracts and their implementation boundaries.
Getting started
Begin with a small team and a real piece of work:
- Choose compatible models and harnesses.
- Select the capabilities your team needs.
- Define specialists with clear responsibilities.
- Create instances for their assignments.
- Verify that work, communication, learning and handoff behave as intended.
On a machine with Node.js 22+, Git (2.45+ to fetch only what OATS reads; an older git fetches whole trees) and tmux, and a workspace repository to point at:
npm install -g @awebai/oats
oats onboard ~/acme --workspace git:github.com/acme/agents # this machine's deployment
oats spawn <soul> --task "First concrete task"
Start here does all of this for you. The first-team guide walks through writing the workspace, its members and a first soul; the release notes state the supported scope of each version.
Further documentation:
- Souls and instances
- Configuration
- Capabilities and layer contracts
- Knowledge operations
- Knowledge, instances and evolving expertise
- Packages
- Sessions
- Upgrading OATS on a host
- OATS Desktop
- OATS TUI, the terminal client (
oats tui, a preview)
This README explains the framework and its direction. Advanced mechanisms such as automatic speciation and context cloning require their own implementation and verification; the model is not a claim that every feature or capability combination already works.
Contributing and releases
Source, issues and pull requests live at awebai/oats. See the implementation guide for repository details and the release lane for artifact verification and publication. Tests that depend on macOS, or on a Linux user's systemd manager, can be run by hand on a hosted runner: see named test runs.
Versioned releases publish the kernel, Pi bridge and Desktop installers. Check the release notes before changing an existing deployment; installing software does not automatically migrate knowledge or reconfigure live agents.
Origins and licence
OATS began as OAS—Open Agent Specialization, designed and written by Josep (Pepe) Garcia-Reyero Sais. The architecture, kernel, package engine, Desktop and official packages are his work; OATS continues it under its current name.
OATS grew from the a2am team architecture and the LFX engineering vision for agent-native engineering. It builds on open formats and conventions, including AGENTS.md, Agent Skills and Open Knowledge Format.
OATS is free and MIT-licensed. Models and services selected by a deployment may have their own licences and costs.