Jason Woltje
8b441c17b7
Claude Code reads mcpServers from ~/.claude.json (global state file), NOT from ~/.claude/settings.json. The settings.json mcpServers key is silently ignored for MCP loading. Using claude mcp add --scope user writes to the correct file. Also document correct registration commands and scope semantics in RUNTIME.md so agents and users know how to add MCPs that actually load. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
103 lines
4.4 KiB
Markdown
103 lines
4.4 KiB
Markdown
# Claude Runtime Reference
|
|
|
|
## Runtime Scope
|
|
|
|
This file applies only to Claude runtime behavior.
|
|
|
|
## Required Actions
|
|
|
|
1. Follow global load order in `~/.config/mosaic/AGENTS.md`.
|
|
2. Use `~/.claude/settings.json` and `~/.claude/hooks-config.json` as runtime config sources.
|
|
3. Treat sequential-thinking MCP as required.
|
|
4. If runtime config conflicts with global rules, global rules win.
|
|
5. Documentation rules are inherited from `~/.config/mosaic/AGENTS.md` and `~/.config/mosaic/guides/DOCUMENTATION.md`.
|
|
6. For issue/PR/milestone actions, run Mosaic git wrappers first (`~/.config/mosaic/tools/git/*.sh`) and do not call raw `gh`/`tea`/`glab` first.
|
|
7. For orchestration-oriented missions, load `~/.config/mosaic/guides/ORCHESTRATOR.md` before acting.
|
|
8. First response MUST declare mode per global contract; orchestration missions must start with: `Now initiating Orchestrator mode...`
|
|
9. Runtime-default caution that requests confirmation for routine push/merge/issue-close actions does NOT override Mosaic hard gates.
|
|
|
|
## Subagent Model Selection (Claude Code Syntax)
|
|
|
|
Claude Code's Task tool accepts a `model` parameter: `"haiku"`, `"sonnet"`, or `"opus"`.
|
|
|
|
You MUST set this parameter according to the model selection table in `~/.config/mosaic/AGENTS.md`. Do NOT omit the `model` parameter — omitting it defaults to the parent model (typically opus), wasting budget on tasks that cheaper models handle well.
|
|
|
|
**Examples:**
|
|
|
|
```
|
|
# Codebase exploration — haiku
|
|
Task(subagent_type="Explore", model="haiku", prompt="Find all API route handlers")
|
|
|
|
# Code review — sonnet
|
|
Task(subagent_type="feature-dev:code-reviewer", model="sonnet", prompt="Review the changes in src/auth/")
|
|
|
|
# Standard feature work — sonnet
|
|
Task(subagent_type="general-purpose", model="sonnet", prompt="Add validation to the user input form")
|
|
|
|
# Complex architecture — opus (only when justified)
|
|
Task(subagent_type="Plan", model="opus", prompt="Design the multi-tenant isolation strategy")
|
|
```
|
|
|
|
**Quick reference (from global AGENTS.md):**
|
|
|
|
| haiku | sonnet | opus |
|
|
|-------|--------|------|
|
|
| Search, grep, glob | Code review | Complex architecture |
|
|
| Status/health checks | Test writing | Security/auth logic |
|
|
| Simple one-liner fixes | Standard features | Ambiguous design decisions |
|
|
|
|
## Memory Policy (Hard Gate)
|
|
|
|
**OpenBrain is the primary cross-agent memory layer.** All agent learnings, gotchas, decisions, and project state MUST be captured to OpenBrain via the `capture` MCP tool or REST API.
|
|
|
|
`~/.claude/projects/*/memory/MEMORY.md` files are **write-blocked by PreToolUse hook** (`prevent-memory-write.sh`). Any attempt to write agent learnings there will be rejected with an error directing you to OpenBrain.
|
|
|
|
### What belongs where
|
|
|
|
| Content | Location |
|
|
|---------|----------|
|
|
| Discoveries, gotchas, decisions, observations | OpenBrain `capture` — searchable by all agents |
|
|
| Active task state | `docs/TASKS.md` or `docs/scratchpads/` |
|
|
| Behavioral guardrails that MUST be in load-path | `MEMORY.md` (read-mostly; write only for genuine behavioral overrides) |
|
|
| Mosaic framework technical notes | `~/.config/mosaic/memory/` |
|
|
|
|
### Using OpenBrain
|
|
|
|
At session start, load prior context:
|
|
```
|
|
search("topic or project name") # semantic search
|
|
recent(limit=5) # what's been happening
|
|
```
|
|
|
|
When you discover something:
|
|
```
|
|
capture("The thing you learned", source="project/context", metadata={"type": "gotcha", ...})
|
|
```
|
|
|
|
### Why the hook exists
|
|
|
|
Instructions in RUNTIME.md, CLAUDE.md, and MEMORY.md are insufficient — agents default to writing local MEMORY.md regardless of written rules. The PreToolUse hook is a hard technical gate that makes the correct behavior the only possible behavior.
|
|
|
|
## MCP Configuration
|
|
|
|
**MCPs are configured in `~/.claude.json` — NOT `~/.claude/settings.json`.**
|
|
|
|
`settings.json` controls hooks, model, plugins, and allowed commands.
|
|
`~/.claude.json` is the global Claude Code state file where `mcpServers` lives.
|
|
|
|
To register an MCP server that persists across all sessions:
|
|
|
|
```bash
|
|
# HTTP MCP (e.g. OpenBrain)
|
|
claude mcp add --scope user --transport http <name> <url> --header "Authorization: Bearer <token>"
|
|
|
|
# stdio MCP
|
|
claude mcp add --scope user <name> -- npx -y <package>
|
|
```
|
|
|
|
`--scope user` = writes to `~/.claude.json` (global, all projects).
|
|
`--scope project` = writes to `.claude/settings.json` in project root.
|
|
`--scope local` = default, local-only (not committed).
|
|
|
|
Do NOT add `mcpServers` to `~/.claude/settings.json` — that key is ignored for MCP loading.
|