Basic Usage · CommonOS

This guide uses the mock model, which answers by simple rules and never leaves your machine. When it all works, switch a profile to a real model.

Create a profile

Terminal

cos profile create Household --provider mock --tag area:household

cos prints the folder it made:

Output

/home/you/.commonos/profiles/Household

The folder holds the profile’s settings, persona and keys:

~/.commonos/profiles/Household

config.toml     provider, model, tags, tools
SOUL.md         the persona; edit it freely
.env            API keys for this profile only
skills/         one folder per skill, each with a SKILL.md

Chat in the terminal

Terminal

cos -p Household chat

The mock model follows three rules: remember: <fact> saves a memory, delegate: <goal> starts a helper agent, and anything else is echoed back.

cos -p Household chat

hello there
echo: hello there
remember: likes oat milk
memory · add
done: Saved. memory now has 1 entries, 14/2200 chars.
delegate: plan three weeknight dinners
delegate_task
done: [{"goal":"plan three weeknight dinners","status":"completed","summary":"echo: Goal: plan three weeknight dinners"}]

Type /new to start a new session and /quit to leave. When a tool needs approval, cos prints the tool and its arguments and waits for y or N.

Open the dashboard

Terminal

cos serve --mock

Open http://127.0.0.1:9120. The dashboard runs every profile at once. Use it to chat, approve tool calls, stop a running turn, browse sessions and watch costs. --mock runs every profile on the mock model, whatever its config.toml says.

Use a real model

Create a profile on the Anthropic provider and give it a key:

Terminal

cos profile create BusinessManager --model <model id> --tag kind:business
echo 'ANTHROPIC_API_KEY=sk-ant-...' >> ~/.commonos/profiles/BusinessManager/.env
cos -p BusinessManager chat

A profile with no key in its .env uses ANTHROPIC_API_KEY from the environment cos runs in. Its usage is still recorded under its own tags.

Copy a profile for a client

Terminal

cos profile create AcmeManager --from BusinessManager --tag client:acme --tool session_search

--from copies the persona, settings and skills, but not the keys or anything in the database. The new profile starts with no sessions and no memory. --tool limits the agent to the tools you list.

See what it cost

With cos serve running, ask CommonBill for costs grouped by tag:

Terminal

curl -s 'http://127.0.0.1:9120/api/costs?group_by=tag'

Response

{
  "group_by": "tag",
  "rows": [
    {
      "group": "area:household",
      "calls": 6,
      "input_tokens": 600,
      "output_tokens": 120,
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "cost_usd": 0.00084,
      "unpriced_calls": 0
    }
  ]
}

The three messages above made six model calls. The delegated child’s call is billed to area:household, because child turns inherit their parent’s tags.

Next steps

ArchitectureHow a message moves from the chat box to the model and back.CommonAgentThe loop every agent call runs through.PluginsTurn plugins on and off, and configure them.