4b7eca8a46
All checks were successful
Reindex Knowledge Base / reindex (push) Successful in 3s
Adds title, description, type, domain, and tags frontmatter to every doc for improved KB semantic search. The description field is prepended to every search chunk, and domain/type/tags enable filtered queries. Type values: context, guide, runbook, reference, troubleshooting Domain values match directory structure (networking, docker, etc.) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
110 lines
3.8 KiB
Markdown
110 lines
3.8 KiB
Markdown
---
|
|
title: "Claude Code Configuration"
|
|
description: "Reference for Claude Code config file locations and precedence, MCP server setup in ~/.claude.json, hooks, permissions, and common gotchas."
|
|
type: reference
|
|
domain: workstation
|
|
tags: [claude-code, mcp, config, hooks, permissions, claude]
|
|
---
|
|
|
|
# Claude Code Configuration
|
|
|
|
## Config File Locations
|
|
|
|
Claude Code reads settings from multiple files in a specific precedence order:
|
|
|
|
| File | Scope | What goes here |
|
|
|------|-------|---------------|
|
|
| `~/.claude.json` | User-level (all projects) | MCP servers, startup state, git repo mappings |
|
|
| `~/.claude/settings.json` | User-level (all projects) | Permissions, hooks, env vars, plugins, status line |
|
|
| `~/.claude/projects/<sanitized-cwd>/settings.json` | Project-level | Project-specific permission overrides |
|
|
| `<repo>/.claude/settings.json` | Repo-level (checked in) | Shared team settings |
|
|
| `<repo>/.mcp.json` | Repo-level (checked in) | Project-scoped MCP servers |
|
|
|
|
**Important**: `~/.claude.json` (home directory root) is different from `~/.claude/settings.json` (inside the `.claude` directory). They serve different purposes.
|
|
|
|
## MCP Server Configuration
|
|
|
|
MCP servers are defined in the top-level `mcpServers` key of `~/.claude.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"server-name": {
|
|
"command": "/path/to/binary",
|
|
"args": ["-t", "stdio"],
|
|
"env": {
|
|
"API_KEY": "value"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Server Types
|
|
|
|
**stdio** — local process, communicates over stdin/stdout:
|
|
```json
|
|
{
|
|
"command": "/path/to/binary",
|
|
"args": ["--flag", "value"],
|
|
"env": { "KEY": "value" }
|
|
}
|
|
```
|
|
|
|
**http** — remote HTTP server (Streamable HTTP transport):
|
|
```json
|
|
{
|
|
"type": "http",
|
|
"url": "http://host:port/mcp",
|
|
"headers": {
|
|
"Authorization": "Bearer <token>"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Current MCP Servers
|
|
|
|
All defined in `~/.claude.json` under `mcpServers`:
|
|
|
|
| Server | Type | Purpose |
|
|
|--------|------|---------|
|
|
| `cognitive-memory` | stdio | Persistent memory system (local Python) |
|
|
| `n8n-mcp` | stdio | n8n workflow automation API |
|
|
| `gitea-mcp` | stdio | Gitea API (issues, PRs, repos) |
|
|
| `tui-driver` | stdio | TUI automation for testing |
|
|
| `kb-search` | url | Knowledge base semantic search (manticore) |
|
|
|
|
### Managing MCP Servers
|
|
|
|
- **Add interactively**: `/mcp add <name>` in Claude Code (stores in `~/.claude.json`)
|
|
- **Add manually**: Edit the `mcpServers` object in `~/.claude.json`
|
|
- **Reconnect**: `/mcp` → select server → Reconnect (useful after remote server restarts)
|
|
- **Permissions**: Auto-allow MCP tools via `"mcp__server-name__*"` in `~/.claude/settings.json` permissions.allow
|
|
|
|
### Gotchas
|
|
|
|
- **Session drops**: Remote (url) MCP servers lose their session if the server container restarts. Run `/mcp` to reconnect.
|
|
- **Don't confuse config files**: `~/.claude.json` holds MCP servers. `~/.claude/settings.json` holds permissions/hooks. They are NOT the same file.
|
|
- **Stale configs**: `~/.claude/.mcp.json` and `~/.claude/.mcp-full.json` are NOT read by Claude Code despite looking like they should be. The canonical location is `~/.claude.json`.
|
|
|
|
## Hooks
|
|
|
|
Hooks are configured in `~/.claude/settings.json` under the `hooks` key. They run shell commands or HTTP requests in response to events.
|
|
|
|
### Current Hooks
|
|
|
|
| Event | Action |
|
|
|-------|--------|
|
|
| `PostToolUse` (Edit/Write/MultiEdit) | Auto-format code via `format-code.sh` |
|
|
| `SubagentStop` | Notify via `notify-subagent-done.sh` |
|
|
| `SessionEnd` | Save session memories via `cognitive-memory` |
|
|
|
|
## Permissions
|
|
|
|
Permission rules live in `~/.claude/settings.json` under `permissions.allow` and `permissions.deny`. Format: `ToolName(scope:pattern)`.
|
|
|
|
Common patterns:
|
|
- `"mcp__gitea-mcp__*"` — allow all gitea MCP tools
|
|
- `"WebFetch(domain:docs.example.com)"` — allow fetching from specific domain
|
|
- `"Bash(ssh:*)"` — allow SSH commands
|