Architecture

Architecture

Principles

1. Autonomous, not orchestrated — each daemon runs independently. Pulse validates conditions, doesn’t control behavior.
2. Bash, not frameworks — each daemon is <200 lines of bash. Zero runtime dependencies beyond the shell.
3. File-based state — blackboard.json for shared state, circuit-breaker files for health, markdown for output.
4. Read-only by default — daemons collect data, they never modify external systems.

Components

brain-pulse (preflight validator)

Runs at 06:55 before any daemon. Responsibilities:

• Health check: is LiteLLM proxy up? Is OpenClaw CLI available? Are agent bins executable?
• Circuit breaker: reads failure counters from ~/.brain/System/circuit-breakers/. After 3 consecutive failures, a daemon is skipped until manually reset.
• Dependency graph: collectors run in parallel (m365, clickup, gworkspace), then secretary runs sequentially (depends on collector output).
• Blackboard update: writes run status, duration, and circuit breaker state to blackboard.json.

Collectors (m365, clickup, gworkspace)

Each collector:

1. Checks if its CLI dependency is installed (graceful degradation — creates stub window if not)
2. Checks if today’s window already exists (idempotent)
3. Calls OpenClaw with agent profile + template + learnings + previous windows
4. Writes a markdown “window” to ~/.brain/Agents/{name}/windows/{date}.md
5. Updates blackboard with status

Secretary (synthesizer)

Reads all collector windows + nag active items → generates a Chief of Staff briefing classified as DISPATCH / PREP / YOURS / SKIP. Detects carryover from previous briefings.

Independent daemons

• auditor: weekly review of all daemon learnings, template compliance, drift detection
• curator: processes Claude Code session transcripts into vault notes
• cleanup: manages disk cache (brew, npm, chrome, playwright)
• nag: tracks commitments with escalating reminders

File structure

~/.local/bin/
├── brain-pulse
├── agent-m365
├── agent-clickup
├── agent-gworkspace
├── agent-secretary
├── agent-auditor
├── cleanup-agent
├── vault-curator
└── vault-doctor

~/.brain/
├── Agents/{name}/
│   ├── config.json
│   ├── TEMPLATE.md
│   ├── LEARNINGS.md
│   └── windows/{date}.md
├── System/
│   ├── blackboard.json
│   └── circuit-breakers/{name}
└── logs/

~/Library/LaunchAgents/com.brain.*.plist

Stack

Component	Role
macOS LaunchAgents	Scheduling (plist per daemon)
bash	Daemon runtime
OpenClaw + LiteLLM	LLM calls via proxy
Obsidian vault	Knowledge base + daemon output
chezmoi	Dotfiles management (bins, plists)