Packages

Snippbot is a Python + TypeScript monorepo managed with pnpm workspaces (frontend) and pip/pyproject.toml (backend). Each package has a clearly scoped responsibility.

Repository layout

snippbot/
├── packages/
│   ├── core/          → snippbot_core   (shared Python business logic)
│   ├── local/         → snippbot        (self-hosted daemon)
│   ├── cli/           → snippbot_cli    (CLI commands)
│   ├── ui/            → React frontend
│   ├── device/        → snippbot_device (remote device agent)
│   ├── docs/          → This documentation site
│   ├── edge/          → snippbot_edge   [Future Phase 6]
│   └── cloud/         → snippbot_cloud  [Future Phase 7]
├── tools/
│   └── build/         → Build scripts (bundle_ui.py, etc.)
├── docs/              → Internal developer docs (AUTHENTICATION.md, etc.)
├── Makefile
└── pnpm-workspace.yaml

Package: snippbot_core

Path: packages/core/src/snippbot_core/

The shared business logic library. All major subsystems live here:

Module	Responsibility
config.py	Environment variable config with defaults
agents/	Agent models, memory, configuration
executor/	Task execution engine with DAG resolution
scheduler/	Cron/interval job scheduler (engine, models, stores)
workflows/	Workflow DAG builder, executor, template store
sub_agent/	Sub-agent spawning, lifecycle, messaging, aggregation
tools/	Built-in tool implementations (bash, browser, file, etc.)
tools/browser/	Full browser automation suite (12+ modules)
sandbox/	Container sandbox config and manager
mcp/	MCP client, connection manager, catalog, OAuth2
hooks/	Hook engine, executor, store, analytics

| channel_store.py | Messaging platform credential/binding storage | | skills_store.py | Tool registry and MCP server persistence | | event_bus.py | Async publish/subscribe event bus | | memory/ | Episodic, semantic, and graph memory layers |

Installed as: pip install snippbot-core (or -e packages/core in dev)

Python requirement: 3.11+

Key dependencies: anthropic, aiosqlite, httpx, pydantic, cryptography, playwright

Package: snippbot (local daemon)

Path: packages/local/src/snippbot/

The self-hosted daemon. Starts the HTTP API server and wires all core subsystems together.

Module	Responsibility
server.py	Main Starlette ASGI app + uvicorn startup
api/routes.py	All API route definitions (382+ KB)
api/chat.py	Chat endpoint with SSE streaming
api/scheduler.py	Scheduler REST routes
api/workflows.py	Workflow REST routes
api/auth.py	Auth key management routes
channel_adapter/	Platform-specific webhook adapters
channel_adapter/adapters/	slack, discord, telegram, whatsapp, teams, google_chat

Port: 18781 (API + static UI)

Installed as: pip install snippbot (pulls in snippbot_core)

Key dependencies: starlette, uvicorn, aiosqlite

Package: snippbot_cli

Path: packages/cli/src/snippbot_cli/

The command-line interface. Communicates with the daemon via HTTP.

Module	Responsibility
main.py	Click CLI entry point
user_config.py	~/.snippbot/config.toml read/write
commands/	Individual CLI command implementations

Installed as: pip install snippbot (CLI is included with the daemon package)

Key dependencies: click, rich, httpx

Package: @snippbot/ui

Path: packages/ui/

The React frontend served by the daemon at /ui/.

Directory	Responsibility
src/pages/	Top-level pages (Chat, Projects, Agents, etc.)
src/components/	Reusable UI components
src/stores/	Zustand global state
src/api/	React Query API hooks
src/styles/	Tailwind config + Aurora theme

Built with: React 18, TypeScript, Vite, Tailwind CSS, React Query, Zustand

Bundle output: Embedded in the snippbot Python package via tools/build/bundle_ui.py

Dev port: 5173 (proxies API calls to 18781)

Package: snippbot-device

Path: packages/device/

The lightweight device agent that runs on remote machines.

Module	Responsibility
main.py	Click CLI entry point (snippbot-device)
agent.py	WebSocket client to daemon
tools.py	Local tool implementations (bash, file, system_info)
config.py	~/.snippbot-device/config.toml management
pair.py	Pairing flow with daemon

Installed as: pip install snippbot-device on remote machines

Key dependencies: websockets, click, toml

Package: @snippbot/docs

Path: packages/docs/

This documentation site. Built with Astro + Starlight.

Dev: make docs-dev (port 4321) Build: make docs-build → packages/docs/dist/ Deploy: Cloudflare Pages → docs.snippbot.com

Build system

Bundling the UI

The React frontend is bundled into the Python package so users don’t need Node.js to run Snippbot:

# Build UI and copy to packages/local/src/snippbot/static/
python tools/build/bundle_ui.py

The daemon serves static files from snippbot/static/ at the /ui/ path.

Make targets

make install      # Install all Python + Node deps
make dev          # Run daemon + UI dev server concurrently
make build        # Build all packages (UI + Python wheels)
make test         # Run Python + TypeScript tests
make docs-dev     # Run docs dev server
make docs-build   # Build static docs site

Dependency graph

snippbot (daemon)
    └── snippbot_core (business logic)
            ├── anthropic SDK
            ├── aiosqlite
            ├── httpx
            ├── cryptography (Fernet)
            ├── playwright (browser)
            └── [optional] chromadb (vector memory)

snippbot_cli
    └── snippbot_core
    └── click, rich, httpx

snippbot_device (standalone)
    └── websockets, click, toml