cosinabox 0.1.0

Open-source Chief of Staff in a box. Opinionated, proactive, runs on your own infra.

cosinabox

Open-source Chief of Staff in a box. Opinionated, proactive, runs on your own infra.

CoSinaBox is a self-hosted AI Chief of Staff agent that runs your day. It ships with default morning briefing, pre-meeting prep, evening wrap, weekly review, and follow-up tracking. You configure who it's for, not what it does.

Key Features

• 5 built-in jobs: morning briefing, pre-meeting prep, evening wrap, weekly review, follow-up nudges
• Telegram-first: primary interface via Telegram bot
• Google integration: Calendar, Gmail, Drive (optional)
• SQLite memory: persistent context without external databases
• Zero telemetry: runs entirely on your infra with your API keys
• Extensible: add custom jobs via a thin user repo

Prerequisites

• Python 3.11+
• Anthropic API key (Claude powers the agent)
• Telegram bot token (via @BotFather)
• Optional: Google OAuth credentials (for Calendar/Gmail/Drive)
• Optional: Fireflies API key (for meeting transcripts)

Quickstart

# Install the engine
pip install cosinabox

# Scaffold your user repo
cosinabox init my-cos
cd my-cos

# Configure (edit .env with your API keys, then customize personality.md)
cp .env.example .env
$EDITOR .env
$EDITOR personality.md

# Verify setup
cosinabox doctor

# Run
cosinabox run

Development Setup

# Clone and install in dev mode
git clone https://github.com/user/cosinabox.git
cd cosinabox
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,google,fireflies,search,attio]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

# Lint & type-check
ruff check src tests
mypy src

See CONTRIBUTING.md for full development guidelines.

Project Structure

cosinabox/
├── src/cosinabox/
│   ├── agent/         # Claude API loop, routing, cost tracking
│   ├── app/           # App orchestrator (config, tools, jobs, alerts, chat)
│   ├── bot/           # Telegram adapter
│   ├── cli/           # CLI commands (init, run, doctor)
│   ├── jobs/          # 5 built-in jobs
│   ├── memory/        # SQLite persistence layer
│   ├── scheduling/    # APScheduler integration
│   ├── tools/         # External integrations (Google, Fireflies, Serper)
│   ├── prompts/       # Default prompt templates
│   ├── personas/      # Persona templates
│   ├── schemas/       # JSON schemas for config validation
│   └── templates/     # User-repo scaffold (used by `cosinabox init`)
├── tests/
│   ├── unit/          # Unit tests
│   └── stress/        # Stress/integration tests
└── docs/              # Architecture and design docs

Architecture

CoSinaBox follows an engine + thin user repo pattern (similar to Hugo + content, or Next.js + app code):

• Engine (cosinabox package): the agent loop, scheduling, tools, and built-in jobs
• User repo (scaffolded by cosinabox init): your personality, stakeholders, integrations config, and optional custom jobs

For detailed architecture, see docs/specs/2026-04-11-cosinabox-design.md.

Privacy

• Zero telemetry by default -- no data leaves your machine except to APIs you explicitly configure
• AGPL-3.0 license to protect against SaaS extraction without contribution
• README documents every external service the engine touches

Running Tests

# All tests
pytest

# Unit tests only
pytest tests/unit/

# With coverage
pytest --cov=cosinabox

License

AGPL-3.0-or-later. See LICENSE.