Home

shelldon

An E-Ink AI pet for the Raspberry Pi Zero 2W — chat-first, with a remote-LLM brain and a face that lives on your desk.

shelldon is a tiny AI pet you talk to. A little face on an E-Ink screen talks back, remembers what you tell it, drifts through moods on its own, dreams to consolidate what it has learned, and can even write its own tools — all running as a systemd service on a 416 MB Raspberry Pi, with the LLM brain living safely off-device.

This wiki documents the system as it actually works: the architecture, every subsystem, and how to run it on real hardware.

---

Start here

Understand how it works

• Architecture — the multiprocess actor model, the message bus, and the core invariants (LLM-free core, fork-per-turn worker, single-writer regions)
• How a Turn Works — the full lifecycle of one message, from your text to a reply and a reacting face
• The Brain — the broker, the provider chain, fallback, and graceful degradation
• Memory & Learning — conversation history, curated memory, the secrets vault, and the dream cycle
• Personality & Autonomy — mood, reflexes, the scheduler, budgets, and self-directed action
• The Screen — the E-Ink display, faces, and the three-zone status bar
• Self-Coding — how the pet writes, gates, and runs its own tools, behind your approval
• Plugins & Extensibility — the plugin model and the shipped plugins

Run it & work on it

• Quickstart — new here? start here — a chat pet running in your terminal in ~5 minutes, no hardware
• Running on the Pi — hardware, the one-shot installer, the systemd service, and operations
• Configuration — environment variables and the .env that drive it
• Development — setup, tests, the import-linter contracts, and the repo layout
• Extending shelldon — recipes: add a provider, a memory op, a face, a scheduled job, a plugin

---

At a glance

Hardware	Raspberry Pi Zero 2W (416 MB), Waveshare 2.13″ V4 E-Ink HAT, optional PiSugar2 battery
Brain	Remote LLM via a provider chain (GLM/Z.ai, Anthropic, OpenAI-compatible) — the Pi can't host a model
Talk to it	A Telegram bot — text it from your phone
Language	Python 3.13, uv + hatchling, 700+ tests
Footprint	Runs under a 400 MB memory cap; an ephemeral fork-per-turn worker keeps RAM flat

What makes it interesting

• The core never touches an LLM. All model I/O lives in the worker and broker; an import-linter contract enforces it. See Architecture.
• Each turn forks a worker that dies when done — so a long-running pet never accumulates memory (the failure mode that killed its predecessor). See How a Turn Works.
• It remembers and dreams. Facts you share are curated into memory; a periodic dream cycle consolidates observations. See Memory & Learning.
• It writes its own tools — proposed by the model, gated by a real test run, promoted only after you approve. See Self-Coding.
• The face is a reaction, not a status icon. The model picks its own expression and a short thought for each message, and they linger before settling back to mood. See The Screen.