LLM visibility audit: brand mentions across AI engines, share of voice, citation gaps, recommendations.
Send & Communicate
/send-slack
Post results to Slack. Supports multiple named channels via SLACK_WEBHOOK_* env vars. Set once, use everywhere.
/send-discord
Post to a Discord channel via webhook. Set DISCORD_WEBHOOK_URL in .env — no bot setup needed.
/send-email
Send reports via email using Resend API. Free tier: 100 emails/day. Set RESEND_API_KEY + EMAIL_FROM in .env.
/send-circle
Post to a Circle community space. Set CIRCLE_API_KEY in .env. Confirms content before posting — no accidental publishes.
03 — SA MCP Modules
What the MCP Can Do
SearchAtlas MCP V2 — 12 active modules, hundreds of tools. OAuth 2.1 Use the search bar ⌘K to find any specific tool by name or intent.
Rate limit
30 API calls/minute. Batch operations count as 1 call — use otto_generate_bulk_recommendations, gbp_bulk_generate_posts, and cg_schedule_article_batch when processing multiple items.
JD Says
Don't memorize commands. Just describe what you want in plain English — Claude routes to the right command automatically. If you're not sure which slash command to use, ask Claude first.
04 — Intent Routing
Match Request → Command
When a user or client asks you something, route to the right command based on specificity.
Broad Requests
Vague → give full picture
"tell me about [client]" / "full report"/business-report
"show me my account"/my-account
"set up a new client"/onboard-client
Specific Lookups
Direct → just answer
"show me their keywords"organic → keywords
"check their backlinks"backlinks tools
"SEO health" / "pillar scores"holistic_audit
"content status" / "articles"content_retrieval
Action Requests
Intent → run workflow
"run SEO for [client]"/run-seo
"optimize their GBP"/run-gbp
"launch ads" / "set up PPC"/run-ppc
"create content"/run-content
"post to Slack / Discord"/send-*
05 — Ready-Made Workflows
6 Workflows
These run end-to-end via the SA MCP. Starting points, not scripts — mix steps across workflows as needed.
🔍
New Client SEO Onboarding
ONE-TIME
OTTO project setup
Site audit
Brand vault + voice
Keyword research
Topical map
First article batch
📅
Monthly SEO Maintenance
RECURRING
Apply OTTO suggestions
Deploy schemas
Fix indexing
Expand topical map
Generate articles
Grade content
📍
GBP Profile Optimization
ONE-TIME
AI recommendations
Fix categories
Add services
Set attributes
AI description
Deploy to Google
💬
GBP Monthly
RECURRING
Reply to reviews
Generate posts
Auto-posting setup
Performance report
🔗
Authority Building
AS NEEDED
Write press release
Distribute
Build cloud stack
Launch PR outreach
Monitor backlinks
🏗️
Website → CMS
PER PROJECT
Website Studio build
Claude Code refine
CMS MCP export
Webflow / WordPress
JD Says
These workflows are starting points, not scripts. Mix and match steps across workflows — Claude is smart enough to figure out the order. The best workflow is the one you actually run.
06 — Agency FAQ
Common Pain Points
The questions every agency asks in the first week.
Q 01
Do I need to know how to code?
No. Warp + natural language is enough. Type what you want, Claude handles the tool calls. Use /slash commands for repeatable workflows — no scripting required.
Q 02
Why is my token budget draining fast?
Claude reads files in loops. Add .claudeignore immediately (exclude node_modules/, .git/, logs, binaries). Run /compact at 65-70% context. Use /clear at 85% for a fresh start.
Q 03
A tool call failed — what do I do?
Read the error message. Parameter Validation Errors contain the correct schema inside them. Extract the expected parameters, then retry once with the correct call. Don't retry blindly.
Q 04
How do I keep CLAUDE.md effective?
Keep it under 150 lines. One fact per line — no long prose. Prune every 2 weeks. Client IDs belong in brand vault, not here. Dead rules waste context every session.
Q 05
How do I share results with clients?
Use /send-slack, /send-discord, /send-email, or /send-circle. All four integrations are pre-wired — just set webhook URLs in .env.
Q 06
Can I run workflows for multiple clients?
Yes. Every /run-* command asks which business to target first. Run /my-account at session start to get your full client list.
Q 07
What if Claude makes a decision it shouldn't?
It will ask before any destructive or irreversible action — publishing content, launching ads, sending comms. Never skip confirmations.
Q 08
How do I discover available tools?
SA MCP V2 exposes full schemas automatically. Use the search bar (⌘K) to find a tool by name or intent. If a tool behaves unexpectedly, call it with empty params {} first — the V2 response includes the correct schema inline.
07 — Non-Negotiables
Six Golden Rules
Break any of these and you'll waste time debugging avoidable problems.
01
Schema Discovery First
Before calling ANY tool for the first time, call it with {} to discover the real schema. Documentation may be outdated — the API response is authoritative.
02
Read Error Messages
Parameter Validation Errors contain the correct schema. Don't retry blindly — read the error, extract correct params, retry once.
03
Poll Async Tasks
Many operations return a task ID, not results. Poll with get_otto_task_status until status = SUCCESS. Never assume completion because it returned.
04
Watch for Tool Name Collisions
Short names can resolve to the wrong tool. Try the full prefixed name — e.g., otto_project_management instead of project_management.
05
Never Hardcode IDs
Project IDs, location IDs, business IDs — always discover via API. Run /my-account first. Hardcoded IDs break silently.
06
Never Expose Secrets
API keys live in .env only. Never print them. Add .env* to both .claudeignore and .gitignore immediately.
JD Says
Golden Rule #1 trips everyone up the first time. Always call a tool with empty params {} before passing real data. The schema — and the fix — is always in the error response.
Agentic Marketing Mastermind
The AI Toolkit for AMM Members
Run complete SEO, GBP, PPC, and content workflows from your terminal. One command, fully automated — powered by the SearchAtlas MCP.
SEARCH/ATLAS
Cohort Member Resource
60+MCP Tools
12SA Modules
15Commands
6Workflows
OAuth 2.1 One-click auth
Works with Claude Code, Cursor, Windsurf, Warp
Streamable HTTP — real-time MCP
AMM Members-only access
Automatic Setup
One Command. Fully Wired.
Paste one line into your terminal. The quickstart script handles everything — no manual installs, no config files.
Builds ~/YourAgency-AMM/ with AMM-SA/ (toolkit) and clients/ (one folder per client) pre-structured.
⚙️
Installs dependencies
Detects what's missing and installs Git, Node.js, and Claude Code automatically. Nothing to chase down manually.
🔌
Connects SearchAtlas MCP
Wires Claude Code to the SearchAtlas MCP at mcp.searchatlas.com/mcp via OAuth 2.1 — no API key to copy-paste.
⌨
Detects your IDE
Scans for Cursor, Warp, Windsurf, VS Code, and iTerm2. Recommends the best one already installed.
◆
Installs slash commands
Clones the AMM-SA toolkit and installs all 13 agency slash commands so they're ready in your first session.
📄
Drops in CLAUDE.md
Places a workspace-level CLAUDE.md at the root so Claude understands your full setup from the very first message.
Resulting workspace structure
~/YourAgency-AMM/├── AMM-SA/← this toolkit (auto-cloned)│ ├── commands/← 13 slash commands│ ├── workflows/← YAML workflow templates│ └── CLAUDE.md← toolkit context for Claude└── clients/← one subfolder per client └── acme-corp/ ├── CLAUDE.md← client context + linked IDs └── brand-profile.md
JD Says
The quickstart script is idempotent — safe to re-run if anything looks off. It won't overwrite existing client files or workspace settings.
Workspace Structure
Your folder is your memory system.
Every file has a specific job. Click any file or folder in the tree to learn what goes inside it, best practices, and how to have Claude build it for you.
EXPLORER
← click any file or folder
📁
Click any file or folder in the tree to see what it does, what to include, and how to create it.
After Setup
First Launch
Open your workspace in Warp or VS Code, then start Claude Code.
Step 2
Open the workspace & start Claude
# Navigate to your workspacecd ~/YourAgency-AMM/AMM-SA# Start Claude Codeclaude
Step 3
Set permissions & verify
# Inside Claude Code:/permissions← select "Bypass"/my-account← should list your SA projects
Why bypass?
Agency workflows call dozens of SearchAtlas tools in sequence. Without bypass you'd manually approve every single tool call — Bypass lets workflows run end-to-end.
Step 08 — Client Onboarding
Onboard Your First Client
Run /onboard-client inside Claude Code. The wizard picks the right path automatically.
Path A — Existing Client in SearchAtlas
Claude runs 4 parallel brand vault calls to pull everything automatically — name, domain, phone, address, hours, colors, logo, brand voice, knowledge graph, competitors, and all linked IDs (OTTO, GBP, PPC). Displays a confirmation block before creating any files.
What gets pulled:
Business info + contact details
Brand voice + knowledge graph entities
OTTO project ID + GBP location ID
PPC account + competitor list
Path B — New Client
17-field guided form. Claude collects business info, contact details, voice profile, and seeded knowledge graph entities — then immediately pushes everything into a new Brand Vault.
What gets created:
New Brand Vault with all fields populated
OTTO project linked to domain
clients/{slug}/CLAUDE.md — session context
clients/{slug}/brand-profile.md — full brand data
Auto-Sync
After onboarding, the client CLAUDE.md includes an Auto-Sync block. At session start, Claude silently runs a 4-call brand vault pull and updates brand-profile.md if anything changed. At session end, it diffs and pushes local additions back to SearchAtlas.
JD Says
When in doubt, use Path A — pull from SearchAtlas first. Existing vault data always beats a blank form. Run Path B only for net-new clients who aren't in SA yet.
Agency Memory
CLAUDE.md Starter Template
Copy, edit, save. This is your agency's permanent AI memory — tailor every field to you. Keep it under 150 lines.
# Agency: [Name] | Claude Code Manual## Who I Am
You assist [Name], owner of [Agency].
Non-technical. Prefer bullet points
and confirmation before any action.
## SearchAtlas Products in UseOTTO: SEO project management
GBP: Google Business management
KRT: Keyword research + entity mapping
Studio: Website Studio for client sites
## My Clients
Acme Corp | acme.com | Local SEO
TechStart | techstart.io | B2B SaaS
## Non-Negotiable Rules- Never publish without approval- Never assume IDs — look up first- /clear between every client session- Save reports to /reports/[client]/[month]/
JD Says
Edit this template before your first real client. The more specific your CLAUDE.md is, the less you have to repeat yourself. Keep it under 150 lines — dead rules waste context every session.
Every file has a specific job. Click any file or folder in the tree to learn what goes inside it, best practices, and how to have Claude build it for you.
EXPLORER
← click any file or folder
📁
Click any file or folder in the tree to see what it does, what to include, and how to create it.
02 — Skill Files
Your SOPs, encoded. Your AI, consistent.
Skill files are markdown documents that tell Claude exactly how to run your agency's repeatable workflows — written once, invoked on demand, consistent every time. Tap a card to expand.
Paste your best GPT system prompts into Claude and say "Convert this into a skill file." Claude formats it with invocation syntax automatically. Five years of prompt refinement — migrated in five minutes.
Research
Keyword Research
Seed extraction, intent clustering, entity gap analysis, KRT validation.
↓ expand
Pulls seed keywords from the brand vault, classifies search intent, identifies entity gaps vs competitors, and validates the final list against KRT data. Produces a structured keyword map ready for the site architecture skill.
Builds a structured entity map for a given topic cluster, identifies which entities the client is missing vs. competitors, and produces a priority page-creation list ready for the build workflow.
use skill entity-mapping for [topic]
CRO
CRO Audit
Evaluate CTAs, trust signals, heading hierarchy, and conversion blockers.
↓ expand
Systematically reviews a page for conversion rate weaknesses: CTA placement, trust signal gaps, heading hierarchy, friction points, and mobile experience. Returns a prioritized fix list.
use skill cro-audit for [page URL]
Content
Brand Voice
Apply this client's exact tone, vocabulary, and stylistic rules to any content.
↓ expand
Encodes the client's approved vocabulary, forbidden words, tone spectrum, and sample sentences. Any content Claude generates is automatically filtered through this guide — ensuring the output sounds like the client, not Claude's defaults.
use skill brand-voice for [client]
Build
Site Architecture
Define silo structure, URL patterns, internal link strategy, and page hierarchy.
↓ expand
Generates a complete site architecture plan from the keyword map — silo structure, URL slugs, internal link anchors, and which pages link to which. Output is ready to feed directly into Website Studio.
use skill site-architecture for [client]
Reporting
Client Report
Monthly reporting structure, KPI definitions, and executive summary format.
↓ expand
Applies a consistent reporting structure — pulls ranking movement, traffic changes, and goal completions, then writes executive commentary in the client's preferred reading level. Consistent output, every month.
use skill client-report for [month]
03 — Build Workflows
Three workflows proven in the field.
Step through each workflow. Every site build, client revision, and recovery follows one of these three patterns.
🏗️ Website Studio Build
🎤️ Verbal Feedback
🔧 Site Recovery
1
Invoke the Search Atlas MCP tool
Open or create the client site in Website Studio via the MCP connection. Claude loads the client CLAUDE.md — brand, audience, and campaign goals are already in context before a single word is generated.
2
Claude orchestrates the full build
Claude calls the MCP to generate pages, applies your site-architecture skill for structure, injects brand-voice content, and signals OTTO SEO to run checks as pages are created — all without switching tools.
3
Review and publish inside the platform
Changes live directly in Website Studio. Review, approve, and publish without leaving Search Atlas. No separate deployment step, no manual file management, no broken handoffs.
Starter prompt
Using the Search Atlas MCP, open [client] in Website Studio. Use the site-architecture and brand-voice skills. Build [page type] for [service] targeting [location/audience].
Why Website Studio? Changes are version-controlled inside Search Atlas, integrated with OTTO SEO for instant optimization checks, and deployable in one click. Building outside the platform loses all of that.
1
Client records their feedback verbally
A voice memo, a Loom, a voice note. No long emails, no back-and-forth. They just talk through what they want changed — in their own words, unfiltered and unedited.
2
Transcribe and paste — raw, no interpretation
Include the transcript plus the current version of the content. No summarizing. No paraphrasing. Raw transcript in, exact changes out. Claude does the interpretation — not you.
3
Claude makes exactly the requested changes
Not its own interpretation. Not extra improvements. Precisely what the client said. Review and send. Even picky clients approve this — because it reflects their exact words back to them.
Starter prompt
Here is my client's verbal feedback: [raw transcript]. Here is the current content: [paste]. Make exactly the changes they described — nothing more, nothing less.
Why this works: Clients reject revisions when they feel unheard. When Claude returns their exact words as edits, approval rates jump dramatically. The transcript is the brief.
1
Don't rebuild — diagnose first
Paste the broken code into Claude Code and ask it to inspect before doing anything. Describe what is and isn't working. Rebuilding from scratch discards working code and doubles your time.
2
Ask "What is broken and why?" — not "Fix it."
A diagnosis before a fix prevents Claude from generating changes that break things that were working. Once you understand the root cause, the fix is usually three lines — not a full rewrite.
3
One fix at a time — confirm each before moving on
Review and confirm each change before the next. Batch fixes are harder to debug if something still doesn't work. One change → test → confirm → next.
Starter prompt
Here is my site code: [paste]. The following is broken: [describe]. Please inspect and explain what's wrong before making any changes.
Rule of thumb: If Claude asks "Should I fix it?" — say no and ask for the diagnosis first. The extra 30 seconds saves 30 minutes of debugging a fix that introduced new problems.
04 — Tool Architecture
Three tools. Three jobs. Zero overlap.
Claude Code orchestrates. Search Atlas MCP executes. Claude.ai thinks. They work together — not in competition. Using the wrong layer for the task loses each platform's built-in advantages.
Claude CodeOrchestration layer
Search Atlas MCPExecution layer
Claude.aiThinking layer
🧠
Memory management
Reads and updates AI_rules.md, client CLAUDE.md files, skill files, and MEMORY.md. Persistent context across every session.
⚙️
Skill invocation
Skills live in your file system. Claude Code reads and applies them to every task automatically when triggered.
🔄
Multi-step workflows
Sequences that read files, call tools, check results, and iterate — all in one session without losing context.
🔌
MCP orchestration
The control layer that calls Search Atlas, Linear, Slack, Playwright — coordinating tools into complete workflows.
📦
Batch pipelines
Loop over city lists, run sequential builds, manage verification across multiple pages or clients at once.
📁
File system access
Reads, writes, and edits your actual files. The only layer that can manage your full agency folder structure.
🏗️
Website Studio
Create, edit, and publish pages inside Search Atlas — version-controlled, OTTO-integrated, one-click deploy. Never build outside the platform.
🔍
OTTO SEO
Audit management, technical fixes, schema markup, indexing — runs as Claude builds. Real-time SEO as you create.
✍️
Content Genius
AI-assisted content generation, topical maps, and DKN — structured content that feeds directly into Website Studio.
🔑
Keyword Research (KRT)
Entity mapping, competitor keyword gaps, SERP analysis — the research layer that informs every build plan.
📍
GBP Management
Google Business Profile publishing, review management, post automation, citation building — all from one MCP connection.
📊
Site Explorer
Backlink analysis, brand signals, competitive keyword gaps, holistic site audit — full platform coverage.
🔎
Research & analysis
Quick web search, document summarization, competitive research — fast and conversational, no file context needed.
✏️
First-draft writing
Blog posts, email copy, ad headlines, social captions — standalone writing tasks where speed matters more than file integration.
💡
Brainstorming
Campaign concepts, naming options, strategic angles — exploratory thinking where you want speed and volume over precision.
🗣️
Client-facing explanations
Plain-language explanations, executive overviews, summaries. Use Projects to give it persistent brand context.
⚡
Quick Q&A
On-demand questions that don't require file access or tool orchestration — fast answers without any setup.
🧪
Strategy testing
Think through approaches, stress-test plans, pressure-check briefs before committing them to a workflow.
05 — Scaling Patterns
From 1 page to 500 — same workflow.
Four tiers of automation. Two available today, one near, one in development. Click each to see what powers it.
Tier 1 · Available Now
Batch Pages via Website Studio MCP
One city list, one service type, one skill invocation. Pages generated with OTTO checking each one as it builds.
Consistent heading hierarchy, keyword placement, and internal links — across 10, 50, or 500 locations. No manual copying between tools. OTTO validates each page before publish.
city list→SA MCP→Website Studio→OTTO check→publish
Tier 2 · Available Now
Onboarding → Full SA Workflow
Intake answers in, complete build plan out. Content Genius + KRT + Website Studio — all in one Claude Code session.
Intake feeds Content Genius research, KRT entity mapping defines page targets, then a Website Studio build plan is ready for approval before a single page is created.
intake→Content Genius→KRT entity map→Website Studio plan
Tier 3 · Near Future
Email → Site Update, No Human Layer
Client emails a change request. Claude parses it, updates via Website Studio MCP, confirms back. Zero interpretation required.
For agencies managing hundreds of live sites, eliminating the human interpretation layer between "client request" and "site update" is a business-level transformation.
client email→Claude parses→Website Studio→confirmation sent
Tier 4 · In Development
Full Overnight Site Build
Search Atlas already has pre-built workflow templates for GBP, PPC, and SEO onboarding. Full overnight builds are next.
Onboard a client before you leave for the day. Wake up to a complete, OTTO-validated, review-ready site. The natural extension of the SA workflow templates already in production.
Six failure patterns that show up consistently — and the specific fix for each. Tap to expand.
🧊
Cold-start syndrome
▼
Every Claude session opens with zero memory. Without your AI_rules.md and CLAUDE.md files in place, you re-explain your world every single time — and results drift depending on what you happen to mention that day.
Fix: Build your AI_rules.md and project CLAUDE.md before starting any real work. Ten minutes of setup saves hours of repeated explanation across every future session.
📂
The silent misroute
▼
Claude says "done." You look for the file and it's not where you expected. No error, no warning — just the wrong folder. Happens every time you open Claude Code without confirming the working directory.
Fix: Before every build session, ask: "What is the current working directory?" Confirm it matches your client folder before generating anything.
📝
Only using one level of CLAUDE.md
▼
Root-only means every client gets the same output — no differentiation. Client-only means Claude has no agency baseline and loses your standards the moment context resets. Both levels running together are required.
Fix: Root AI_rules.md in your agency folder sets the baseline. Client CLAUDE.md in every client subfolder adds the specifics. Never operate with just one.
🎯
Generic prompts produce generic output
▼
The less specific your input, the more Claude falls back on generic patterns. "Write a page about our plumbing services" produces a page that sounds like every other plumbing page on the internet — because Claude has nothing else to work from.
Fix: Your skill files and CLAUDE.md exist to close this gap. The more specific those files are, the more distinctive the output — Claude applies your standards, not its defaults.
🔌
Building site pages outside Search Atlas
▼
Building sites outside Website Studio means losing version control, OTTO integration, one-click publish, and pre-built workflow templates. You trade ten minutes of platform setup for hours of manual work downstream on every project.
Fix: Use Website Studio via the Search Atlas MCP for all site creation and editing. That's what it's built for — use it consistently.
🌊
Treating skill files as a one-time setup
▼
Skill files are living documents. If your keyword research process improves, the skill file should improve. If a client changes their brand voice, update the file. Stale skills produce stale, consistent-in-the-wrong-way output.
Fix: Review each skill file when the underlying process changes. Treat them the same way you'd treat a team onboarding doc — always current, always specific.
Agency Memory
CLAUDE.md Starter Template
Copy, edit, save. This is your agency's permanent AI memory — tailor every field to you.
# Agency: [Name] | Claude Code Manual## Who I Am
You assist [Name], owner of [Agency],
a digital marketing agency. I am
non-technical. I prefer bullet points
and confirmation before any action.
## My PreferencesTone: Professional, direct, client-safe
Reports: Executive summary, wins first
Actions: Always confirm before publishing
## My Clients
Acme Corp | acme.com | Local SEO
TechStart | techstart.io | B2B SaaS
## Tools (preferred order)
1. Search Atlas — SEO/GBP/content
2. ClickUp — tasks & time tracking
3. Google Calendar — scheduling
4. Slack — team + client updates
## Non-Negotiable Rules- Never publish without approval- Never assume IDs — look up first- Save to /reports/[client]/[month]/- /clear between every client session
Detailed Workflows
Step-by-Step Execution
Each workflow has strict step dependencies. Skipping steps causes "missing ID" errors downstream.
🔍 SEO Onboarding — /run-seo
1. Create OTTO Project for client domain 2. Create Site Audit (needs project_id) 3. Get Pillar Scores (needs audit) 4. Create Brand Vault (parallel with 5) 5. Keyword Research (parallel with 4) 6. Create Topical Map (needs step 5) 7. Generate Articles (needs brand_vault + topical_map)
Generate max 4 articles per session. Content gen takes 3-8 min per article.
📈 PPC Launch — /run-ppc
1. Create & Validate Business 2. Generate Products from Landing Pages 3. Validate URLs & Approve Products 4. Bulk Create Keyword Clusters (async — poll) 5. Send to Google Ads (confirm first) 6. Activate Campaigns (confirm — spending starts)
Keyword clustering can take 2-5 min. New campaigns take 24-48h for Google review.
📍 GBP Optimization — /run-gbp
1. Load Location — sync from Google 2. AI Recommendations 3. Fix Categories (parallel with 4 & 5) 4. Add Services (parallel with 3 & 5) 5. Add Attributes (parallel with 3 & 4) 6. Deploy to Google (confirm first!)
Location must be verified on Google before deploying.
Operations marked async return a task_id. Claude polls every 5-10s until SUCCESS. Don't cancel unless 15+ minutes.
Subscriptions
What You Need
🧠Claude AIPro $20 / Max $100
Claude Code requires an active subscription. Pro covers personal use. Max recommended for agency workloads — higher rate limits and extended context.
🔍SearchAtlasRequired
An active SearchAtlas plan is required for MCP tools. After subscribing, generate your key at Settings → API Keys.
SearchAtlas · AMM
Research Agent
A scheduled agent that reads your vault, runs 4 analytical lenses, and writes insights automatically.
Agent Loop
The Intelligence Loop
Three agents running in sequence. Each feeds the next — compounding intelligence over time.
Research PipelineAnimated
watch the data flow between agents
Quickstart Guide
Research Agent + Obsidian + Claude Hook
A two-stage intelligence loop that reads your vault, surfaces blind spots, researches actionable topics, and auto-captures Claude session activity — all writing back into Obsidian.
macOS • Python 3.10+ • Claude Code CLI
1
What This Is
Three components turn your Obsidian vault into a passive intelligence engine:
Component
What It Does
When
Insight Agent
Reads vault context (voice notes, project docs, git history). Runs 4 analytical lenses through Claude to surface blind spots.
Scheduled / manual
Research Agent
Picks top 3 topics from insights, queries Gemini for live data, synthesizes with Claude, writes HTML reports.
After insight agent
Session Hook
Claude Code SessionEnd hook. Captures git state and writes a session log to the vault.
Every Claude exit
The compounding effect
Each agent reads previous outputs. Over time, the system gets smarter about your blind spots.
2
How It Works
YOUR DAILY WORK
|
v
Claude Code Sessions ---SessionEnd Hook---> Obsidian Vault
| |
| Voice Notes (Wispr) -----sync-----> |
| Team Chat (ClickUp) ----sync-----> |
| Git Repos (.planning/) -symlink---> |
| v
| STAGE 1: Insight Agent
| reads vault context
| runs 4 analytical lenses
| writes to Insights/
| |
| v
| STAGE 2: Research Agent
| picks top 3 topics
| Gemini for live data
| Claude for synthesis
| writes to Research/
| |
+------ feeds back into next run <-----+
JD Says
The research agent is persistent — it runs on a schedule and builds context you never have to explain again. Set it up once and it compounds every session.
3
Bootstrap Setup
# Set your pathsVAULT="$HOME/Documents/My Vault"ENV_FILE="$HOME/.env"# Create vault directoriesmkdir -p "$VAULT"/{Scripts,Insights,Research,Live,Wispr}
# Install Python dependenciespip install anthropic python-dotenv google-generativeai markdown
# Create .env if neededcat > "$ENV_FILE" <<'EOF'
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
EOF
# Create Claude hooks directorymkdir -p ~/.claude/hooks
Prerequisites: Obsidian (any version), Claude Code CLI, Python 3.10+, git, API keys (Anthropic + Gemini, billing-enabled)
4
Configure the Intelligence Agents
Place 4 files in $VAULT/Scripts/:
Scripts/
vault_report.py ← shared HTML renderer
insight-agent.py ← Stage 1: pattern detection
research-agent.py ← Stage 2: deep investigation
run-insight.sh ← wrapper for scheduled runs
Claude Code fires shell commands on lifecycle events. The command receives hook context as JSON on stdin. async: true means it runs in the background.
6
Wire Up CLAUDE.md
Minimum viable CLAUDE.md for the intelligence loop:
# My CLAUDE.md## Credentials
All API keys live in `/path/to/.env`. Load via python-dotenv, never source.
## Git Rules
Commit messages: `feat:`/`fix:`/`docs:` prefix.
## Workflow
Use `.planning/` directories (PROJECT.md, STATE.md, ROADMAP.md)
for all structured work. These files are read by external
analysis agents to track project health.
The CLAUDE.md closes the loop
Without it, Claude sessions produce unstructured output. With it, every session generates .planning/ artifacts that feed back into the insight agent.
7
Schedule & Run
# Dry run (preview, no API calls)python3 "$VAULT/Scripts/insight-agent.py" --dry-run
# Run a specific lensbash "$VAULT/Scripts/run-insight.sh" --lens blind-spots
# Run research agent standalonepython3 "$VAULT/Scripts/research-agent.py"
# Research a specific topicpython3 "$VAULT/Scripts/research-agent.py" --topic "LLM cost optimization"
What
Where
Format
Insight reports
$VAULT/Insights/2026-04-13-blind-spots.html
Standalone HTML
Research reports
$VAULT/Research/2026-04-13-topic-slug.html
Standalone HTML
Session logs
$VAULT/projects/repo-name.md
Markdown
Suggested schedule
Daily 9 PM for blind-spots. Mon + Thu 8 AM for weekly (auto-triggers research agent). Use macOS launchd for automation.
8
Troubleshooting
Problem
Fix
"ANTHROPIC_API_KEY not set"
Edit ENV_FILE path at the top of insight-agent.py and research-agent.py
Gemini returns empty / "QuotaError"
Check GEMINI_API_KEY is billing-enabled. Agent auto-falls back to Claude.
Session hook doesn't fire
Check ~/.claude/settings.json has the SessionEnd entry. Test: echo '{"cwd":"/tmp"}' | python3 ~/.claude/hooks/obsidian-session-capture.py
Launchd job not running
launchctl list | grep vault. Check /tmp/insight-agent-stderr.log
.planning/ symlinks not reading
ls -la "$VAULT/Live/" — check symlinks resolve. Ensure Terminal has disk access.
ESC
Start typing to search across all sections...
SearchAtlas · AMM
Resources & Sessions
Session archive, guides, and every link you need — all in one place.
01 — Sessions
Session Archive
Every recorded session — weekly calls, monthly deep-dives, and 1-on-1 setups.
JD Says
If you only watch one session, watch the most recent weekly call first. The pattern clicks faster when you see it in action than when you read about it.
Reference docs, visual breakdowns, and setup walkthroughs.
🚀
Onboarding
Setup & Client Guide
Tool install, MCP config, and full client onboarding wizard walkthrough.
Open →
🔄
MCP V2 Update
SA MCP V2 Changes
What changed in SA MCP V2. New tools, deprecated patterns, migration notes.
▼ Read more
What’s New
V2 expanded the SA MCP to 300+ tools across 12 modules. Every module now has dedicated CRUD, retrieval, and async task operations. Schema discovery is required before first use — tool names and parameter shapes changed from V1.
Key Changes vs V1
300+ tools (was ~50)OAuth 2.1 auth (no API key)Async task polling requiredbrand_vault split from project_managementgbp_locations_crud vs gbp_locationsSeparate CRUD + read-only tools per module
Migration Notes
If you used short tool names from V1 (e.g. project_management), these may now resolve to content project ops instead of OTTO ops. Always call with params: {} first to verify the schema. Full module list is in the Commands & Workflows tab.
Install Command
claude mcp add searchatlas --type http https://mcp.searchatlas.com/mcp
🧠
4 Core Skills
The Agentic Framework
The 4 skills every AMM member builds across the program.
▼ Read more
01 — Skills / SOPs
Build reusable procedures for every repeatable task. A skill is a prompt + context + expected output format saved as a CLAUDE.md command. SOPs turn one-off wins into team systems.
02 — Systems / Automation
Connect your tools so work happens without you initiating it. LaunchAgents, cron jobs, pipeline scripts, and MCP integrations that trigger on data, not on your attention.
03 — Scale / Speed
Multi-agent swarms, parallel task execution, and subagent delegation. The goal: one agent orchestrates, many agents execute. Hours of manual work become minutes.
04 — SearchAtlas Mastery
Deep fluency with OTTO, Brand Vault, GBP, PPC, Content, and LLM Visibility modules via MCP. Not clicking the UI — running workflows agentically and letting Claude chain the steps.
Why This Order
Skills before systems: you can’t automate what you haven’t nailed manually. Systems before scale: one working pipeline beats ten half-built ones. SA mastery runs in parallel throughout — it compounds every other skill.
📋
Cheat Sheet
Quick Reference
The most useful rules to have open during any session.
▼ Read more
Context Management
/compact at 65% usage — compresses history, keeps cache warm
/clear at 85% usage — fresh context, cost reset
Subagents: Haiku = search/validate • Sonnet = implement/analyze • Opus = architecture only
CLAUDE.md Rules
Every project folder needs a CLAUDE.md at the root — it’s Claude’s session brief. Include client name, domain, brand voice, linked IDs.
Put your global rules in ~/.claude/CLAUDE.md. They apply to every session automatically.
Keep CLAUDE.md under 500 lines. After that Claude stops reading it reliably.
SA MCP Quick Ref
Always call a new tool with empty params {} first — the response shows you the real schema
Async tasks return a task ID — poll with get_otto_task_status until status = SUCCESS
Never hardcode IDs — always discover via API (/my-account → then proceed)
401 error = OAuth expired. Restart Claude Code and re-authorize.
Common Failure Patterns
Push failing? Check your folder path first — #1 root cause across the cohort
Output generic? Role-frame Claude: “You are a [domain expert] providing [output] for [client].”
Tool misbehaving? Try the full prefixed name (otto_project_management, not project_management)
Session drift? Have Claude review the session log and update memory before closing
🗺️
AI Brain Architecture
Brain Diagram
Diagram of the full AI agency brain — memory layers, routing, MCP topology.
Explore →
🧸
Swarm System
Multi-Agent Architecture
How multi-agent swarms work in the AMM stack. When to use vs single agent.
▼ Read more
Single Agent vs Swarm
Single agent: One task, one context, sequential steps. Best for focused client work, content writing, or anything under ~30 min.
Swarm: One orchestrator + many specialist workers running in parallel. Best for large audits, multi-site builds, or workflows with independent branches.
Architecture
The orchestrator breaks the goal into subtasks and dispatches workers. Workers report back. Orchestrator synthesizes and decides next steps.
How to wire persistent memory into Claude so it gets smarter every session.
System Architecture
Wire a Persistent Brain Into Your AI Workflow
How to give your AI agent memory that compounds across sessions — the full loop from terminal to vault to review and back.
Memory Graph
Live Knowledge Map
Drag nodes to explore. Every connection reflects a real link in the vault — the same graph Obsidian renders from your memory files.
Vault GraphInteractive
drag to rearrange • hover to highlight connections
The Core Loop
Memory is a cycle, not a database
Every session feeds the next. Work creates context, hooks capture it, the vault stores it, a reviewer finds gaps, and the next session starts smarter.
⌨
1. Work
You work in your terminal with your AI agent. Every coding session, conversation, and decision is a potential memory. The session starts with full brain context loaded.
⚡
2. Capture
Hooks fire automatically on events: session start, file edits, compaction, session end. They extract context and write structured markdown. Zero manual effort.
📁
3. Store
Obsidian vault holds everything as .md files with YAML frontmatter. Symlinked so the AI reads it natively — writes from either side appear in both.
📑
4. Index
MEMORY.md is the master index. The AI loads this first every session. Auto-trigger rules here route work to the right skill automatically.
🔍
5. Review
A blind-spot agent runs on session start or via cron. It crawls the vault, checks for stale clients, missed follow-ups, contradictions, and coverage gaps.
✨
6. Generate
The reviewer writes new memory files for discovered patterns, fixes broken links, updates stale entries. The index gets updated. The loop closes — ready for next session.
System Layers
What lives where
Seven layers, each with a clear job. Every layer talks to the ones above and below it.
01 · Work
⌨
Work Layer
Where you actually do the work.
Warp / TerminalClaude Code CLIIDE (Cursor / VS Code)
From the moment you open your terminal to the blind-spot review the next day.
Session Start
Brain loads automatically
A SessionStart hook fires. It reads MEMORY.md and injects it as context. A second hook checks if today's blind-spot review exists. The AI starts with full context from every previous session.
During Work
Guards and monitors run silently
PreToolUse guards sensitive paths. When context gets large, PreCompact preserves critical state and PostCompact re-injects the brain after compression. CLAUDE.md defines the rules the AI follows throughout.
Session End
Memory capture is enforced
A Stop hook forces the AI to write memories: new bugs, API gotchas, feedback, routing rules. The AI cannot skip this. CLAUDE.md defines exactly what to update — client files, dates, next actions, index.
Daily Review
Blind-spot agent crawls the vault
Triggered on session start or via scheduled job. Reads every client file: flags contacts stale > 14 days, deliverables > 30 days, overdue actions, revenue concentration > 30%, empty pipeline stages. Writes a daily report.
Generate
New memories and suggestions written
The reviewer writes new .md files for discovered patterns, fixes broken links, updates stale entries. MEMORY.md gets updated with pointers to new files. Everything is ready for the next session.
Next Session
Loop closes — smarter than yesterday
The SessionStart hook loads the updated vault including everything the reviewer found. The AI knows about blind spots without you telling it. Compound intelligence.
JD Says
Most teams treat their AI like a fresh hire every single session. Memory changes that. It’s the difference between a tool you train and one that trains itself.
The Protocol File
CLAUDE.md makes it all stick
Hooks fire shell scripts. CLAUDE.md tells the AI what those hooks mean and what to do about it. Without this file, the hooks are noise. With it, every session follows the same protocol.
Session Start Protocol
Read MEMORY.md. Check if today's blind-spot review exists. Load the relevant client file if working on a specific client. All defined in one file.
Session End Protocol
Update any client files touched. Save learnings to memory/ with proper frontmatter. Update MEMORY.md. Commit and push if git remote exists.
Memory File Format
Every file needs YAML frontmatter: name, description, type. Body includes a Why line and a How to apply line so the AI can judge edge cases.
Session Capture
Paste session notes → extract action items to client files, save learnings to memory, create a session record, update the index. One paste, everything routed.
The Nervous System
Hooks are the synapses
Shell scripts in settings.json that fire on Claude Code lifecycle events. They run automatically — zero manual effort.
Guards before writes. Protect sensitive paths, block .env edits.
PostToolUse
After every tool call. Monitor token usage, trigger compaction.
PreCompact
Before compression — inject what to preserve: task, paths, decisions.
PostCompact
After compression wipes context — re-inject the brain. Same as SessionStart.
Stop
Mandatory memory-write enforcer. AI cannot close without documenting.
The Vault
Anatomy of a memory file
Every memory is a markdown file with YAML frontmatter. Five types, each with a clear purpose.
_brain/memory/feedback-deploy-rule.md
---name: Deploy Ruledescription: Every commit must push immediatelytype: feedback---
Every git commit must be immediately followed by git push.
Hosting deploys from the remote only — commit without push = nothing deployed.
**Why:**Discovered when a deploy was "done" but nothing went live.**How to apply:**After every commit, push. No exceptions.
The AI should never say "done" until the push succeeds.
Feedback
Corrections and confirmed approaches. "Do this" / "Don't do that" with reasoning. Record both mistakes and validated wins.
Project
Active work context: who, what, why, when. Decisions, blockers, architecture. Decays fast — include Why so future-you can judge.
User
Your role, expertise, preferences, schedule. Calibrates how the AI communicates with you and what it assumes.
Reference
Pointers to external systems: "bugs tracked in Linear", "API docs at X". Saves time finding things outside the vault.
Auto-Trigger
Rules in MEMORY.md that auto-invoke skills: "any frontend task → use design skill first." The AI self-routes.
Run It
One prompt. Everything wired.
The setup prompt handles all 12 phases automatically. It audits what you have, only creates what's missing, wires the sync, installs the hooks, and runs the first blind-spot review.
3 Steps
1
Open Claude Code in your project directory
cd ~/your-agency-folder && claude
2
Copy the setup prompt
Click the button below — the full prompt is copied to your clipboard.
3
Paste into Claude Code and follow along
Claude walks you through each phase. It asks before making changes.
Setup Prompt — 12 phases
Phase 1:Audit what exists— vault, markdown, CLAUDE.md, hooks, symlink, gitPhase 2:Vault structure— memory/ maps/ workflows/ sessions/ daily/Phase 3:MEMORY.md— master index, auto-triggers, under 200 linesPhase 4:CLAUDE.md protocol— session start/end, memory format, capture rulesPhase 5:Hook layer— SessionStart, Stop, PreCompact, PostCompact, PreToolUsePhase 6:Memory symlink— Obsidian ↔ Claude share same filesPhase 7:Index content— orphan files linked into MEMORY.mdPhase 8:Frontmatter check— all vault files have name + typePhase 9:Blind-spot agent— daily review: clients, pipeline, revenue, vault healthPhase 10:Seed 5 memories— user profile, deploy rule, feedback, tool ref, projectPhase 11:Verify circuit— 12-point pass/fail, everything checkedPhase 12:First review— live test with your actual files
JD Says
The Stop hook is the most important one. Without it, every session ends with zero memory written — all that context just evaporates. Wire it before anything else.
