53b605379e
* Fix istall/update scripts * test: capture pre-refactor install snapshot for regression Adds take-snapshot.sh script and the resulting snapshot/ directory, capturing the exact vault state produced by launchme.sh before the framework-agnosticity refactor begins. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Summary: Refactor agents/skills/hooks/mcp in agentic-platform-agnostic templates. refactor: rename source CLAUDE.md → DISPATCHER.md (framework-neutral) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> refactor: convert agent frontmatter from tools: to neutral capabilities: Replace Claude Code-specific `tools:` frontmatter with framework-agnostic `mode: subagent` and `capabilities: [...]` in all 8 agent files. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> refactor: add neutral hook trigger manifests (.hook.yaml) refactor: hooks read neutral JSON schema (args.* instead of tool_input.*) refactor: convert .mcp.json to neutral mcp/servers.yaml Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Implement agentic-platform adapters skeleton. build: add adapters/lib.sh skeleton with vocabulary constants test: bash test runner for adapter helpers Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> build(adapters): parse_frontmatter helper with tests Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> build(adapters): parse_capabilities helper with tests Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> build(adapters): should_include helper with tests Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> build(adapters): parse_hook_yaml helper with tests Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> build(adapters): agent_body helper with tests Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> build(adapters): enumerate_agents and enumerate_hooks helpers Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Implement agentic-platform adapter for Claude Code. build(adapters): claude-code adapter skeleton with capability/event tables build(claude-code): adapter_translate_dispatcher with test build(claude-code): adapter_translate_references with test build(claude-code): adapter_translate_skills with tests build(claude-code): adapter_translate_agents with capability→tools mapping build(claude-code): hook wrapper template (CC native → neutral schema) build(claude-code): adapter_translate_hooks with wrapper generation build(claude-code): adapter_translate_mcp with hand-rolled YAML parser build(claude-code): adapter_finalize and complete adapter_build wiring build: scripts/build.sh dispatches to per-framework adapter Also fix adapter_translate_hooks and adapter_translate_agents to use while-read loops (avoiding word-splitting on paths with spaces) and guard grep calls with || true to survive set -eo pipefail when hooks have no match-tool field. Remove scripts/build.sh from .gitignore. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Refactor install/update scripts to support agentic-platform agnosticity. refactor(lib.sh): generalize install_claude_md → install_dispatcher New signature takes the full destination path instead of just the vault dir, allowing callers to install CLAUDE.md, AGENTS.md, or any dispatcher file to an explicit location. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> feat(launchme): support --framework flag, build dist/ before install Add --framework and --target arg parsing. Run build.sh before installing to populate dist/<framework>/. All install_* calls now read from dist/<framework>/ instead of the raw source dirs. MCP is now handled automatically by the adapter (no interactive prompt). Replaced install_claude_md with install_dispatcher. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> feat(updateme): support --framework flag, build dist/ before update Add --framework and --target arg parsing. Run build.sh before installing to populate dist/<framework>/. All install_* calls now read from dist/<framework>/ instead of raw source dirs. Replaced install_claude_md with install_dispatcher. Also fix set -e compatibility in lib.sh: add || true to all conditional [[ ... ]] && info "..." logging lines so they don't abort the script when VERBOSE_COPY=0. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test: regression runner diffs dist/claude-code against pre-refactor snapshot - Add tests/regression/run.sh that builds dist/claude-code and compares against snapshot, excluding runtime-only artifacts (.mbifc-manifest, .mcp.json, .claude-plugin/plugin.json) - Fix adapters/lib.sh agent_body: preserve '---' section dividers in body (awk now only skips '---' while still inside frontmatter, fm < 2) - Fix adapters/claude-code/adapter.sh: change 'read' capability to expand to only 'Read', appending 'Glob, Grep' at end of tools list to match snapshot ordering - Update snapshot to reflect intentional refactor changes: hook JSON schema (.args.* instead of .tool_input.*), wrapper scripts, settings.json with wrapper paths, and consistent tool ordering for postman/sorter Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Implement opencode adapter. Co-Authored-By: win0na <winnie@winneon.moe> feat(lib.sh): add install_plugins helper for opencode JS plugins build(adapters): opencode adapter skeleton with capability/event tables build(opencode): adapter_translate_dispatcher (DISPATCHER.md → AGENTS.md) build(opencode): adapter_translate_references and adapter_translate_skills Implements Task 4 and Task 5: - adapter_translate_references: Copies reference markdown files to .opencode/references/ - adapter_translate_skills: Copies skill SKILL.md files to .opencode/skills/<name>/ with exclude filtering Both functions respect framework filtering via should_include(). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> build(opencode): adapter_translate_agents with capability→permission mapping Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> build(opencode): bash-executor template for spawning hook scripts build(opencode): plugin-stub template for mbifc-hooks.js build(opencode): adapter_translate_hooks with JS plugin generation Implements _oc_hook_registry_json and adapter_translate_hooks in the opencode adapter. Copies hook scripts to .opencode/hooks/, generates a single .opencode/plugins/mbifc-hooks.js by inlining bash-executor.js and synthesising a hook registry from *.hook.yaml files. Uses python3 for template substitution to safely handle multi-line JS content. Adds 3 unit tests (copies scripts, registry entries, noop when no hooks dir). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> build(opencode): adapter_translate_mcp with local/remote handling build(opencode): adapter_finalize and complete adapter_build wiring Add adapter_finalize placeholder and wire adapter_translate_mcp into adapter_build; add end-to-end integration test (14/14 pass). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> feat(launchme): branch on --framework for opencode install layout Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> feat(updateme): branch on --framework for opencode install layout Mirror the same case "$FRAMEWORK" block from launchme.sh: framework-specific DIST_COMPONENTS_DIR, VAULT_COMPONENTS_DIR, DISPATCHER_SRC/DST, MCP_SRC/DST, HAS_PLUGINS; conditional install_plugins; conditional install_settings; framework-aware vault-setup check; framework-neutral summary messages. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Fix adapters to follow the same template. fix: restore adapter_build() contract, revert function renames Both adapters now export adapter_build() and adapter_translate_*() as the uniform public contract. scripts/build.sh sources one adapter and calls adapter_build uniformly. Private helpers (_oc_*) and vocabulary tables (cc_capability_to_tools, oc_capability_to_permission, etc.) retain their prefixes. CC regression and OC unit tests all pass. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> fix(tests): restore test_oc_ prefix on adapter_build end-to-end test * Fix agent format in opencode adapter * refactor: rename --framework to --platform across all scripts and tests Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Modify generic name for model tiers Co-Authored-By: win0na <winnie@winneon.moe> refactor: neutral model vocabulary (low/mid/high) in source agents feat(claude-code): cc_model_to_native() maps low/mid/high to haiku/sonnet/opus Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> feat(opencode): update oc_model_to_provider() for low/mid/high vocabulary Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add gemini-cli adapter Co-Authored-By: win0na <winnie@winneon.moe> build(gemini-cli): adapter skeleton with capability/event/model tables build(gemini-cli): adapter_translate_dispatcher (DISPATCHER.md → GEMINI.md) build(gemini-cli): adapter_translate_references and adapter_translate_skills Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> build(gemini-cli): adapter_translate_agents with capability→tools mapping Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> build(gemini-cli): adapter_translate_hooks with wrapper scripts Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> feat(install): add gemini-cli platform to launchme.sh and updateme.sh Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Implement preserving config merge for opencode. Co-Authored-By: win0na <winnie@winneon.moe> feat(opencode): config-merge.sh with formatting-preserving JSON merge Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> build(opencode): source config-merge.sh from adapter Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> feat(install): use oc_config_merge for opencode.json instead of overwrite Source config-merge.sh from install scripts for opencode platform so user keys in opencode.json are preserved on reinstall and update. Fix in-place merge by writing to a temp file before moving to output. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * Add mcp files to gitignore. * Fix claude-specific references in agents, skills and references * Fix: remove claude-specific reference from hooks. build: add platform_dir and dispatcher_name to all hook wrapper/plugin templates feat(hooks): platform-aware path checks using platform_dir and dispatcher_name from JSON input test: update regression snapshot for platform-aware hook wrappers and scripts * Added interactive platform choice in launchme, and platform auto-detection in updateme. * Fix: remove claude-specific references from documentation * Update documentation to reflect the new platform-agnostic architecture * fix: address Copilot review feedback on PR #32 - tests/run.sh: check source return code, report failures - tests/regression/run.sh: use mktemp + trap cleanup instead of fixed /tmp paths - tests/regression/run.sh: include .mcp.json in regression comparison - tests/regression/take-snapshot.sh: use --platform flag instead of stale scripted input - adapters/opencode/templates/plugin-stub.js.tmpl: include stdout in hook block error message * fix: address Copilot review round 2 - config-merge.sh: reword comment to only promise indentation preservation (not full formatting) - take-snapshot.sh: copy required artifacts explicitly, optional ones with existence check - adapters/lib.sh: document parse_hook_yaml single-trigger limitation * fix: address Copilot review round 3 - adapters/opencode/adapter.sh: replace python3 template substitution with pure bash (while-read loop with case matching), removing python3 dependency - adapters/lib.sh: should_include now falls back to plain YAML key read for files without frontmatter delimiters (fixes hook .yaml exclude: support) * fix: address Copilot review round 4 - scripts/launchme.sh: fix double-dot in FW_DIR_NAME display (basename already includes the dot, e.g. ".claude") - scripts/launchme.sh: replace undefined MCP_ANSWER with check on MCP_DST existence for summary banner --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
9.8 KiB
Executable File
Getting Started with My Brain Is Full - Crew
A step-by-step guide for setting up your AI-powered vault. No technical background required.
What you need before starting
Required
- Obsidian: A free note-taking app. Download it at obsidian.md
- An agent platform: one of Claude Code (Pro/Max/Team), Gemini CLI, or OpenCode.
- An Obsidian vault: This is just a folder on your computer where Obsidian stores your notes. If you don't have one yet, Obsidian will create one for you when you first open it.
- Git: A tool to download the project. On Mac, the terminal will prompt you to install it automatically the first time you use it. On Windows, download it from git-scm.com.
Optional (but recommended)
- Gmail account: If you want the Postman agent to process your Gmail inbox (via GWS CLI or MCP)
- Hey.com account: If you use Hey for email (via Hey CLI) — works alongside or instead of Gmail
- Google Calendar: If you want calendar integration
Step 1: Install Obsidian
- Go to obsidian.md and download the app for your system (Mac, Windows, or Linux)
- Open Obsidian
- If this is your first time, click "Create new vault"
- Give it a name (e.g., "My Brain", "Second Brain", "Knowledge Base", whatever feels right)
- Choose where to save it on your computer
- Remember this location. You'll need it in Step 3
Install recommended plugins
Inside Obsidian:
- Go to Settings (gear icon, bottom left)
- Click Community plugins
- Click Browse
- Search for and install these plugins:
Essential (install these first):
| Plugin | What it does |
|---|---|
| Templater | Makes templates work with dynamic content (dates, etc.) |
| Dataview | Lets you query your notes like a database |
| Calendar | Visual calendar in the sidebar |
| Tasks | Better task management with due dates and queries |
Recommended (install when ready):
| Plugin | What it does |
|---|---|
| QuickAdd | Rapid note capture |
| Folder Notes | Index notes for folders |
| Tag Wrangler | Manage and rename tags in bulk |
| Periodic Notes | Weekly and monthly review notes |
| Omnisearch | Better search across your vault |
Don't worry if this feels like a lot. The Architect agent will remind you about missing plugins during setup.
Step 2: Install an agent platform
Install one of the following:
| Platform | Install | Subscription |
|---|---|---|
| Claude Code | claude.ai/code | Claude Pro, Max, or Team |
| Gemini CLI | github.com/google-gemini/gemini-cli | Google account |
| OpenCode | opencode.ai | Varies by provider |
Claude Code works as both CLI and Desktop app (Cowork). The Crew works on all supported platforms.
Step 3: Install the Crew
Open your terminal and navigate to your Obsidian vault folder:
cd /path/to/your-vault
Not sure how to open the terminal? On Mac, press
Command + Space, type "Terminal", and press Enter. On Windows, pressWindows + R, type "cmd", and press Enter.
Clone the repo inside your vault:
git clone https://github.com/gnekt/My-Brain-Is-Full-Crew.git
Run the installer:
cd My-Brain-Is-Full-Crew
bash scripts/launchme.sh
The script will ask a couple of questions:
- Which platform? Select your agent platform (Claude Code, Gemini CLI, or OpenCode)
- Is this your vault folder? Confirm or enter the correct path
When it's done, your vault will look like this (paths vary by platform):
your-vault/
├── .<platform>/ ← .claude/, .gemini/, .opencode/, or any platform dir that will be supported in the future
│ ├── agents/ ← 8 lightweight crew agents
│ ├── skills/ ← 14 specialized skills for complex flows
│ ├── hooks/ ← file protection and validation
│ └── references/ ← shared docs the agents read
├── CLAUDE.md / GEMINI.md / AGENTS.md / ... ← dispatcher (varies by platform)
├── My-Brain-Is-Full-Crew/ ← the repo (for future updates)
└── ... your Obsidian notes
Something went wrong? The most common issue is that
gitisn't installed. On Mac, the terminal will prompt you to install it automatically. On Windows, download it from git-scm.com. If you're stuck, just show this page to a tech-savvy friend. It takes 60 seconds.
Step 4: Connect your vault
- Open your agent platform (Claude Code, Gemini CLI, or OpenCode)
- Open it inside your Obsidian vault folder. This is important: the platform needs to be in your vault to read and write your notes.
If you're using a CLI tool:
cd /path/to/your-vault
claude # or: gemini, opencode
If you're using Claude Code Desktop (Cowork), open the vault folder as your working directory.
Step 5: Initialize your vault
This is the fun part. Just type:
"Initialize my vault"
The /onboarding skill will kick in and the Architect will start a friendly conversation with you. It will ask:
About you
- What should I call you?
- What's your preferred language?
- What do you do? (student, professional, creative, researcher...)
- What brought you here? (overwhelm, organization, health, productivity...)
About your vault
- Are you new to Obsidian, or migrating from an existing vault?
- Do you want all 8 agents, or just some?
- What areas of your life do you want to manage?
About integrations (optional)
- Do you want email triage? (requires Gmail via GWS/MCP, or Hey.com via Hey CLI)
- Do you want calendar integration? (requires Google Calendar via GWS/MCP)
After the conversation, the Architect creates your entire vault structure, saves your profile, and leaves you a personalized welcome note.
Agent memory (Post-it)
Every agent has a small "post-it" file in Meta/states/ where it jots down notes for its next run. This means agents remember what they did last time: the Sorter knows which files it already triaged, the Scribe remembers what you were brainstorming about, the Architect knows which onboarding step you were on if the conversation was interrupted.
You don't need to manage these files — agents handle them automatically. Each post-it is limited to 30 lines, so they never grow out of control.
Step 6: Start using it
From now on, you just talk to your agent. Here are some things to try on your first day:
Capture some thoughts
"Save this: I had an idea about reorganizing the team standup. Maybe we should do async updates on Mondays and only meet on Wednesdays"
The Scribe will turn this into a clean note in your inbox.
Dump several things at once
"Quick notes: need to call the dentist, also Marco mentioned a book called Thinking Fast and Slow, and I should review the Q3 budget before Friday"
The Scribe detects multiple items and creates separate notes for each.
Check your email
"Check my email for anything important"
The /email-triage skill scans your inbox (Gmail or Hey.com), saves actionable emails, and gives you a summary.
File everything
"Triage my inbox"
The /inbox-triage skill processes all notes in your inbox and files them to the right places.
Search your brain
"What do I know about the Henderson project?"
The Seeker searches your vault and synthesizes an answer with source citations.
Step 7: Build daily habits
The Crew works best with simple daily routines:
Morning (2 minutes)
"Check my calendar for today" to see what's ahead "Any messages from the crew?" to check if agents flagged anything
Throughout the day
Just dump thoughts as they come. The Scribe handles the rest.
Evening (5 minutes)
"Triage my inbox" to let the Sorter file everything
Weekly (10 minutes)
"Weekly review" to run the
/vault-auditskill for a full vault health check
Troubleshooting
"The agent doesn't seem to activate"
Make sure your agent platform is open inside your vault folder (not a different directory). Verify agent files exist in the platform's agents directory (e.g., .claude/agents/). Try saying the trigger phrase differently. Agents and skills understand natural language in multiple languages.
"Email/Calendar isn't working"
The Postman needs at least one email backend: GWS CLI (gws), Hey CLI (hey), or MCP connectors. For GWS, see docs/gws-setup-guide.md. For Hey, install from github.com/basecamp/hey-cli and run hey auth login. For MCP, run the installer again (bash scripts/launchme.sh) and answer yes to the Gmail/Calendar question, or manually copy .mcp.json from the repo to your vault root.
"My vault structure looks different from the docs"
The Architect customizes the structure based on your onboarding answers.
"How do I update to a new version?"
cd /path/to/your-vault/My-Brain-Is-Full-Crew
git pull
bash scripts/updateme.sh
Only changed files are updated. Your vault notes are never touched.
"An agent did something weird"
Open an issue on GitHub with:
- What you asked
- What happened
- What you expected
"I want to change my profile"
"Update my profile" and the Architect will help you modify your settings
Next steps
- Examples: See real-world usage scenarios
- Mobile Access: Use the Crew from your phone
- Meet the Agents: Deep-dive into each agent's capabilities
- Contributing: Help make the Crew better
Remember: the best organizational system is the one you actually use. Start small. Talk to your agent. Let the Crew handle the rest.