The Borg

Welcome to The Borg — a personal AI workspace for turning prompts, notes, tools, agents, and repeatable workflows into something that feels a little more like an operating environment.

Yes, it is yet another ClaudeOS-style setup.

"Resistance" is probably unnecessary.

This repo is my personal AI workspace, shared in case the patterns, structure, or terrible naming choices are useful to someone else.

Want to run it yourself? → QUICKSTART.md — macOS setup in about ten minutes, including how to install only the scheduled tasks you actually want.

Directory Structure

• cerebruh/ — The shared second-brain wiki template. Personal knowledge, reusable context, and other things Future Me will definitely forget.
• c4po/ — The workspace administrator agent. Handles things like uptime, config, security, monitoring, and general “please don’t let this catch fire” duties.
• mrs-beast/ — The social media manager agent. Helps with posts, ideas, drafts, and occasionally making me sound more clever than I am.
• warren-bot-fett/ — The investment portfolio manager agent. Tracks portfolio ideas, market context, and other financially flavored stuff.
• bones/ — The family medical assistant agent. Tracks health context, surfaces medical information, and helps the family stay on top of care decisions.
• norm/ — The personal accounting and tax agent. Organizes financial records, supports tax planning and compliance, and prepares work for licensed-professional review.
• ari/ — The personal job recruiter agent. Finds suitable roles, tailors applications, prepares interviews, and helps evaluate offers.
• vinny/ — The personal legal-document and deal-negotiation agent. Reads agreements, tracks negotiation state, and prepares working material for counsel review.
• architetto/ — The software architect agent. Bootstraps greenfield repos — picking the stack, automated-testing framework, repo structure, and database — then hands them off with the decisions written down.
• repos/ — Where architetto parks the repos it initializes. Each is its own independent git repo; the workspace git-ignores the contents (structure only, via .gitkeep) so product code stays out of The Borg's history.
• jony-vibe/ — The graphic design and branding agent. Handles logos, color/type systems, layout, brand guidelines, and image-generation prompts.
• ebert/ — The personal entertainment recommender agent. Picks movies, shows, miniseries, and audiobooks for me, my partner, or date night — and remembers what flopped so it never pitches it twice.
• bernard/ — A case study, not an agent: the sanitized harness of a private health wiki and its family-facing WhatsApp companion agent (Bernard) — how it was built and what everything does.
• design/ — Design assets for The Borg repo itself, made by jony-vibe — right now that's the GitHub social preview, the card you see when someone drops a link to this repo in Slack. Design work for a repo under repos/ lives inside that repo's own design/ folder instead.
• tmp/ — Shared scratch space for any agent's working files. Git-ignored (structure only, via .gitkeep), so nobody's half-finished draft ends up in the history.
• LINT.md — The lint rules every AGENTS.md in the workspace is held to. Reference data, not always-on context — c4po reads it when auditing. See /lint-audit above.
• SOURCE-DOCUMENTS.md — How to read and cite an authoritative document — a contract, a filing, a statement, a scan — without confidently inventing what it says. Includes the .docx and scanned-PDF text-extraction recipes that actually work on a stock Mac (no tesseract required).
• MEMORY-INVENTORY.yaml — The governance registry for durable memory: every instruction file, rule, command, scheduled prompt, and wiki page gets a record saying why it exists, who owns it, what it costs to load, and when it's next reviewed — so the workspace's accumulated context can be audited instead of just accumulating. Schema in MEMORY-INVENTORY.schema.json; python3 .bin/build-memory-inventory.py validate checks it and python3 .bin/build-memory-inventory.py discover enumerates what is actually on disk — with --require-coverage, discovery fails on any artifact that has no record, naming its owner and the metadata the record must carry, which is how the monthly lint audit enforces the Memory inventory rule in LINT.md. Every artifact discovery finds now has a record, but most are status: draft — mechanically derived by build-memory-inventory.py bootstrap, registered but not yet reviewed. validate prints both numbers and validate --require-reviewed fails while any draft remains, so full coverage can't be mistaken for full review. Records for artifacts whose path is itself sensitive live in gitignored <agent>/.private/memory-inventory.yaml overlays, never here (see c4po/LONG-TERM-MEMORY-INVENTORY-DESIGN.md).

Scheduled Jobs

Each agent runs background tasks via macOS launchd. Plists live in ~/Library/LaunchAgents/ under the com.theborg.* namespace. Model jobs are driven by .bin/run-scheduled-task.sh; the model-less jobs (the CLI updater and the git Icon sweep) run their deterministic .bin/ scripts directly. Jobs log launchd output to <agent>/.claude/scheduled/logs/launchd.{out,err}. The plists embed absolute paths and aren't committed verbatim — regenerate them from the registered task schedules with the single .bin/install-scheduled-tasks.sh generator (add --load to (re)register them with launchd).

Scheduled jobs are harness-agnostic. Each one runs on Claude Code or on Codex, and the choice is per-job rather than baked into the runner. Resolution is last-wins: the built-in default claude, overridden by BORG_HARNESS in ~/.zshenv (the workspace-wide default), overridden by HARNESS=claude|codex in a task's .conf sidecar. .bin/run-scheduled-task.sh supplies whatever each harness needs to write unattended — --permission-mode bypassPermissions on Claude, a workspace-write sandbox with explicit .git writable roots on Codex — so a job can be moved between harnesses by editing one line and nothing else. A job whose chosen CLI is missing fails loudly with exit 127 rather than quietly running on the other one.

Jobs that spend a weekly budget resolve the reset at run time via .bin/weekly-reset.sh rather than having it baked into a schedule — it is an account fact that differs per user. On Codex it is derived from real account data (resets_at in the newest session rollout, a rolling window that legitimately drifts); on Claude nothing exposes it, so it comes from BORG_CLAUDE_RESET in ~/.zshenv and is audited monthly by Assumption H. An unknown reset never blocks a job — it runs and reports the gap.

The independent repos under repos/* reuse this same framework without being tracked here: a repo registers a job by dropping a <task>.conf beside its <task>.prompt (a SCHEDULE= line plus any per-run overrides — harness, model, extra CLI args, report mode), which the installer discovers from the filesystem and the runner sources at run time. Those repo-hosted jobs are documented in their own repo's README, not below.

Jobs notify the user by email via .bin/notify-email.sh <agent> [subject] (outbound Gmail SMTP; creds in the workspace root .env). Stdin is Markdown; notifications are multipart/alternative with the original plain text first and dependency-free rendered HTML second. Every job passes a short, descriptive subject (e.g. Borg security audit — 2026-07-03 — 0 finding(s)) so the inbox is scannable without opening each message. A model-driven job on Claude is pinned to a fixed --session-id, so its notification email includes an exact claude --resume <id> command for continuing the headless session; a job on Codex cannot pre-pin an id, so its footer carries codex resume <id> parsed from the run log (falling back to codex resume --last). Model-less maintenance reports need no resume footer.

A run that dies without producing anything still notifies. .bin/run-scheduled-task.sh emails on every non-zero exit and splits the subject two ways, because the two cases need opposite responses: a job that exhausted the weekly or 5-hour model budget terminates before its first tool call and is reported as scheduled task STARVED (usage limit), no output: <task> — wait for reset <clock> (nothing is broken; re-running before the reset dies the same way), while anything else is reported as scheduled task FAILED: <task> (exit N). The detection reads both the run log and — for a REPORT=1 task, whose stdout is redirected away from the log into its dated report — the captured report, since that is where the harness prints the limit message. launchd does not retry either case: a job with a state gate picks the work up at its next firing, a pure report loses that period's run. The scheduling half of this problem is handled separately by .claude/rules/burndown-window-is-not-schedulable.md.

A run that hangs is killed and reported, not left running. Each run has a wall-clock limit: 60 minutes by default, 6 hours for the backlog burndown, and overridable per task with TIMEOUT= in its .conf sidecar (90s, 45m, 2h; a bare number means minutes; 0 disables the limit). When the limit expires, the runner sends SIGTERM to the harness's whole process tree, then SIGKILL after a 30-second grace period. It writes a TIMEOUT line to the task log and exits 124. The email subject is scheduled task TIMED OUT, did not complete: <task>. The limit exists because a hung run blocks more than itself: launchd will not start a job that is still running, so the hang also silently skips the job's next firing.

For model-job details, see <agent>/.claude/scheduled/<label>.prompt; the CLI updater is defined in .bin/run-cli-update.sh.

c4po

Label	Schedule	What it does
c4po-security-audit	Daily at 10:00 AM	Audits all agent settings files, hooks, permission rules, secret-file hygiene (the root .env), and MCP servers for security issues. Emails the result every run — findings with recommended fixes, or an all-clear if clean.
c4po-lint-audit-monthly	1st–5th of each month at 9:00 AM¹	Audits the entire workspace — recursing into subdirectories and the independent repos under repos/* (generic rules only there) — against the lint rules in LINT.md. Emails the result every run — violations grouped by rule section, or an all-clear if clean. Runs once per month (state tracked in c4po/.claude/scheduled/state/).
c4po-assumptions-audit-monthly	6th–10th of each month at 11:00 AM¹	Runs the report-only ten-stage memory-governance audit: inventories every durable artifact, checks coverage and mechanical health, builds a privacy-safe generated snapshot, deeply reviews a bounded risk/cadence-based public cohort, evaluates its retirement triggers, and then runs the preserved external Assumptions A–H against current guidance. Private findings are count-only in email and route to the interactive command for review. Emails the result every run — findings and proposed permission-tiered remediation, or an all-clear if clean — and records state only after successful delivery. Runs once per month (state tracked in c4po/.claude/scheduled/state/).
c4po-privacy-audit-monthly	1st–5th of each month at 11:00 AM¹	Audits git-tracked files for identifying information and private medical or financial details, excluding documented allowlist entries. Emails findings and stops without remediation or state writes; emails an all-clear and records monthly state when clean. Never rewrites git history.
c4po-retro	Wed at 12:00 PM (Thu retry)² — just after the weekly Claude usage-limit reset (Wed 11:00 AM)	The multi-session counterpart to /retro. Runs on Claude (Opus, effort high) under the inherited auto permission mode, drawing on the fresh week's budget. Keeping it off bypassPermissions is deliberate: it is the one job that touches cerebruh/, and the Edit deny rules in c4po/.claude/settings.local.json are what mechanically enforce that the wiki stays read-only. Harvests durable lessons from the user's machine-wide Claude Code sessions (CLI and Claude Desktop) and Codex sessions (CLI and ChatGPT desktop), including archived Codex sessions, since its last run and routes them to the right home — proposed rules, AGENTS.md additions, and skills are emailed as a digest; durable shared knowledge is staged into for the user to ingest. Propose/stage-only — never writes Auto Memory or the cerebruh wiki. Emails every run — the digest, or a one-liner if nothing clears the bar. Runs once per week (state tracked in ).

mrs-beast

Label	Schedule	What it does
mrs-beast-social-media-drafts	Sun, Mon, Wed at 4:00 PM	Surveys the last 7 days of shipped work across the workspace and the WAIQ app, picks the single most interesting change (skipping topics already posted about), and emails one X (Twitter) post draft plus a ready-to-paste infographic prompt.

warren-bot-fett

Label	Schedule	What it does
warren-bot-fett-daily-market-scan	Mon–Fri at 9:00 AM — paused since 2026-08-06³	Fetches market data (indices, yields, VIX), checks portfolio allocations against targets, and emails the result every run — a specific trade alert when a genuine buying opportunity exists, otherwise a brief no-action summary (one-liner on market holidays).
warren-bot-fett-ai-sleeve-monthly	1st–5th of each month at 9:00 AM¹	Runs the AI Sleeve rebalance on the first trading day of the month: ranks candidates by market cap, enforces category minimums, computes floor-adjusted weights, and delivers a target-weights report via email. Writes ai-sleeve/last-rebalance.json for month-over-month diffs.

¹ Fired on days 1–5 as a retry window in case the machine was asleep on day 1. The prompt enforces once-per-month execution via a state file.

² Fired on the primary day plus the next day as a retry window in case the machine was asleep. The prompt enforces once-per-ISO-week execution via a state file.

³ Paused for a ~4-month account rebalance via launchctl disable, so the row stays in the installer's task table and its plist stays current, but --load skips the bootstrap instead of failing. A private one-shot job fires 2026-12-06 to ask whether to resume; re-enabling is deliberately manual:

launchctl enable gui/$(id -u)/com.theborg.warren-bot-fett-daily-market-scan
.bin/install-scheduled-tasks.sh --load

Slash Commands

Project-scoped command sources live in .claude/commands/ (workspace-wide) or <agent>/.claude/commands/ (agent-scoped, only visible to Claude Code from that agent's directory). Claude Code invokes them as /name. Run .bin/sync-codex-prompts.sh to adapt the same files into Codex skills, invoked as $name or selected through /skills.

The bridge generates <name>/SKILL.md under ~/.codex/skills/, keeps unique names, scope-prefixes collisions, and refuses to overwrite unrelated or locally modified skills. It preserves each command's description and adapts $ARGUMENTS, while dropping Claude-only frontmatter such as model: and argument-hint:. It does not manage ~/.codex/prompts/ at all — that surface is gone in Codex 0.145.0, and the 19 symlinks the old bridge left there were removed by hand on 2026-08-02. Run .bin/sync-codex-prompts.sh --check to detect drift.

Scoped Rules

Situational guidance that shouldn't load every session lives in <scope>/.claude/rules/*.md — Claude Code loads those files itself, scoped to the directory they sit in. Codex has no equivalent loader, but it scans .agents/skills from the working directory up to the repository root, which reproduces the same scoping. Run .bin/sync-codex-rule-skills.sh to publish each rule as <scope>/.agents/skills/<name>/SKILL.md, and --check to detect drift; the monthly lint audit runs the check.

The generated SKILL.md is a stub: the rule's name:, its description:, and an instruction to read the canonical .claude/rules/ file. The rule text lives in exactly one place and is never copied. Symlinking the stub instead would be simpler but does not work — Codex 0.147.0 follows a symlinked skill folder while silently ignoring a folder whose SKILL.md is a symlink.

A skill loads only when the model selects it on its description, whereas Claude loads an unscoped rule every session. A rule that must fire every time therefore also carries a one-line summary in the governing AGENTS.md — and, for rules that sit above a repos/* boundary, in that repo's AGENTS.md too, since a Codex session inside an independent repo never reads the workspace root.

Every prompt-driven Borg-agent scheduled task has a matching interactive command (named after the task, minus the agent prefix); repo-hosted tasks under repos/* and deterministic model-less shell jobs are exempt (see LINT.md → Scope and Scheduled tasks). Each paired command delegates to the same .prompt the launchd job runs — no duplicated logic — applying only the overrides needed for interactive use: skip once-per-month state gates and state/data-file writes, and report to the session instead of email.

Command	Scope	What it does
/f	workspace	Runs the given prompt on Fable in Claude Code; Codex uses its current model.
/h	workspace	Runs the given prompt on Haiku in Claude Code; Codex uses its current model.
/o	workspace	Runs the given prompt on Opus in Claude Code; Codex uses its current model.
/s	workspace	Runs the given prompt on Sonnet in Claude Code; Codex uses its current model.
/done	workspace	Closes out a finished thread with a one-line acknowledgement and nothing else. Treats the argument (and any "no" / "I'm done" style closeout text) as a close signal rather than a prompt to evaluate — no tool calls, no summary, no follow-up suggestions, no questions. Use instead of /h, which mis-fires by answering the closeout text.
/suggest	workspace	Suggests the single most useful follow-up in the workspace's standard ## Suggested Next Prompt format, with one directly reusable prompt and no extra commentary. An optional argument focuses the suggestion; when no meaningful next step exists, it says so without emitting the section.
/handoff	workspace	Creates a unique, privacy-safe Markdown snapshot under the workspace-root tmp/ so a fresh Claude Code, Claude Desktop, or Codex session can resume without the old transcript. Captures the objective, status, decisions, session-owned versus pre-existing git changes, verification, blockers, next actions, and a ready-to-paste resume prompt; an optional argument adds focus for the next session.
/remember	workspace	Save durable context to the current repository's shared Auto Memory store (~/.claude/projects/<project>/memory/) so it persists across sessions. Keeps MEMORY.md as a concise index and places substantive detail in linked topic files. With no argument, writes a concise gist of the current conversation; with an argument, saves that specific item as a standing fact or rule. Shows the proposed addition for approval before writing unless the request is unambiguous.
/push	workspace	Stages only the files the current session authored (this is a shared multi-agent monorepo — sibling agents' uncommitted changes are left alone or split into their own confirmed commit), commits with a concise message matching recent commit style (or the supplied argument as the message), and pushes to the current branch's remote. Reports the commit hash.

Status

This is one person’s working setup, not a polished product.

There is no roadmap, no SLA, and no sacred architecture. Things may move, disappear, mutate, or get renamed because I thought of a better pun at 11:47 PM.

That said, if you find something useful, please borrow it. Remix it. Fork it. Assimilate it into your own workflow.

Feedback, ideas, and “hey, this could be cleaner” notes are very welcome.

Forking it

Setup lives in QUICKSTART.md — prerequisites, BORG_ROOT, cloning, the Claude OAuth token, email notifications, the pre-commit hook, and installing scheduled tasks selectively. It's the only setup list; this section deliberately doesn't repeat it.

Two things worth knowing before you start:

• Read SECURITY.md before your first commit. There's a short forker checklist in there that may save you from accidentally publishing secrets, personal notes, API keys, or other spicy artifacts.
• You don't have to take the whole thing. Delete the agents you don't want and install only the scheduled tasks you'll actually read the email from.