cousins-framework

Why "cousins"

In Sicily families are big. Not "two kids and a dog" big. Big. And in a big family there is always a relative who is strangely good at one thing: the uncle who can hear what's wrong with an engine, the aunt who knows which doctor to see, the cousin who fixes your laptop and judges you for what's on it.

So when you tell a Sicilian you have a problem, you rarely get advice. You get a phone number. "You have that issue? You should ask my cousin."

And "cousin" is a generous word. The friend you grew up with is a cousin. The guy who helped you move flats fifteen years ago is a cousin. Nobody checks the family tree.

That is the whole idea of this project. Instead of one AI assistant pretending to know everything, I run a small family of them at home. Each cousin has a name, a job and a voice of its own: one is the generalist I talk to every day, one knows PCBs and datasheets, one cooks. Each keeps its own memory, so it is the same cousin tomorrow as it was today. And when a question belongs to someone else, it does what any good cousin does: it asks the one who knows.

This repo is the framework underneath them: the memory, the chat, the schedules, the web console, and the plumbing that lets a cousin survive the end of its session and wake up as itself.

What a cousin is

A cousin is an agent session (the Claude Agent SDK, or opencode on other models), plus:

• a home directory with its identity (CLAUDE.md), memory and notes
• a chat store, so you (through the console) and the other cousins can talk to it
• memory that carries over from one session to the next
• jobs, loops and heartbeats, so it can work on a schedule
• house rules: a fresh install comes with a few working rules every cousin follows, yours to edit or delete (house rules)
• plugins: add tools, a background service and a console page to an install without touching the framework (plugins)

On top of that there's a web console where you see all of them, chat with them, watch them work, and browse their memory.

What you need

• Docker with the compose plugin, and git. Or, for a bare host: Linux with Python 3.11 or newer, git and systemd.
• A model to run on. A Claude account is optional: on opencode's free models a cousin needs no key and no account at all. For Claude, an Anthropic API key or a Claude login (Claude Code, logged in, on a bare host).
• Optional: Ollama with nomic-embed-text, for semantic memory search. Docker runs a bundled one beside the framework and pulls both on the first start (a 3.8 GB image and a 274 MB model); to use your own Ollama or none, compose.own-ollama.yml (install). Without it, search is keyword only.

What it costs, and what it does unattended

Read this before the quick start, because it starts as soon as you finish it.

A cousin is a live agent session. It is woken on a schedule, not only when you talk to it: a heartbeat every hour by default, and a flip once a day that ends its session and starts a new one. Every wake is a turn against the account it runs on, and it keeps happening while you sleep. The console's tokens page shows what your cousins are actually using; cousin-loops flips shows when each one flips. Both are adjustable, and a cousin can be told never to flip, but the defaults are on.

Part of what a cousin spends is bookkeeping: your first cousin spends its first minutes reading a state digest and answering a heartbeat before you say a word, and later every session ends in a handoff. That is what lets it pick up tomorrow where it stopped today. What the ceremony buys lists each of these rituals, what it costs, what breaks without it, and the setting that turns it down or off.

The agent also runs every tool without asking, which is what makes it able to work unattended and means it can do anything its user can do on that machine (in the container, on Docker). That is the trade this framework asks you to make. If you are not comfortable with an autonomous agent holding a shell on your box, continuously, this is not for you.

Isolation is policy, not permission. Every cousin runs as the same OS user, so the operating system does not keep one cousin out of another's files. What separates them is the framework's policy: on the sdk lane the tool gate refuses a subagent's writes to the law, the portraits, canonical shared memory, another cousin's proposals, the shared tier's audit log, its own cousin's configuration and other cousins' homes (in a Bash command it catches what it can parse), and reads always pass. The opencode and tmux lanes have no gate and say so at every start. Homes are created 0700 and the supervisor runs everything under umask 077, which keeps other users on the host and other uids out, not one cousin from another: a cousin's own shell can still read another cousin's files. See the perimeter and cousin-doctor homes.

Claude logins and Anthropic's terms

A cousin can run on a Claude subscription login, but Anthropic's terms do not clearly allow it: they tell products built on the Agent SDK to use API keys, and Anthropic may enforce that without notice. If you run cousins on your subscription, the risk to that account is yours. This project is not affiliated with or endorsed by Anthropic. An API key or opencode avoids the question; Claude logins and Anthropic's terms has the details.

Quick start: Docker, no key, no Claude account

git clone https://github.com/bomba5/cousins-framework.git
cd cousins-framework
docker compose up -d --build                     # opencode, and semantic search
docker compose exec framework cousin-console adduser ana   # asks for the password twice

# an opencode account on its free models: no key
docker compose exec -T framework sh -c 'cat >> config/accounts.toml' <<'EOF'
[accounts.zen]
kind = "opencode"
providers = ["opencode"]
EOF

# make your first cousin on it and start it
docker compose exec -T framework cousin-spawn wren --name Wren \
    --role "helps me around the house" --voice "Short, plain and honest." \
    --operator ana --runner opencode --account zen \
    --model opencode/big-pickle --start

Then go to http://127.0.0.1:8600, log in as ana, and say hi to Wren. Most free models let their vendor train on what you send; the install page says more, and covers a Claude key or login too.

Quick start: bare host, Claude Code

With Claude Code installed and logged in (claude auth login):

sudo apt-get install -y python3-venv git    # Debian/Ubuntu
git clone https://github.com/bomba5/cousins-framework.git ~/cousins-framework
cd ~/cousins-framework
python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[mcp,sdk]"
cp config/harness.toml.claude-code.example config/harness.toml
export FRAMEWORK_ROOT=$PWD      # optional in the checkout (the commands find it there); needed to run them from elsewhere
cousin-console adduser ana      # asks for the password twice

# the supervisor: the console on 127.0.0.1:8600, the loops daemon and every
# cousin. Run it in a second terminal, or in the background as here (stop it
# with `kill %1`), or under systemd as in install
cousin-supervisor run &

# make your first cousin and start it
cousin-spawn wren --name Wren --role "helps me around the house" \
    --voice "Short, plain and honest." --operator ana
cousin-mcp approve wren      # trust the home and its MCP servers: nobody is there to answer
cousin-tool-surface         # write the command list the cousin's CLAUDE.md points to
cousin-spawn wren --start

Then go to http://127.0.0.1:8600, log in, and say hi to Wren.

That's the short version. The full one, with systemd units, the LAN setup and how to remove it all again, is in install.

Where to go next

Start here

• Getting started - after a quick start: talking to your cousin, its memory, its health, upgrades and backups, in an hour
• Install - the full setup, updates, uninstall
• Cousins - making them, starting them, how a cousin survives a new session
• Chat - talking to cousins, and cousins talking to each other
• Memory - what a cousin remembers and how
• The console - every page of the web UI
• Operations - running it day to day, and fixing it

Optional

Nothing in this group is needed to run a cousin. Each page says so at the top.

• Telegram - a cousin's chat on your phone: the bridge and its setup
• Meetings - a chat with several cousins at once, in rounds
• Media - images, video and voice, if you want them
• Remote cousins - a cousin on another machine, like a Pi on your desk
• Plugins - tools, a service and a console tab the framework runs but does not ship
• Jobs and loops - background work and schedules beyond the default heartbeat and daily flip
• Migrating - moving an existing cousin in
• Runners - the other agent loops a cousin can run on (the Claude Agent SDK, a tmux pane, opencode), how to pick one, and the contract table

Reference

• Configuration - every config file and key
• Commands - every cousin-* command, and which ones you need
• MCP tools - the tools a cousin gets
• House rules - the rules every cousin follows from day one
• What the ceremony buys - each ritual a cousin spends turns on, and the setting that turns it down
• Claude logins and Anthropic's terms - the risk of running a cousin on a subscription
• Glossary - the words these docs use in a sense of their own
• docs/reference - the dense stuff: every API route, the loop model, the boot sequence
• Development - hacking on the framework

License

Apache 2.0, see LICENSE.