How Brain connects to the outside world. Adjust paths and hosts to your own setup.
- Path:
~/notes/(any git-tracked markdown notes/wiki directory works — Obsidian, vimwiki, plain files) - Access: Direct filesystem read/write within the granted paths only.
- Diary:
~/notes/diary/YYYY-MM-DD.md— daily entries. - Work notes:
~/notes/work/— tasks, worklog, people, notes. - Format: Markdown.
- Access boundary: Only the paths listed in
.claude/settings.json(permissions.additionalDirectories) are readable. Keep this tight. - Tip: If your notes are git-tracked with a periodic autocommit, pull before reading when freshness matters.
- Auth:
gh auth login. - Commands:
gh pr list— open PRsgh pr status— PRs relevant to yough pr view <number> --repo <owner/repo>— PR detailsgh api notifications— unread notificationsgh search prs --review-requested=@me— PRs awaiting your review
- Limitations: Rate limits apply. Batch queries when possible.
If you use GitHub Enterprise or a self-hosted GitHub, set up a ghe shell alias that runs gh against that host:
# ~/.zshrc or ~/.bashrc
ghe() { GH_HOST=github.example.com gh "$@"; }
Then ghe pr list, ghe search prs --author=@me, etc. work the same as gh. Document any quirks here (e.g. auth that doesn't persist in headless/cron contexts).
- Usage:
claude -p --model <model>for non-interactive (print mode) execution. - Models:
opus(thorough tasks),sonnet(faster/cheaper tasks),haiku(cheap summarization). - Note: Reads
CLAUDE.mdfrom the working directory automatically. In Brain,CLAUDE.mdis a symlink to the canonicalAGENTS.md.
- macOS: Use LaunchAgents in
~/Library/LaunchAgents/. Example templates live inlaunchd/. launchd runs missed jobs on wake; cron silently skips them if the machine is asleep. - Linux: cron or systemd timers work fine.
- Brain tasks: scheduled jobs call
scripts/run-task.sh tasks/<task>.mdand log tologs/cron.log.
- Brain repo: Commit early and often. Every change should be reversible.
- Other repos: When delegating cross-project work, subagents can commit and push if asked.
Gives you mobile access to Brain. Runs as a persistent service.
- Code:
agent/src/main.py, using a venv atagent/.venv/. - Config:
agent/.env(copy fromagent/.env.example). Holds the bot token and your allowed user ID — never commit it. - Logs: stdout →
logs/telegram-bot.log, stderr →logs/telegram-bot.error.log.
Service management (macOS launchd):
# Status
launchctl list | grep telegram-bot
# Restart
launchctl kickstart -k gui/$(id -u)/com.brain.telegram-bot
# Stop
launchctl bootout gui/$(id -u)/com.brain.telegram-bot
# Start
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.brain.telegram-bot.plist
Image handling: Photos sent via Telegram arrive as a temporary URL (valid ~1hr, often blocked by robots.txt). Download immediately with curl -sS -L -o /tmp/brain-tg-img-XXXXX.jpg <url> before doing anything with the image.
Brain works well with MCP servers for services you use — issue trackers (Linear, Jira), team chat (Slack), internal wikis, etc. Add them via Claude Code's MCP configuration and reference them from skills. The example skills (work-snapshot, catchup-podcast) show the pattern of pulling from a chat/wiki MCP; replace those with your own integrations.
Track integrations you want but haven't set up yet here (e.g. Google Calendar API, a notes sync, a specific MCP server).