Pocket

A local-first AI runtime for desktop skills. Not a chatbot. Not just a desktop pet. Pocket is an orchestration framework where a friendly desktop pet is the UI layer over a modular, model-agnostic runtime — powered on-device by MiniCPM (llama.cpp) with zero cloud dependency after first run.

Pocket is a fork of MiniCPM-Desk-Pet and is AGPL-3.0-only (the vendored pet + agent hooks carry that license).

Architecture — six layers

┌──────────────────────────────────────────────────────────────┐
│  ui/         Electron desktop pet · tray · settings · hooks    │  ← the relay
├──────────────────────────────────────────────────────────────┤
│  runtime/    Orchestration only: dispatcher + SkillRegistry    │
│  skills/     3-file skill contract  (DEFERRED — see CONTRACT)  │
│  services/   llm (real) · embeddings/search/storage/… (stubs)  │
│  providers/  base ABC · minicpm (real) · ollama/openai (stub)  │
│  data/       config · logs · models · adapters                 │
│  bin/        vendored llama-server + Metal dylibs              │
└──────────────────────────────────────────────────────────────┘

Dependency direction is strictly downward: ui → runtime → services → providers. Skills (when built) compose services; nothing depends up.

Governing rules

1. Everything becomes a skill. 2. Services stay reusable.
2. The runtime stays minimal. 4. Progressive disclosure.
3. Components stay model-agnostic.

What v1 is (and isn't)

v1 is the relay. Coding-agent activity (Claude Code + ~20 others) flows in through the ui/ hooks → the runtime → pet reactions, plus local MiniCPM chat.

• Real: the relay, local chat via the MiniCPM provider, the layer spine (Provider ABC → LLMService → Dispatcher), the empty SkillRegistry seam.
• Deferred but scoped: the Skills layer (skills/CONTRACT.md), the non-LLM services (services/deferred.py), the Ollama/OpenAI providers, and the embeddings/Data store. Adding them is additive — no runtime rewrite.

The two request flows, per the architecture:

• foreground query → Dispatcher.foreground → SkillRegistry (empty → falls through) → LLMService → MiniCPM.
• background event (hook) → bypasses the conversation path → pet reaction (UI state machine). The dispatcher is the seam a future skill-triggered reaction hangs off.

Run it

./go.sh doctor    # check node 18+, uv
./go.sh setup     # install deps (idempotent)
./go.sh           # start Pocket runtime + desktop pet

The model (MiniCPM5-1B-GGUF, ~1 GB) is fetched on first launch via the onboarding wizard, into data/models/ (gitignored). Drop a .gguf there beforehand to skip the download.

Layout

Path	Layer	Status
runtime/	Runtime	server (HTTP surface) + dispatcher.py + registry.py
providers/	Providers	base.py ABC, minicpm/ (real), ollama.py/openai.py (stub)
services/	Services	llm.py (real), deferred.py (embeddings/search/storage/notify/ocr)
skills/	Skills	CONTRACT.md only — deferred
ui/	UI	vendored Electron pet + agent hooks
data/, bin/	Data	config, logs, adapters, models; llama-server binary