Brain

Kyle's second brain and AI agent hometown.

This is a public mirror of my private working repo. It holds of my core (non-project-specific) AI configuration, shell setup, CLI tooling, (obsidian-like) knowledge-graph, and macOS bootstrap that powers my (most) of my non-development workflows.

Quick walkthrough: https://youtu.be/ZbXWg_BPrgg

Join my live stream https://www.youtube.com/channel/UCvcUQVJEeLEFpNNpeyWG7cA/, leave a GitHub Issue, or email me at kylexrich@gmail.com if you have any questions.

Why this exists

I was tired of scattering AI config and scripts across a million places without unified git diff tracking. So I moved everything into one repo and symlinked where necessary. Once the scaffolding was there, it felt natural to build additional project-agnostic components and position this repo for growth over time.

Repository layout

cli/               — Brain CLI (oclif, TypeScript)
emily-repo-resources/ — Public-only generated Emily AGENTS snapshots + skills + guidance
deprecated/
  openclaw/        — Legacy OpenClaw runtime archive (not actively used)
system/            — Machine config (AI config, shell, bootstrap, symlinks)
  .ai/             — Source of truth: global instructions (AGENTS.md) + skills, mirrored to the configs below
  .dot-claude/     — Configuration for Claude Code and Claude Desktop (incl. generated CLAUDE.md + skills mirror)
  .dot-codex/      — Configuration for OpenAI Codex (incl. generated AGENTS.md + skills mirror)
  bootstrap-system.md — macOS setup guide
  credentials/     — Private local OAuth/client credential storage (excluded)
  symlinks/        — Per-machine symlink manifests + apply scripts
  zshrc/           — Shell config sourced by ~/.zshrc
  scripts/         — Small terminal utilities
vault/             — Knowledge graph (only conventions are public; content is private)

AGENTS.md files throughout are the rules-of-the-road for AI contributors — additive, hierarchical, nearest-wins. CLAUDE.md stubs next to them are auto-generated.

The Brain CLI

A TypeScript oclif CLI under cli/ used exclusively by AI agents. Topics:

• contact — Cross-source contact lookup (Google Contacts + macOS Address Book).
• music — Apple Music on Sonos: queue an artist's albums, queue a playlist, set exact group volume.
• stream — YouTube VOD pipeline: discover livestreams, download, transcribe locally, chunk, sync + publish metadata.
• image — Gemini image generation / editing.
• stt / tts — On-device whisper.cpp transcription and Microsoft Edge text-to-speech.
• repo — Maintenance: AGENTS.md header injection, public-mirror export, AI config sync, skill-folder sync.
• token — OAuth rotation (YouTube).

External tools needed: ffmpeg, ffprobe, whisper-cli (whisper.cpp, brew install whisper-cpp), yt-dlp, gog (Google Contacts), Sonos discovery (bundled at cli/bin/), curl.

AI configuration

system/.dot-claude/ and system/.dot-codex/ are the real AI configs symlinked out to ~/.claude, ~/.codex, etc.

• Codex config (system/.dot-codex/) — For OpenAI Codex.
• Claude config (system/.dot-claude/) — For Claude.
• Skills — Apple Notes, Reminders, Hue, Sonos, whisper transcription, image gen, video understanding, symlink management, scheduled-job skills, and more. Authored once in system/.ai/skills/ (the source of truth) and mirrored into each tool's skills/ folder by brain repo sync-skills, which runs on every build.
• Subagents (/agents/) — CLI-invoked iMessage handlers for a personal 1:1 and a group chat.
• BlueBubbles MCP server (system/custom-mcp/bluebubbles/) — A self-built HTTP MCP that bridges BlueBubbles iMessage into Claude sessions. Webhook-driven; one daemon serves many sessions.
• Scheduled tasks (/scheduled-tasks/) — Morning brief, video-processing pipeline, OAuth refresh, health nags, stream-light control, and a thrice-daily production log-health check that posts a digest to Slack.

System layer

• system/bootstrap-system.md — End-to-end macOS setup (Homebrew, tools, shell, auth flows, symlinks).
• system/symlinks/ — Per-machine manifest plus apply / teardown / verify script. The repo owns every config file; the manifest routes each one to where its tool expects it.
• system/zshrc/ — Modular shell config sourced from ~/.zshrc.
• system/scripts/ — Small terminal utilities.

The vault

vault/ is a lightweight, standalone knowledge graph — Obsidian-adjacent but file-only. One folder per content type (beliefs/, concepts/, experiences/, ideas/, thoughts/, sources/, quotes/, goals/, notes/, and others), with required frontmatter, strict bidirectional linking, and duplicate-prevention rules enforced in AGENTS.md at every level.

Only the conventions ship in this mirror; the notes themselves are private.

About this mirror

Generated by brain repo export-public from an allowlist in .public-export.json. The flow: git ls-files → include globs → exclude globs → copy with sanitize substitutions → a verify pass that fails the export if any redacted value leaks through.

The public mirror also includes emily-repo-resources/, a generated folder copied from an explicit allowlist in the private Emily repo. It contains selected top-level AGENTS.md snapshots renamed to AGENTS.source.md, manually allowlisted non-sensitive Emily skills, and the .ai/guidance/ reference docs those snapshots cite (grouped by source package under guidance/). This folder is public-only generated output: update the Emily source files or the .public-export.json allowlist, then run brain repo export-public.

Excluded or redacted: vault content, credentials, agent memory, session transcripts, plans / projects / backups, per-machine state, any other sensitive/personal information.

You will see the shape of the real brain repo, with some private content hidden.

Borrowing or forking

Borrowing a skill or the MCP server

Copy the relevant directory or file into your own setup. Many of the skills, agents, mcp servers, configurations, etc. are mostly self-contained by design.

The BlueBubbles MCP server has its own package.json under system/custom-mcp/bluebubbles/; npm install + wire up the env vars and run it.

Forking the whole thing

If you want the full setup on your own machine:

1. Fork and rename as you like.
2. Edit everything that is redacted (e.g. <BLUEBUBBLES_GROUP_CHAT_ID>), hard-codes personal values like kylexrich@gmail.com, kylerich or /Users/kylerich/, etc.
3. Supply your own credentials in system/zshrc/.env.
4. Work through (adapted) system/bootstrap-system.md.
5. Apply symlinks with the per-machine script under system/symlinks/.
6. Run npm run build (or brain repo sync-ai && brain repo sync-skills) to regenerate the CLAUDE.md stubs and the per-tool skill mirrors.

I don't promise a smooth path. This is personal plumbing, not a distributable framework.