Skip to content

Latest commit

 

History

History
82 lines (58 loc) · 3.75 KB

integrations.md

File metadata and controls

82 lines (58 loc) · 3.75 KB

Integrations

How Brain connects to the outside world. Adjust paths and hosts to your own setup.

Notes (filesystem)

  • 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.

GitHub (gh CLI)

  • Auth: gh auth login.
  • Commands:
    • gh pr list — open PRs
    • gh pr status — PRs relevant to you
    • gh pr view <number> --repo <owner/repo> — PR details
    • gh api notifications — unread notifications
    • gh search prs --review-requested=@me — PRs awaiting your review
  • Limitations: Rate limits apply. Batch queries when possible.

A Second GitHub Host (optional)

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).

Claude CLI

  • 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.md from the working directory automatically. In Brain, CLAUDE.md is a symlink to the canonical AGENTS.md.

Scheduling (launchd / cron)

  • macOS: Use LaunchAgents in ~/Library/LaunchAgents/. Example templates live in launchd/. 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>.md and log to logs/cron.log.

Git

  • 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.

Telegram Bot

Gives you mobile access to Brain. Runs as a persistent service.

  • Code: agent/src/main.py, using a venv at agent/.venv/.
  • Config: agent/.env (copy from agent/.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.

MCP Servers (optional)

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.

Not Yet Configured

Track integrations you want but haven't set up yet here (e.g. Google Calendar API, a notes sync, a specific MCP server).