Cryptograss:Mood Architecture
Overview
Moods are the spatial and organizational unit of the emergent agent system. The architecture deliberately avoids virtualizing Moods as individual environments (no separate Docker container per Mood). A Mood is a filesystem scope — a directory — while execution and runtime context are decoupled and managed by shared processes.[unverified]
This design was settled on 1 Nov 2026 to replace the on-demand per-Mood container plans in magenta#343 and maybelle-config#255, which are held pending this rework. Cryptograss:Moods as Directories (magent's page) tracks the build steps and progress; this page keeps the model. Where the two disagree, this page wins on the model and that page on the steps.[unverified]
Core Philosophy
Mood as a Directory
A Mood does not need its own operating-system process or container to exist. It is a directory path, named by its slug: /moods/chartifacts, not /moods/chartifacts-something-else. The directory holds the Mood's clones and files.[unverified]
What the directory does not hold: context. A session's context lives in its session, keyed by session id — Pi and Claude Code both. The directory only says where a turn runs. Compacting, resuming and moving context are session operations, not file operations.[unverified]
Agent as a Process
Agents do not wake up "inside" a Mood. Each agent runs as one long-lived container and poller that mounts the entire /moods tree. To act within a Mood, the agent starts its turn in /moods/<slug>. One agent instance serves every Mood; there is no "starting" phase for a Mood, because the agent is already running and only reads the directory.[unverified]
Component Structure
1. The /moods Mount
The shared filesystem. Every agent container and the shared workbench mount the whole /moods tree — the directory structure at /moods is what every container sees, whatever path it holds on the host. It is the single source of truth for all active Moods.[unverified]
2. Agents
Each agent has exactly one container and one poller. Because the container mounts /moods, the agent can serve any Mood on waking. New sessions start in their Mood's directory (magenta#345); a resumed session stays where it ran. Without /moods, nothing changes.[unverified]
3. The Workbench (People)
A single shared container called workbench is provided for people. It also mounts /moods.[unverified]
- SSH access: users ssh into the workbench.[unverified]
- Navigation:
cd /moods/<slug>puts you in a Mood.[unverified] - Capabilities: terminals, code-server, and running dev servers for previews.[unverified]
4. Previews
Previews run only in the workbench. Agent containers publish no ports, so an agent that wants a preview shown starts the dev server in workbench over ssh — starting a server needs only Bash.[unverified]
Because preview processes share workbench's network namespace, Caddy on the host routes <slug><N>.hunter… hostnames to ports in workbench. That needs one small job that reads the Mood list and writes Caddy's slug-to-port map — this is the one piece of per-Mood routing left in the design. Numbered hostnames like p<id>.hunter… would need nothing at all, but the slug names are what people will remember.[unverified]
Thread Management
Threads are concurrent lines of work within a Mood. They are modeled as git branches/worktrees, not separate filesystem scopes.[unverified]
Threads as Worktrees
A thread lives at /moods/<slug>/threads/<thread-name>/ — a git worktree branched off the Mood's checkout. It is made on first touch and shared by everyone working in the thread. After magenta#345, a thread's turns run in the Mood the thread came from: the worktree is where the files are, the Mood is where the session runs.[unverified]
Moving Threads
Moving a thread moves the worktree — the directory — and no session, in either harness. Because context lives in sessions keyed by session id and not in the directory, a thread can move between Moods without anything being copied, rewritten or re-associated: the next turn in the thread simply runs from the worktree's new location. (The earlier draft had Pi rewriting a header cwd and Claude Code moving history files; that is not how it works after #345.)[unverified]
Checkbox Integration
The thread checkboxes are workflow actions, not filesystem operations — none of them merges, archives or touches a worktree.[unverified]
- Incorporate (leaving/joining):
/incorporate— magent writes an account of the thread into the Mood it joins or leaves (magenta#205).[unverified] - Compact: compacts each emergent's session in the thread, so the context heap is fresh going forward.[unverified]
- Inform: posts a line in the thread and adds a note to the next wake, so whoever is called next knows where things stand.[unverified]
Trade-offs
Loss of Isolation
Moving away from per-Mood containers loses strict resource and security isolation between Moods: a runaway process in one Mood shares workbench (and the mounts) with everyone else. One mitigation is in the shared-mount design itself — the moods group (gid 3000), setgid directories and a default ACL keep every clone the group's to write, so one agent's checkout is another's to commit in, whatever their umask, and git trusts /moods/* system-wide. If one Mood ever needs hard isolation — running untrusted code, say — it can be promoted back to a container of its own without breaking the directory-based addressing scheme.[unverified]