Soberdriver

A single-context, multi-agent nightly audit orchestrator for a workspace of markdown notes, tasks and goals. Part of the Miracle Maker family (sibling of Miracle Oracle — they grow from the same shared agent_utils harness).

Soberdriver runs a fleet of domain agents over your workspace, each scoped to a slice of it (growth, dev, life, work — configurable). Every agent audits its files, fixes what it can, and writes a short summary. An aggregator then reads all summaries, finds cross-domain conflicts, and regenerates a single dashboard.md. Optionally it sends a Telegram report.

Pipeline

domain agents (N)            aggregator                 report
┌──────────────┐            ┌──────────────┐           ┌──────────┐
│ audit        │  summary   │ cross-domain │ dashboard │ Telegram │
│ fix          │ ─────────► │ analysis     │ ────────► │ (opt.)   │
│ summary      │  ×N        │ + rewrite    │  .md      │          │
└──────────────┘            └──────────────┘           └──────────┘

• Domain agent (scripts/domain_agent.py) — audits a domain in one of two modes:
  • unified — one Claude call (audit + fix + summary in a single context)
  • fragmented — three separate calls (audit → fix → summary), context lost between them
  • The two modes are an A/B experiment; swap them per domain over time to isolate the effect of the approach from the effect of the domain.
• Orchestrator (scripts/soberdriver.py) — runs the domain agents sequentially, logs each run to a JSONL experiment ledger, runs the aggregator, writes dashboard.md, and sends the report.
• Harness (scripts/agent_utils.py) — shared utilities: driving the claude CLI, Telegram send, env/proxy loading, MSK time. Bundled so each repo is self-contained.

Strong anti-fabrication rules are baked into every prompt: agents write only what is explicitly in the files, never invent statuses, blockers or cross-project links.

Requirements

• Python 3.10+
• The claude CLI installed and authenticated (Soberdriver drives it via subprocess — no API key in this repo).
• pip install -r requirements.txt

Configuration

Copy .env.example to your workspace as .env (or point SOBERDRIVER_DOTENV at it):

Variable	Purpose
WORKSPACE_DIR	Path to the workspace to audit (defaults to ~/.soberdriver)
BOT_TOKEN	Telegram bot token (optional — omit to skip the report)
CHAT_ID	Telegram chat id for the report (optional)
SOBERDRIVER_MODEL	Claude model id (defaults to claude-opus-4-8)
HTTPS_PROXY	Optional proxy for outbound requests

The domains and file lists in scripts/domain_agent.py (AGENT_CONFIGS) and the common files in scripts/soberdriver.py are examples — adapt them to your own workspace layout.

Run

# a single domain agent
WORKSPACE_DIR=/path/to/workspace python3 scripts/domain_agent.py dev --mode unified

# the full nightly orchestration
WORKSPACE_DIR=/path/to/workspace python3 scripts/soberdriver.py

Schedule it via cron, e.g. nightly at 05:00:

0 5 * * * WORKSPACE_DIR=/path/to/workspace /usr/bin/python3 /path/to/scripts/soberdriver.py

License

MIT — see LICENSE.