Introduction
CommonOS runs Hermes-style personal agents in Rust, with one base agent, one Postgres database, and plugins.
CommonOS lets you run a separate AI agent for each area of your life and work: one for home, one for your own business, one for each client. Every agent runs on the same loop, keeps its own persona, keys, tools and memory, and writes to one shared database. Costs, memory and delegation are plugins.
It is built in Rust and follows the design of Hermes Agent: the same turn loop, the same hook points, the same rules for memory and child agents. If you know Hermes, you already know how CommonOS behaves.
Three layers
CommonOS has three layers. Each has one job, and each depends only on the layers below it.
commonos-cliThe command. Links the plugins in and starts everything.
- cos profile
- cos chat
- cos serve
common-bill · common-memory · common-delegateAdd hooks, tools, session context, tables and routes through one contract.
- CommonBill
- Memory
- Delegate
commonosThe host: profiles, the shared Postgres store, message routing, the plugin system, the dashboard.
- Profiles
- Dispatcher
- Store
- Dashboard
common-agentThe base agent. Every agent call runs through it. No Postgres, no web.
- Turn loop
- Hooks
- Tools
- Providers
- Prompt tiers
- CommonAgent is the base agent. Every agent call runs through it: the turn loop, hooks, tools, model providers and the system prompt. It knows nothing about Postgres or the web, so you can embed it anywhere.
- CommonOS is the host. It loads your profiles, routes messages to the right agent, stores everything in Postgres, runs the plugin system and serves the dashboard.
- Plugins add to it through one contract. CommonBill records what every model call costs. Memory gives each agent durable notes. Delegate lets an agent hand work to helper agents.
cos is the command that ties them together.
Core ideas
Profiles
A profile is one agent that you create. It is a folder with a persona (SOUL.md), a model, API keys, skills and an optional list of allowed tools. Profiles keep areas of work apart: a client’s agent cannot see your personal memory or use your personal integrations. No profiles ship with CommonOS. Read more about profiles.
Sessions and turns
A session is one conversation with a profile. A turn is one message from you and everything the agent does to answer it: model calls, tool calls, approvals. Every turn is stored with its status, so you can see exactly what happened. Read more.
Tags
Tags are key:value labels such as client:acme or area:household. A profile’s tags are copied onto every turn it runs, and onto every child turn it delegates. CommonBill uses them to report what each client or area costs. Read more.
Tools and approvals
Each tool declares a risk: read tools run, write tools ask you first, deny tools never run. You approve in the dashboard or with a y/N prompt in the terminal. Read more.
Hooks
Twenty-two hook points fire as a turn runs, with the same names and behavior as Hermes. A hook can watch, replace content, or block. Plugins use hooks to record costs, stream live events and enforce policy. Read more.
Good to know
- Profiles are not a sandbox. Tools run with your permissions. Profiles separate data and tools, not operating-system access.
- The dashboard binds to
127.0.0.1only. There is no login yet, so it never listens on a public address. - Replies are not streamed yet. The reply arrives when the turn finishes.