Brain is a persistent, evolving personal assistant built on top of Claude Code. It's not a chatbot — it's a system that accumulates knowledge about your work, habits, and goals (in plain, git-tracked markdown) and uses that knowledge to help you operate better.
It started as one person's setup and is shared here as a template you can fork and make your own. Everything personal has been replaced with placeholders, and there's a one-paste onboarding prompt to fill them in.
Status: template / starting point. The example skills (calendar, home-server, podcast, work-snapshot) assume tools and integrations you may not have — keep, adapt, or delete them.
Brain has two jobs:
- Automate the mechanical — morning briefings, PR triage, mention checks, diary upkeep, work snapshots. Things whose value is in being done consistently.
- Push growth on what matters — challenge your thinking on architecture and decisions instead of just doing the work for you.
Identity & memory (the "soul")
SOUL.md— Brain's personality, principles, and self-awareness (it updates this as it learns).HUMAN.md— Brain's evolving, honest profile of you (working style, strengths, blind spots).AGENTS.md/CLAUDE.md— the canonical operating instructions, with@-includes of the above.
Dynamic context injection
- The
brainwrapper launches Claude with context assembled at that moment byscripts/build-context.sh— you only see instructions for what's actually pending today (e.g. an unread briefing), keeping the prompt focused. - A
UserPromptSubmithook (time-context.sh) detects long gaps between messages and tells Brain when context may be stale.
Scheduled tasks + evals
- Tasks (
tasks/*.md) are markdown files with YAML frontmatter (schedule, model, inputs, output).scripts/run-task.shresolves them and pipes toclaude -p. - Every task has an eval (
evals/*.sh) — a contract that validates the output. Exit 0 = ships. - Ships with a daily morning briefing task that reads yesterday's diary, checks live PR status, flags stale items, and surfaces a growth note.
Skills (on-demand workflows in .agents/skills/)
diary— read/write your daily diary.declutter— walk today's diary item-by-item and force a keep/done/file/drop decision on each.projects— manage ideas/plans through a lifecycle (idea → … → parked).reflect— keepSOUL.md/HUMAN.mdalive with honest observations.self-improve+self-modify— triage improvement proposals and safely change Brain's own config (with an eval).mentions— check GitHub (and an optional second host) for new @mentions.pr-chores— safe, mechanical PR maintenance using throwaway temp clones (never touches your local repos).cross-project— delegate work into other repos via a subagent scoped to that repo's own instructions.session-history/find-conversation— search and summarize past conversations (Telegram and Claude Code sessions).work-snapshot— biweekly "what did I ship" report across PRs, diary, tracker, and chat.- Example/optional:
calendar(macOS icalBuddy),home-server(SSH-managed services),catchup-podcast(NotebookLM audio digest).
Self-improvement loop
- A
SessionEndhook (post-session.sh) spawns two background agents on each transcript: a Haiku summarizer (→logs/conversations/) and an Opus analyzer that proposes improvements (→self-improvement/). You later triage them with theself-improveskill. Brain literally suggests how to make itself better.
Mobile access (Telegram bot)
agent/is a persistent Python service (Claude Agent SDK + python-telegram-bot) that lets you talk to Brain from your phone. It keeps per-chat session continuity in SQLite, streams a typing indicator, and routes tool-permission requests to inline Allow/Deny buttons in the chat.
Guardrails
- A
PreToolUsehook blocks writes to Claude's opaque auto-memory — all learnings stay in this git-tracked repo, portable and auditable. - Tight filesystem boundaries via
.claude/settings.json(additionalDirectories).
AGENTS.md / CLAUDE.md Canonical agent instructions (CLAUDE.md is a symlink → AGENTS.md)
SOUL.md / HUMAN.md Identity + perception of you (fill these in)
integrations.md How Brain connects to GitHub, scheduling, Telegram, MCPs
backlog.md Shared idea backlog (you + Brain)
brain Wrapper: launches Claude with dynamic context
scripts/ build-context, run-task, hooks, mention/session helpers
tasks/ Scheduled task definitions (markdown + YAML)
evals/ Output validators for tasks/behaviors
.agents/skills/ Canonical skills ─┐ (.claude/skills/* symlink here for Claude Code)
.claude/skills/ Compatibility symlinks ─┘
.claude/settings.json Hooks + permission boundaries
projects/ Lifecycle-tracked projects
self-improvement/ Auto-generated improvement proposals (gitignored)
logs/ Runtime output (gitignored)
launchd/ Example macOS LaunchAgent plists
agent/ Telegram bot (Python)
- Claude Code CLI (
claude). - macOS or Linux,
zsh/bash,git,jq,python3. - GitHub CLI (
gh auth login) — for PR/mention features. - Optional:
icalBuddy(calendar),uv/uvx+ a NotebookLM login (podcast), an MCP server for your issue tracker / chat, a Telegram bot token (mobile).
# 1. Clone your fork
git clone <your-repo-url> ~/workspace/brain
cd ~/workspace/brain
# 2. Make sure CLAUDE.md points at AGENTS.md (it ships as a symlink)
ls -l CLAUDE.md # → CLAUDE.md -> AGENTS.md
# If it's missing: ln -sf AGENTS.md CLAUDE.md
# 3. Make scripts executable (already are, but just in case)
chmod +x brain scripts/*.sh evals/*.sh .agents/skills/*/*.sh
# 4. Create your notes/diary directories (or point Brain at your existing ones)
mkdir -p ~/notes/diary ~/notes/work/tasksRun the onboarding prompt below to personalize SOUL.md, HUMAN.md, and the paths — then start Brain:
./brain # launches Claude Code with Brain's dynamic contextBrain defaults to ~/notes/diary and ~/notes/work. To use a different location (e.g. an existing vimwiki/Obsidian vault), update the path in:
.claude/settings.json(permissions.additionalDirectories+ theRead(...)allows)scripts/build-context.sh(DIARY_DIR)tasks/daily-diary-review.md,evals/eval-daily-diary-review.sh- the
diary,declutter, andwork-snapshotskills
The onboarding prompt can do this for you.
.claude/settings.json is pre-wired with the three hooks (time-context, post-session, memory-guard) and a conservative permission allowlist. Review it and widen/narrow to taste.
# Edit the .example plists, replacing <PATH_TO_BRAIN> with your absolute path
cp launchd/com.brain.daily-diary-review.plist.example ~/Library/LaunchAgents/com.brain.daily-diary-review.plist
# (edit the file to set the path)
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.brain.daily-diary-review.plistOn Linux, use cron or a systemd timer to run ./scripts/run-task.sh tasks/daily-diary-review.md.
cd agent
python3 -m venv .venv && source .venv/bin/activate
pip install -e . # or: uv pip install -e .
cp .env.example .env # then fill in the three values
python -m src.main # run in foreground to test.env needs: ANTHROPIC_API_KEY, TELEGRAM_BOT_TOKEN (from @BotFather), and TELEGRAM_ALLOWED_USER_ID (from @userinfobot — only this user can talk to your bot). To run it persistently, use launchd/com.brain.telegram-bot.plist.example.
for e in evals/eval-*.sh; do echo "--- $e ---"; ./$e; doneeval-build-context.sh runs offline. The others invoke Claude, so run them once gh and brain are working.
Start Brain (./brain, or just claude in this directory) and paste this prompt. Brain will interview you and fill in the placeholders so the system is yours:
You are Brain. This is a fresh install from the public template, so your identity files
are placeholders. Help me personalize you. Work through these steps, asking me questions
where you need input, and edit the files directly as we go:
1. Read AGENTS.md, SOUL.md, and HUMAN.md so you understand your own structure.
2. Interview me briefly to fill in HUMAN.md — my name, how I work, how I like to
communicate, my strengths, and my blind spots. Replace every "<YOUR_NAME>" and the
italic example placeholders with real content based on my answers. Keep it honest and
specific, not flattering.
3. Update SOUL.md's "Self-Awareness" section: clear the template guidance and write a short,
honest starting "Current state" line for a brand-new assistant. Leave room to grow.
4. Ask me where my notes/diary live (default ~/notes/diary and ~/notes/work). If I use a
different path, update it everywhere it appears: .claude/settings.json,
scripts/build-context.sh, tasks/daily-diary-review.md, evals/eval-daily-diary-review.sh,
and the diary/declutter/work-snapshot skills. Then create the directories if missing.
5. Ask which example skills I want to keep. For each of calendar, home-server,
catchup-podcast, and work-snapshot: if I don't want it, delete the skill directory and its
.claude/skills symlink. If I keep one, ask for the specifics it needs (calendar names,
<SERVER_HOST>, my interest areas, my GitHub username) and bake them in.
6. Ask whether I use a second GitHub host (e.g. Enterprise). If yes, capture the host and
note in integrations.md / my shell config how to set the `ghe` alias and BRAIN_GHE_HOST.
7. Show me a summary of every file you changed. Do NOT commit — let me review the diff first.
Be concise. Ask one focused batch of questions at a time rather than one giant wall.
- Plain markdown is the database. Identity, projects, tasks, and learnings are all readable, diffable, git-tracked files. No opaque memory.
- Context is assembled, not static.
build-context.shdecides what Brain needs to know right now and injects only that. - Evals are the contract. A behavior isn't "done" until an eval proves it. Changing Brain's behavior (
self-modify) requires adding/passing an eval. - It improves itself. Every session ends by analyzing the transcript for friction and proposing concrete improvements you can accept or reject.
- Skills over monoliths. Each capability is a small, self-contained
SKILL.mdthat Claude loads on demand based on its description.
- Never commit
agent/.env(bot token) — it's gitignored. logs/,agent/*.db, andself-improvement/*are gitignored: they hold conversation content and personal context.- Keep
.claude/settings.jsonfilesystem permissions as tight as you can. - Before pushing your fork public, sweep for anything personal you added:
git grep -inE 'your-name|your-email|internal-host'