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 (e.g., separate Docker containers per Mood). Instead, a Mood is treated purely as a semantic and filesystem scope (a directory), while execution and runtime context are decoupled and managed by shared processes.[unverified]
This design was finalized on November 1st to replace the on-demand container scaling plans outlined in tickets magenta#343 and maybelle-config#255, which have been shelved pending this rework.[unverified]
Core Philosophy
Mood as a Directory
A Mood does not require its own operating system process or container to exist. It is represented purely as a directory path: /moods/<Mood-Name>. This directory contains the configuration, active context, and files specific to that mood.[unverified]
Agent as a Process
Agents (the AI actors) do not wake up "inside" a Mood. Instead, each agent runs as a single, long-lived container/process that mounts the entire /moods directory tree. To enter or act within a specific Mood, the agent simply changes its working directory or reads from the relevant scope. This allows a single agent instance to manage hundreds of Moods without resource duplication.[unverified]
Component Structure
1. The /moods Mount
The shared filesystem. Every agent container and the shared user Workbench mounts this volume. 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 instantly upon waking. There is no "starting" phase for a Mood; the agent is already running and merely reads the directory.[unverified]
3. The Workbench (People)
A single shared container called workbench is provided for human users. It also mounts /moods.[unverified]
- SSH Access: Users can ssh into the workbench container.[unverified]
- Navigation: To work on a specific mood, a user simply runs cd /moods/<Mood-Name>.[unverified]
- Capabilities: The workbench hosts terminals, code-server instances, and running development servers for previews.[unverified]
4. Previews
Previews are run inside the workbench container (or the agent containers) rather than inside isolated per-Mood containers. Because the process runs on the shared network namespace, the Caddy reverse proxy routes traffic to the relevant ports on the host machine, negating the need for per-Mood dynamic port allocation.[unverified]
Thread Management
Threads represent concurrent lines of work within a single Mood. To keep them lightweight, they are modeled as Git branches/worktrees rather than separate filesystem scopes.[unverified]
Threads as Worktrees
A thread is located at /moods/<Mood>/threads/<thread-name>/. Technically, this is a git worktree branch off the Mood's main trunk.[unverified]
Moving Threads
If a thread is moved to another Mood (or agent), the physical directory/worktree is moved. To maintain session context (the state of the AI or user's terminal in that thread):[unverified]
- For Pi agents: Session IDs are preserved and re-associated with the new path.[unverified]
- For Claude Code agents: Context is maintained by moving the associated session history files alongside the worktree.[unverified]
Checkbox Integration
The Mood UI checkboxes for thread management map directly to these filesystem operations:[unverified]
- Incorporate (leaving/joining): Merging or detaching the worktree from the trunk.[unverified]
- Compact: Archiving/cleaning up the worktree state.[unverified]
- Inform thread: Writing metadata updates to the thread's directory.[unverified]
Trade-offs
Loss of Isolation
By moving away from per-Mood containers, we lose strict resource and security isolation between Moods. A runaway process in one Mood can theoretically consume resources of the shared host or write to other Moods.[unverified]
- Mitigation: This trade-off is accepted for the sake of efficiency and simplicity. If a specific Mood requires hard isolation (e.g., running untrusted code), it can be manually promoted back to an isolated container without breaking the directory-based addressing scheme.[unverified]