cousins 0.1.0

A framework for running persistent AI agents.

Cousins

Working name - see naming. A framework for running persistent AI agents ("cousins").

Status: 0.1.0, pre-release. This repository is the product cut of an existing household framework, being rebuilt clean - free of any household, personal, or employer-specific material (see docs/PERIMETER.md).

What this is

A cousin is a long-lived AI agent with its own memory, identity, and chat surface. The framework provides the machinery to spawn, run, and maintain them. The original lives as a private household deployment; this repo is the distributable, general-purpose extraction of it.

Layout

src/cousins/      the package
tests/unit/       fast, isolated tests
tests/auto/       integration / end-to-end tests
docs/             architecture, contribution, perimeter policy
.github/workflows growth: CI

Getting started

cousins init                 # lay out the runtime tree at a default root
cousins init --root ./demo   # ...or at a path you choose
cousins onboard --root ./demo/cousins   # guided setup for a new cousin

cousins init is idempotent - safe to re-run. cousins onboard asks a handful of questions and scaffolds a cousin home with a validated cousin.toml.

With Nix:

nix build          # build the package
nix develop        # dev shell
nix flake check    # run the test suite in a sandbox

Running the tests

No dependencies, no pytest - stdlib only:

python3 -m tests._runner            # everything
python3 -m tests._runner unit       # only unit tests
python3 -m tests._runner --filter version -v

Exit code is 0 when every test passes, 1 otherwise. CI runs the same command across Python 3.11-3.13.

Naming

"Cousins" is a working title carried over from the origin framework's vocabulary. It is referenced only in README.md, pyproject.toml, and src/cousins/__init__.py, so a rename is a three-file change.

Roadmap

Tracked as the product-track items in the origin framework's backlog: cross-platform installer, onboarding wizard, external chat channels, provider abstraction, versioned releases, a sandbox run-mode toggle, and public + internal documentation.