[docs] Add ob CLI and CLI-Direct references across all documentation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: az9713

CLAUDE.md

@@ -18,7 +18,7 @@ schemas/        — Database table extensions. Open.
 dashboards/     — Frontend templates (Vercel/Netlify). Open.
 integrations/   — MCP extensions, webhooks, capture sources. Open.
 docs/           — Setup guides, FAQ, companion prompts.
-resources/      — Claude Skill, companion files.
+resources/      — Claude Skill, companion files, ob CLI tool.
 ```
 
 Every contribution lives in its own subfolder under the right category and must include `README.md` + `metadata.json`.
@@ -58,3 +58,4 @@ Every contribution lives in its own subfolder under the right category and must
 - `docs/02-companion-prompts.md` — Five prompts for memory migration, use case discovery, and weekly review
 - `docs/03-faq.md` — Common issues, architecture questions, and community tips
 - `docs/04-ai-assisted-setup.md` — Build with Cursor, Claude Code, or other AI coding tools
+- `docs/CLI_DIRECT_APPROACH.md` — CLI-Direct approach: use Open Brain from terminal AI tools without MCP

CONTRIBUTING.md

@@ -30,6 +30,7 @@ This is a first-class path, not a workaround. Some of the best contributions com
 | `schemas/` | Database table extensions and metadata schemas | CRM contacts table, taste tracker, reading list schema | Open |
 | `dashboards/` | Frontend templates for Vercel/Netlify hosting | Knowledge dashboard, weekly review, mobile capture UI | Open |
 | `integrations/` | MCP extensions, webhooks, capture sources | Discord bot, email handler, browser extension, calendar sync | Open |
+| `resources/` | Companion tools and files | `ob` CLI tool, Claude Skill | Not a contribution category |
 
 ### Extensions vs Primitives vs Recipes
 

README.md

@@ -23,8 +23,9 @@ Never built an Open Brain? Start here:
 1. **[Quick Start Guide](docs/QUICKSTART.md)** — Already set up? Get your first 10 wins in 5 minutes.
 2. **[Setup Guide](docs/01-getting-started.md)** — Build the full system (database, AI gateway, Slack capture, MCP server) in about 45 minutes. No coding experience needed.
 3. **[AI-Assisted Setup](docs/04-ai-assisted-setup.md)** — Prefer building with Cursor, Claude Code, or another AI coding tool? Point it at this repo and go. Same system, different workflow.
-4. **[Companion Prompts](docs/02-companion-prompts.md)** — Five prompts that help you migrate your memories, discover use cases, and build the capture habit.
-5. **Then pick Extension 1** and start building.
+4. **[CLI-Direct Approach](docs/CLI_DIRECT_APPROACH.md)** — Use Claude Code, Codex, or Gemini CLI? Skip MCP entirely and use the lightweight [`ob` CLI tool](resources/ob-cli/) for direct access with just `curl` and `jq`.
+5. **[Companion Prompts](docs/02-companion-prompts.md)** — Five prompts that help you migrate your memories, discover use cases, and build the capture habit.
+6. **Then pick Extension 1** and start building.
 
 **If you hit a wall:** We built a [FAQ](docs/03-faq.md) that covers the most common questions and gotchas. And if you need real-time help, we created dedicated AI assistants that know this system inside and out: a [Claude Skill](https://www.notion.so/product-templates/Open-Brain-Companion-Claude-Skill-31a5a2ccb526802797caeb37df3ba3cb?source=copy_link), a [ChatGPT Custom GPT](https://chatgpt.com/g/g-69a892b6a7708191b00e48ff655d5597-nate-jones-open-brain-assistant), and a [Gemini GEM](https://gemini.google.com/gem/1fDsAENjhdku-3RufY7ystbS1Md8MtDCg?usp=sharing). Use whichever one matches the AI tool you already use.
 
@@ -42,6 +43,7 @@ Never built an Open Brain? Start here:
 | [Companion Prompts](docs/02-companion-prompts.md) | Users | Memory migration, use case discovery, weekly review ritual |
 | [FAQ](docs/03-faq.md) | Everyone | Common issues, architecture questions, community tips |
 | [AI-Assisted Setup](docs/04-ai-assisted-setup.md) | Everyone | Build with Cursor, Claude Code, or other AI coding tools |
+| [CLI-Direct Approach](docs/CLI_DIRECT_APPROACH.md) | Developers | Use Open Brain from terminal AI tools without MCP — includes the `ob` CLI |
 
 ## Extensions — The Learning Path
 

docs/01-getting-started.md

@@ -10,6 +10,8 @@ https://github.com/user-attachments/assets/85208d73-112b-4204-82fd-d03b6c397a8b
 
 A database that stores your thoughts with vector embeddings, plus an MCP server that lets any AI assistant search and write to your brain. No Slack required — capture happens from whatever AI tool you're already using (Claude Desktop, ChatGPT, Claude Code, Cursor).
 
+> **Using a terminal-based AI tool (Claude Code, Codex, Gemini CLI)?** You can skip MCP entirely and use the lightweight `ob` CLI instead. See the [CLI-Direct Approach](CLI_DIRECT_APPROACH.md) guide and the [`ob` CLI tool](../resources/ob-cli/). You still need Steps 1–4 below (database + OpenRouter), but you can skip Steps 5–7 (Edge Function and MCP).
+
 ## What You Need
 
 About 30 minutes and zero coding experience. You'll copy and paste everything.

docs/02-companion-prompts.md

@@ -12,7 +12,7 @@ Your Open Brain is built. Now make it work for you. These five prompts cover the
 - **Prompt 4: Quick Capture Templates** — Five capture patterns optimized for clean metadata extraction
 - **Prompt 5: The Weekly Review** — End-of-week synthesis that surfaces themes, forgotten action items, and emerging patterns
 
-**Tools:** All prompts work with any MCP-connected AI (Claude, ChatGPT, Gemini, Grok). Prompt 1 specifically requires an AI that has accumulated memory about you. Prompts 2 and 5 require your Open Brain MCP server to be connected.
+**Tools:** All prompts work with any MCP-connected AI (Claude, ChatGPT, Gemini, Grok). Prompt 1 specifically requires an AI that has accumulated memory about you. Prompts 2 and 5 require your Open Brain MCP server to be connected. If you use the [CLI-Direct approach](CLI_DIRECT_APPROACH.md) with the [`ob` CLI tool](../resources/ob-cli/) instead of MCP, you can adapt these prompts by having your AI run `ob capture` and `ob search` shell commands in place of the MCP tools.
 
 ---
 

docs/03-faq.md

@@ -180,4 +180,22 @@ If you run into a blocker, post it in the Substack chat thread — not in someon
 
 ---
 
+---
+
+## CLI-Direct and the `ob` Tool
+
+### "Can I use Open Brain from the terminal without MCP?"
+
+Yes. The [CLI-Direct Approach](CLI_DIRECT_APPROACH.md) describes how to use Open Brain from terminal-based AI tools (Claude Code, OpenAI Codex, Gemini CLI) without MCP. It uses a lightweight bash script called `ob` that talks directly to Supabase and OpenRouter using `curl` and `jq`. No Edge Function, no MCP server, no deployment step. Setup takes 5–10 minutes. The script lives at [`resources/ob-cli/ob`](../resources/ob-cli/) in this repo.
+
+### "Should I use MCP or the `ob` CLI?"
+
+If you only use terminal-based AI tools, the CLI-Direct approach is simpler. If you use both GUI clients (Claude Desktop, ChatGPT) and CLI tools, use both — MCP for GUI, `ob` for terminal. Both paths write to the same `thoughts` table and are fully interoperable. See the [comparison matrix](CLI_DIRECT_APPROACH.md#9-comparison-matrix-mcp-vs-cli-direct) for a detailed breakdown.
+
+### "I set up `ob` but `ob capture` fails"
+
+Check your environment variables: `OB_SUPABASE_URL`, `OB_SUPABASE_KEY`, and `OB_OPENROUTER_KEY` must all be set. Run `ob version` to see which are configured. See the [CLI-Direct troubleshooting section](CLI_DIRECT_APPROACH.md#11-troubleshooting) for common issues.
+
+---
+
 *This FAQ is based on real community questions from the Substack chat and YouTube comments. If you run into something not covered here, [open an issue](https://github.com/NateBJones-Projects/OB1/issues) or post in the [Substack community](https://natesnewsletter.substack.com/) so everyone benefits from the answer.*

docs/04-ai-assisted-setup.md

@@ -6,6 +6,8 @@ Point your AI coding tool at this repo and tell it to walk you through the [setu
 
 This works in Cursor, Claude Code, Codex, Windsurf, OpenClaw, or any AI coding tool that can read files. You don't need to copy-paste from a browser or follow along manually. Let your AI be your pair programmer through the whole build.
 
+> **Terminal-only alternative:** If you use Claude Code, Codex, or Gemini CLI and want the simplest possible setup, consider the [CLI-Direct Approach](CLI_DIRECT_APPROACH.md) instead. It uses a lightweight [`ob` CLI tool](../resources/ob-cli/) (`curl` + `jq` only) to talk directly to Supabase — no MCP server, no Edge Function deployment. Setup takes 5–10 minutes instead of 30–45.
+
 ## How to Start
 
 1. Clone or open this repo in your AI coding tool

docs/API_REFERENCE.md

@@ -21,6 +21,8 @@ Complete reference for the Open Brain MCP Tools API, extension MCP servers, data
 
 The core MCP server is deployed as a Supabase Edge Function. It provides four tools that give any MCP-connected AI client the ability to read and write to the `thoughts` table.
 
+> **CLI alternative:** The [`ob` CLI tool](../resources/ob-cli/) provides the same four capabilities (capture, search, recent, stats) as direct shell commands using `curl` and `jq`. It talks to the same Supabase REST API and `match_thoughts()` RPC function documented below — no MCP server required. See [CLI-Direct Approach](CLI_DIRECT_APPROACH.md) for the full architecture.
+
 **Deployment path:** `supabase/functions/open-brain-mcp/index.ts`
 
 **Live URL pattern:**

docs/ARCHITECTURE.md

@@ -23,6 +23,8 @@ This document describes the complete technical architecture of the Open Brain sy
 
 Open Brain is a three-tier system. Think of it like a classic client-server application, except the "client" is an AI assistant and the "server" speaks a specialized protocol called MCP.
 
+> **Alternative path:** Terminal-based AI tools (Claude Code, Codex, Gemini CLI) can bypass Tier 2 entirely using the [`ob` CLI tool](../resources/ob-cli/), which calls the Supabase REST API and OpenRouter directly. See [CLI-Direct Approach](CLI_DIRECT_APPROACH.md) for that architecture. Both paths use the same Tier 3 infrastructure and the same `thoughts` table.
+
 ```
 ┌─────────────────────────────────────────────────────────────────────┐
 │                         TIER 1: AI CLIENTS                          │

docs/DEVELOPER_GUIDE.md

@@ -610,14 +610,17 @@ docs/
 
 These are end-user docs. The DEVELOPER_GUIDE.md you are reading is also in this folder.
 
-### `resources/` — Claude Skill and Companion Files
+### `resources/` — Companion Tools and Files
 
 ```
 resources/
-└── (Claude Skill and companion prompt files)
+├── ob-cli/              # ob CLI tool — direct Open Brain access without MCP
+│   ├── ob               # The bash script (curl + jq only)
+│   └── README.md        # Installation and usage
+└── open-brain-companion.skill  # Claude Skill for AI-assisted help
 ```
 
-Resources are companion tools — things like the Claude Skill that knows the Open Brain system and can help users when they get stuck.
+Resources are companion tools. The `ob` CLI provides a lightweight alternative to MCP for terminal-based AI tools — see [`docs/CLI_DIRECT_APPROACH.md`](CLI_DIRECT_APPROACH.md) for the full guide. The Claude Skill helps users when they get stuck.
 
 ### `.ignore/` — Files Hidden from Some Tools