smolkik_adm/My-Brain-Is-Full-Crew
1
0
Fork 0
mirror of https://github.com/gnekt/My-Brain-Is-Full-Crew.git synced 2026-09-07 10:34:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add Codex CLI as a first-class fourth platform (#35)

Browse Source 
Rebuilt from scratch following Codex CLI's actual architecture (as
outlined in the review on PR #26). Closes the integration gap with a
proper build adapter, correct install paths, TOML agent files, and
all the architectural differences documented and tested.

What changed vs the previous attempt (PR #26):

- Agents: build adapter generates .toml files (name/description/
  developer_instructions) into dist/codex-cli/.codex/agents/ instead
  of copying .md files with sed transforms
- Skills: installed to .agents/skills/ (correct Codex discovery path)
  instead of .codex/skills/
- Dispatcher: AGENTS.md uses a root-context orchestration header that
  works within agents.max_depth=1 constraints; named-agent routing
  replaced with embedded-instructions workaround for the known
  spawn_agents limitation (openai/codex#15250)
- Tool compat: AskUserQuestion and request_user_input removed; all
  prompts adapted to Codex's actual tool set and approval/confirmation
  flow
- Installer/updater: launchme.sh --platform codex-cli and updateme.sh
  with Codex auto-detection, creating the correct split layout
  (AGENTS.md + .codex/agents/ + .codex/config.toml + .agents/skills/)
- Tests: new per-adapter test suite (tests/adapters/codex-cli/),
  install/update smoke (tests/scripts/codex-cli-install.test.sh), and
  a four-platform parity gate that proves Codex changes do not regress
  Claude Code, Gemini CLI, or OpenCode
- Docs: new codex-cli.md guide, codex-migration.md for users switching
  from other platforms, and README/getting-started/examples updated for
  four-platform positioning
- Bash harness: .gitattributes added to enforce LF on .sh files;
  harness LF-normalized so tests/run.sh works on Windows checkouts
- .gitignore: .planning/ added (internal GSD workflow artifacts)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Arpit Behera
2026-04-12 22:26:56 +03:00
committed by GitHub
parent 49839486b8
commit 18fc58c398
18 changed files with 3136 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

219
docs/codex-cli.md Normal file
View File

@@ -0,0 +1,219 @@
# Codex CLI Guide
This guide covers everything you need to install, update, and run My Brain Is Full — Crew on [Codex CLI](https://openai.com/codex) (`@openai/codex`).
> **Windows note:** Codex CLI's Windows support is experimental. If you are on Windows, running inside WSL (Windows Subsystem for Linux) is strongly recommended.
---
## Install and update commands
### First-time install
```bash
# Install Codex CLI globally
npm i -g @openai/codex@latest
# Clone the repo inside your vault and install the Crew
cd /path/to/your-vault
git clone https://github.com/gnekt/My-Brain-Is-Full-Crew.git
cd My-Brain-Is-Full-Crew
bash scripts/launchme.sh --platform codex-cli
```
The installer accepts an optional `--target` flag if you want to point it at a vault in a non-standard location:
```bash
bash scripts/launchme.sh --platform codex-cli --target /path/to/your-vault
```
### Update after a git pull
```bash
cd /path/to/your-vault/My-Brain-Is-Full-Crew
git pull
bash scripts/updateme.sh --platform codex-cli
```
The updater auto-detects Codex CLI by checking for `.codex/agents` in your vault. If multiple platforms are installed, pass `--platform codex-cli` explicitly.
---
## What installs where
After running `launchme.sh --platform codex-cli`, your vault will contain:
```
your-vault/
├── .codex/
│ ├── agents/ ← 8 core crew agents (.toml format)
│ ├── references/ ← shared docs the agents read
│ └── config.toml ← MCP server definitions + profiles + sandbox policy
├── .agents/
│ └── skills/ ← 14 specialized skills (plain text instructions)
├── Meta/
│ └── scripts/ ← orchestra scripts (permission-free agent commands)
└── AGENTS.md ← dispatcher (project instructions for Codex)
```
Key differences from other platforms:
| Path | Purpose |
|------|---------|
| `.codex/agents/*.toml` | Custom agent definitions (Codex native format) |
| `.agents/skills/` | Repo-scoped skill instructions (shared discovery path) |
| `.codex/config.toml` | MCP servers, approval policy, sandbox mode, model profiles |
| `AGENTS.md` | Dispatcher — Codex reads this as its primary project instruction file |
---
## Architecture differences from Claude Code, Gemini CLI, and OpenCode
### Dispatcher
All platforms use a dispatcher file, but the name and format differ:
| Platform | Dispatcher file |
|----------|----------------|
| Claude Code | `CLAUDE.md` |
| Gemini CLI | `GEMINI.md` |
| OpenCode | `AGENTS.md` |
| Codex CLI | `AGENTS.md` (with root-context routing header) |
Codex CLI shares the `AGENTS.md` name with OpenCode but prepends a routing header that handles orchestration within the `agents.max_depth = 1` constraint (see below).
### Agent format
Claude Code, Gemini CLI, and OpenCode all use Markdown (`.md`) agent files. Codex CLI uses TOML:
```
.claude/agents/architect.md ← Claude Code
.gemini/agents/architect.md ← Gemini CLI
.opencode/agents/architect.md ← OpenCode
.codex/agents/architect.toml ← Codex CLI
```
### Skills location
Skills install to `.agents/skills/` for Codex (not `.codex/skills/`). Codex CLI discovers skills from this shared path.
### Agent chaining (max_depth constraint)
Codex CLI enforces `agents.max_depth = 1`. This means child agents can only go one level deep. My Brain Is Full — Crew handles this through root-context orchestration:
- The dispatcher embeds orchestration instructions in the root context (not in a child)
- Child agents (`spawn_agent`) finish one bounded task and return to root
- Any next step is decided from the root context, not by a nested child
### Tool name differences
Codex CLI does not have the `AskUserQuestion` or `request_user_input` tools. The equivalent patterns are:
| Source concept | Codex CLI equivalent |
|---|---|
| `AskUserQuestion` | Ask a direct question in the chat thread and wait for the reply |
| `request_user_input` | Same — use the root conversation for follow-up questions |
| `Skill tool` | Follow the skill instructions directly in the root context |
| `Agent tool` | Use `spawn_agent` for a bounded child task; orchestration returns to root |
| `max chain depth 3` | `agents.max_depth = 1` with root-only orchestration |
| `.mcp.json` | `.codex/config.toml` |
### MCP configuration
Claude Code uses `.mcp.json`. Codex CLI uses `.codex/config.toml`. The MCP server, approval policy, sandbox mode, and model profile settings all live in the TOML config. The CLI and Codex IDE extension share this same config file.
---
## Runtime smoke matrix
Use this table to verify the Crew works correctly in a real Codex vault after install or update. Run each row and compare the result against the expected outcome.
| Surface | Name | Prompt or command | Expected result |
|---------|------|-------------------|----------------|
| Agent | Architect | `@Architect Set up my vault structure` | Architect starts onboarding conversation or confirms vault is already set up |
| Agent | Scribe | `@Scribe Save this note: quick test` | Scribe creates a note in 00-Inbox with proper frontmatter |
| Agent | Sorter | `@Sorter Triage my inbox` | Sorter reviews inbox notes and files them, or reports inbox is empty |
| Agent | Seeker | `@Seeker What do I know about this project?` | Seeker searches the vault and returns results with source citations |
| Agent | Connector | `@Connector Find connections in my recent notes` | Connector analyzes the vault graph and suggests wikilinks |
| Agent | Librarian | `@Librarian Run a vault health check` | Librarian scans for broken links, duplicates, and orphan notes |
| Agent | Transcriber | `@Transcriber Process this transcript: [paste text]` | Transcriber generates structured meeting notes |
| Agent | Postman | `@Postman Check my email` | Postman scans Gmail (or Hey) and saves actionable emails, or reports missing integration |
| Skill | onboarding | `/onboarding` | Architect starts the full onboarding conversation |
| Skill | create-agent | `/create-agent` | Architect walks through designing a new custom agent |
| Skill | manage-agent | `/manage-agent` | Architect lists, edits, or removes custom agents |
| Skill | defrag | `/defrag` | Architect runs the 5-phase vault defragmentation |
| Skill | email-triage | `/email-triage` | Postman scans and prioritizes unread emails |
| Skill | meeting-prep | `/meeting-prep` | Postman generates a comprehensive meeting brief |
| Skill | weekly-agenda | `/weekly-agenda` | Postman produces a day-by-day week overview |
| Skill | deadline-radar | `/deadline-radar` | Postman produces a unified deadline timeline |
| Skill | transcribe | `/transcribe` | Transcriber processes a recording or transcript into structured notes |
| Skill | vault-audit | `/vault-audit` | Librarian runs the full 7-phase vault audit |
| Skill | deep-clean | `/deep-clean` | Librarian runs the extended vault cleanup |
| Skill | tag-garden | `/tag-garden` | Librarian analyzes and cleans up tags |
| Skill | inbox-triage | `/inbox-triage` | Sorter processes and routes all inbox notes |
| Skill | contact-sync | `/contact-sync` | Postman syncs contacts to Apple Contacts |
| Chaining | bounded child-agent chain | `@Sorter Triage my inbox` (with notes present that mention a new project) | Sorter files notes, then dispatcher signals Architect to create the new project folder; child returns to root before Architect runs |
| MCP | MCP visibility | `codex -C <vault> mcp list` | Lists the MCP servers configured in `.codex/config.toml`, or shows the auth/setup state for each server |
### Running the non-interactive discovery smoke
```bash
codex exec -C <vault> "List the project custom agents under .codex/agents, the repo skills under .agents/skills, and the dispatcher file used in this workspace."
```
Expected output references:
- `AGENTS.md` (the dispatcher)
- `.codex/agents` path (custom agents)
- `.agents/skills` path (repo skills)
### Running the MCP visibility smoke
```bash
codex -C <vault> mcp list
```
Expected: lists MCP servers from `.codex/config.toml` (e.g., `Gmail`, `Calendar`) or shows their auth/setup state.
---
## Troubleshooting
### Agents are not discovered
- Verify `.codex/agents/` exists in your vault root and contains `.toml` files.
- Open Codex CLI from your vault directory: `codex -C /path/to/your-vault`
- Check that `AGENTS.md` exists at the vault root (not inside the repo subdirectory).
### Skills are not available
- Verify `.agents/skills/` exists in your vault root and contains subdirectories.
- Skills must be at the vault root level: `<vault>/.agents/skills/<skill-name>/`
### Child agent chain does not return to root
- This is a Codex `agents.max_depth = 1` constraint. Child agents can only go one level deep.
- The dispatcher uses root-context orchestration to work within this constraint.
- If a task seems to require deeper nesting, flatten it: complete the first bounded step in a child, then handle the next step in the root context.
### MCP server not connecting
- MCP configuration lives in `.codex/config.toml` (not `.mcp.json`).
- Check `codex -C <vault> mcp list` to see the current server status.
- For Gmail/Calendar setup, see `docs/gws-setup-guide.md`.
- For Apple Contacts, verify the `apple-contacts` server entry in `.codex/config.toml`.
### Codex errors about approvals
- Child agent approvals surface in the child thread. Approve or deny there, then continue orchestration from the root context after the child returns.
- If a task requires deeper recursion, stop spawning children and flatten the next step into the root context or split the work into separate bounded child tasks.
### Windows users
Codex CLI's Windows support is experimental. Use WSL (Windows Subsystem for Linux) for the most reliable experience. From WSL, follow the standard Linux install path above.
### Reinstall vs update
- **Reinstall** (`launchme.sh`): Use when setting up a new vault or recovering from a broken state.
- **Update** (`updateme.sh`): Use after `git pull` to push new agents, skills, and references to an existing vault. Custom agents are never overwritten.
For a migration from another platform, see [docs/codex-migration.md](codex-migration.md).

172
docs/codex-migration.md Normal file
View File

@@ -0,0 +1,172 @@
# Migrating to Codex CLI
This guide covers how to move an existing My Brain Is Full — Crew installation from Claude Code, Gemini CLI, or OpenCode to Codex CLI. It also explains what transfers automatically and what needs manual attention.
> **If you are doing a fresh install** (not migrating), follow [docs/codex-cli.md](codex-cli.md) instead.
---
## When to reinstall vs update
| Scenario | Recommended action |
|----------|-------------------|
| You have an existing Claude Code / Gemini CLI / OpenCode vault and want to add Codex CLI alongside it | Run `bash scripts/launchme.sh --platform codex-cli` in the same vault — multiple platforms can coexist |
| You want to switch exclusively to Codex CLI | Run `launchme.sh --platform codex-cli`; the other platform files remain but are inactive |
| Your Codex layout is broken or missing files | Run `launchme.sh --platform codex-cli` again — it is idempotent and safe to re-run |
| You pulled new repo changes and want to update Codex | Run `bash scripts/updateme.sh --platform codex-cli` |
You do not need to remove other platform directories. Codex CLI only reads `.codex/` and `.agents/skills/`; it ignores `.claude/`, `.gemini/`, and `.opencode/`.
---
## Path mapping by platform
When you switch to Codex CLI, the project files move to new paths. Use this table to locate your existing files and understand where the equivalent lives in Codex.
| Source platform | Dispatcher | Agents | Skills | MCP or config | Codex target |
|----------------|-----------|--------|--------|--------------|-------------|
| Claude Code | `CLAUDE.md` | `.claude/agents/*.md` | `.claude/skills/` | `.mcp.json` | `AGENTS.md` / `.codex/agents/*.toml` / `.agents/skills/` / `.codex/config.toml` |
| Gemini CLI | `GEMINI.md` | `.gemini/agents/*.md` | `.gemini/skills/` | (none) | `AGENTS.md` / `.codex/agents/*.toml` / `.agents/skills/` / `.codex/config.toml` |
| OpenCode | `AGENTS.md` | `.opencode/agents/*.md` | `.opencode/skills/` | `opencode.json` | `AGENTS.md` / `.codex/agents/*.toml` / `.agents/skills/` / `.codex/config.toml` |
After running `launchme.sh --platform codex-cli`, the Codex files are installed automatically. You do not need to copy the old platform files manually.
---
## Moving from Claude Code
1. Pull the latest repo changes:
```bash
cd /path/to/your-vault/My-Brain-Is-Full-Crew
git pull
```
2. Run the Codex installer:
```bash
bash scripts/launchme.sh --platform codex-cli
```
3. The installer creates:
- `.codex/agents/` — all 8 core agents in TOML format
- `.agents/skills/` — all 14 skills as plain text instructions
- `.codex/config.toml` — MCP servers (translated from `mcp/servers.yaml`)
- `AGENTS.md` — dispatcher with Codex routing header
4. Your existing `.claude/` directory and `CLAUDE.md` are left untouched.
5. MCP configuration: Claude Code uses `.mcp.json`. Codex CLI uses `.codex/config.toml`. If you added custom MCP servers to `.mcp.json` manually, you will need to add them to `.codex/config.toml` as well. See the `[mcp_servers.*]` TOML table format.
6. Custom agents: Claude Code custom agents live in `.claude/agents/`. Codex CLI custom agents must be in `.toml` format in `.codex/agents/`. Custom agents created via the `/create-agent` skill are not automatically migrated — see [Custom agents and what does not migrate automatically](#custom-agents-and-what-does-not-migrate-automatically).
---
## Moving from Gemini CLI
1. Pull the latest repo changes:
```bash
cd /path/to/your-vault/My-Brain-Is-Full-Crew
git pull
```
2. Run the Codex installer:
```bash
bash scripts/launchme.sh --platform codex-cli
```
3. The installer creates the full Codex layout (same as above).
4. Your existing `.gemini/` directory and `GEMINI.md` are left untouched.
5. MCP configuration: Gemini CLI does not use `.mcp.json`. If you have MCP servers configured elsewhere, add them to `.codex/config.toml` manually.
6. Custom agents: Gemini CLI custom agents live in `.gemini/agents/`. These are Markdown files. For Codex CLI, custom agents must be TOML files in `.codex/agents/`. See [Custom agents and what does not migrate automatically](#custom-agents-and-what-does-not-migrate-automatically).
---
## Moving from OpenCode
1. Pull the latest repo changes:
```bash
cd /path/to/your-vault/My-Brain-Is-Full-Crew
git pull
```
2. Run the Codex installer:
```bash
bash scripts/launchme.sh --platform codex-cli
```
3. The installer creates the full Codex layout. Note that both OpenCode and Codex CLI use `AGENTS.md` as the dispatcher. The installer will overwrite `AGENTS.md` with the Codex-specific version (which includes the root-context routing header). If you are running both platforms from the same vault, be aware that the two platforms share `AGENTS.md`.
4. Your existing `.opencode/` directory is left untouched.
5. MCP configuration: OpenCode uses `opencode.json`. Codex CLI uses `.codex/config.toml`. If you added custom MCP servers to `opencode.json`, add them to `.codex/config.toml` manually.
6. Custom agents: OpenCode custom agents live in `.opencode/agents/` as Markdown files. Codex CLI custom agents must be TOML files in `.codex/agents/`. See [Custom agents and what does not migrate automatically](#custom-agents-and-what-does-not-migrate-automatically).
---
## Custom agents and what does not migrate automatically
When you run the installer, the 8 core crew agents are automatically translated to Codex TOML format. However, **custom agents you created with `/create-agent`** are not automatically migrated because:
- They live in your platform's agents directory (`.claude/agents/`, `.gemini/agents/`, etc.)
- They are Markdown files; Codex requires TOML
- The installer never overwrites or deletes files in the agents directory that it did not create
### To migrate a custom agent manually
1. Locate your custom agent file (e.g., `.claude/agents/budget-tracker.md`)
2. Open Codex CLI in your vault and run `/create-agent`
3. Describe the agent's purpose — the Architect will guide you through creating a new `.toml` file in `.codex/agents/`
4. Alternatively, create the TOML file manually using one of the generated core agents as a template (e.g., `.codex/agents/scribe.toml`)
### What the TOML format looks like
```toml
[agent]
name = "budget-tracker"
description = "Monitors spending notes and flags when you are close to the monthly limit"
model = "o4-mini"
[agent.prompt]
content = """
You are the Budget Tracker agent for the My Brain Is Full — Crew system.
... (your agent instructions here)
"""
```
---
## Verification after migration
After running the installer, verify the Codex layout with these commands:
### Check that files installed correctly
```bash
ls <vault>/.codex/agents/ # Should list *.toml files for all 8 agents
ls <vault>/.agents/skills/ # Should list subdirectories for all 14 skills
ls <vault>/.codex/config.toml # Should exist with [mcp_servers.*] tables
ls <vault>/AGENTS.md # Should exist with Codex routing header
```
### Run the non-interactive discovery smoke
```bash
codex exec -C <vault> "List the project custom agents under .codex/agents, the repo skills under .agents/skills, and the dispatcher file used in this workspace."
```
Expected: response references `AGENTS.md`, `.codex/agents`, and `.agents/skills`.
### Check MCP visibility
```bash
codex -C <vault> mcp list
```
Expected: lists MCP servers from `.codex/config.toml`.
### Run the full runtime smoke matrix
See [docs/codex-cli.md — Runtime smoke matrix](codex-cli.md#runtime-smoke-matrix) for the complete list of agents, skills, chaining, and MCP checks.

51
docs/examples.md
View File

@@ -155,6 +155,57 @@ Practical scenarios showing how the Crew works in daily life. Each example shows
---
## Codex CLI session examples
These examples show how to start and use the Crew with Codex CLI specifically.
### Install and launch
```bash
# Install Codex CLI
npm i -g @openai/codex@latest
# Install the Crew for Codex CLI
bash scripts/launchme.sh --platform codex-cli
# Launch Codex in your vault
codex -C /path/to/your-vault
```
### Verify the layout before your first session
```bash
# Non-interactive discovery smoke — confirms agents, skills, and dispatcher are visible
codex exec -C /path/to/your-vault "List the project custom agents under .codex/agents, the repo skills under .agents/skills, and the dispatcher file used in this workspace."
# Check MCP server visibility
codex -C /path/to/your-vault mcp list
```
### Using agents and skills inside Codex
Once inside the interactive `codex` session, the Crew works the same way as on other platforms — just talk naturally:
```
"Initialize my vault" → /onboarding skill starts
"Save this note: quick idea" → Scribe agent captures it
"Triage my inbox" → /inbox-triage skill runs
"Check my email" → /email-triage skill scans Gmail
"Weekly review" → /vault-audit skill audits vault
```
### Update after a git pull
```bash
cd /path/to/your-vault/My-Brain-Is-Full-Crew
git pull
bash scripts/updateme.sh --platform codex-cli
```
For the full runtime smoke matrix covering all 8 agents, all 14 skills, bounded child-agent chaining, and MCP visibility, see [docs/codex-cli.md](codex-cli.md).
---
## Daily Workflow Cheat Sheet
| Time | What to say | Skill/Agent |

50
docs/getting-started.md
View File

@@ -8,7 +8,9 @@ A step-by-step guide for setting up your AI-powered vault. No technical backgrou
### Required
- **Obsidian**: A free note-taking app. Download it at [obsidian.md](https://obsidian.md)
- **An agent platform**: one of [Claude Code](https://claude.ai/code) (Pro/Max/Team), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [OpenCode](https://opencode.ai).
- **An agent platform**: one of [Claude Code](https://claude.ai/code) (Pro/Max/Team), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [OpenCode](https://opencode.ai), or [Codex CLI](https://openai.com/codex) (`npm i -g @openai/codex`).
> **Windows + Codex CLI:** Codex CLI's Windows support is experimental. If you plan to use Codex CLI on Windows, run it inside WSL (Windows Subsystem for Linux) for the best experience.
- **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](https://git-scm.com).
@@ -66,8 +68,9 @@ Install one of the following:
| **Claude Code** | [claude.ai/code](https://claude.ai/code) | Claude Pro, Max, or Team |
| **Gemini CLI** | [github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) | Google account |
| **OpenCode** | [opencode.ai](https://opencode.ai) | Varies by provider |
| **Codex CLI** | `npm i -g @openai/codex` | OpenAI account |
Claude Code works as both CLI and Desktop app (Cowork). The Crew works on all supported platforms.
Claude Code works as both CLI and Desktop app (Cowork). The Crew works on all four supported platforms.
---
@@ -95,19 +98,34 @@ bash scripts/launchme.sh
```
The script will ask a couple of questions:
1. **Which platform?** Select your agent platform (Claude Code, Gemini CLI, or OpenCode)
1. **Which platform?** Select your agent platform (Claude Code, Gemini CLI, OpenCode, or Codex CLI)
2. **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
├── .<platform>/ ← .claude/, .gemini/, .opencode/
│ ├── 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)
├── CLAUDE.md / GEMINI.md / AGENTS.md ← dispatcher (varies by platform)
├── My-Brain-Is-Full-Crew/ ← the repo (for future updates)
└── ... your Obsidian notes
```
**Codex CLI** uses a split layout instead of a single platform directory:
```
your-vault/
├── .codex/
│ ├── agents/ ← 8 core agents (.toml format)
│ ├── references/ ← shared docs
│ └── config.toml ← MCP servers + profiles + sandbox policy
├── .agents/
│ └── skills/ ← 14 specialized skills
├── AGENTS.md ← dispatcher
├── My-Brain-Is-Full-Crew/ ← the repo (for future updates)
└── ... your Obsidian notes
```
@@ -118,13 +136,18 @@ your-vault/
## Step 4: Connect your vault
1. Open your agent platform (Claude Code, Gemini CLI, or OpenCode)
1. Open your agent platform (Claude Code, Gemini CLI, OpenCode, or Codex CLI)
2. 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:
```bash
cd /path/to/your-vault
claude # or: gemini, opencode
claude # or: gemini, opencode, codex
```
For Codex CLI, you can also use the `-C` flag to point directly at your vault:
```bash
codex -C /path/to/your-vault
```
If you're using Claude Code Desktop (Cowork), open the vault folder as your working directory.
@@ -220,7 +243,11 @@ The Crew works best with simple daily routines:
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](https://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.
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](https://github.com/basecamp/hey-cli) and run `hey auth login`.
For MCP connectors:
- **Claude Code / OpenCode**: run the installer again (`bash scripts/launchme.sh`) and answer **yes** to the Gmail/Calendar question, or manually add the servers to your `.mcp.json` at the vault root.
- **Codex CLI**: MCP servers are configured in `.codex/config.toml` (not `.mcp.json`). Run `bash scripts/launchme.sh --platform codex-cli` and the installer writes them automatically. See [docs/codex-cli.md](codex-cli.md) for the full MCP setup details.
### "My vault structure looks different from the docs"
The Architect customizes the structure based on your onboarding answers.
@@ -233,6 +260,11 @@ git pull
bash scripts/updateme.sh
```
For Codex CLI specifically:
```bash
bash scripts/updateme.sh --platform codex-cli
```
Only changed files are updated. Your vault notes are never touched.
### "An agent did something weird"
@@ -249,6 +281,8 @@ Open an issue on GitHub with:
## Next steps
- **[Examples](examples.md)**: See real-world usage scenarios
- **[Codex CLI Guide](codex-cli.md)**: Install/update guide, architecture differences, runtime smoke matrix, and troubleshooting for Codex CLI
- **[Migrate to Codex CLI](codex-migration.md)**: Step-by-step migration from Claude Code, Gemini CLI, or OpenCode
- **[Mobile Access](mobile-access.md)**: Use the Crew from your phone
- **[Meet the Agents](agents/)**: Deep-dive into each agent's capabilities
- **[Contributing](../CONTRIBUTING.md)**: Help make the Crew better