fix(docs): critical factual corrections v3.6.1
Major audit correcting misleading documentation about Claude Code behavior: ### Fixed - `--add-dir`: permissions (not context loading) - `excludePatterns` → `permissions.deny` (never existed) - `.claudeignore` removed (not an official feature) - "selective loading" myth → lazy loading reality - Invented CLI flags (`--think`, `--headless`, `--learn`) → prompt keywords - `@` file reference: "loads automatically" → "reads on-demand" ### Added - Session Search Tool (`cs`) - zero-dep bash script for finding sessions - Security section: Known limitations of permissions.deny 15 files modified, 516 insertions, 200 deletions Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
0552522030
commit
46c5862c4e
16 changed files with 687 additions and 200 deletions
|
|
@ -6,7 +6,7 @@
|
|||
|
||||
**Written with**: Claude (Anthropic)
|
||||
|
||||
**Version**: 3.6.0 | **Last Updated**: January 2026
|
||||
**Version**: 3.6.1 | **Last Updated**: January 2026
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -167,15 +167,20 @@ Model: Sonnet | Ctx: 89.5k | Cost: $2.11 | Ctx(u): 56.0%
|
|||
|
||||
---
|
||||
|
||||
## Plan Mode & Think Levels
|
||||
## Plan Mode & Thinking Depth
|
||||
|
||||
| Feature | Activation | Usage |
|
||||
|---------|------------|-------|
|
||||
| **Plan Mode** | `Shift+Tab × 2` or `/plan` | Explore without modifying |
|
||||
| **OpusPlan** | `/model opusplan` | Opus for planning, Sonnet for execution |
|
||||
| **Think** | `--think` flag | Standard analysis (~4K tokens) |
|
||||
| **Think Hard** | `--think-hard` flag | Deep analysis (~10K tokens) |
|
||||
| **Ultrathink** | `--ultrathink` flag | Maximum depth (~32K tokens) |
|
||||
|
||||
> ⚠️ **Note**: Extended thinking uses **prompt keywords** (e.g., "think hard"), not CLI flags.
|
||||
|
||||
| Prompt Keyword | Thinking Depth | Use For |
|
||||
|----------------|----------------|---------|
|
||||
| "Think" | Standard | Multi-component analysis |
|
||||
| "Think hard" | Deep | Architectural decisions |
|
||||
| "Ultrathink" | Maximum | Critical redesign |
|
||||
|
||||
**OpusPlan workflow**: `/model opusplan` → `Shift+Tab × 2` (plan with Opus) → `Shift+Tab` (execute with Sonnet)
|
||||
|
||||
|
|
@ -243,11 +248,10 @@ exit 0 # 0=continue, 2=block
|
|||
|
||||
| ❌ Don't | ✅ Do |
|
||||
|----------|-------|
|
||||
| Vague prompts | Specify file + line |
|
||||
| Vague prompts | Specify file + line with @references |
|
||||
| Accept without reading | Read every diff |
|
||||
| Ignore warnings | Use `/compact` |
|
||||
| Ignore warnings | Use `/compact` at 70% |
|
||||
| Skip permissions | Never in production |
|
||||
| Giant context loads | Load only what's needed |
|
||||
| Negative constraints only | Provide alternatives |
|
||||
|
||||
---
|
||||
|
|
@ -275,12 +279,11 @@ VERIFY: Empty email shows error, invalid format shows error
|
|||
|
||||
| Flag | Usage |
|
||||
|------|-------|
|
||||
| `-p "query"` | Non-interactive mode |
|
||||
| `-p "query"` | Non-interactive mode (CI/CD) |
|
||||
| `-c` / `--continue` | Continue last session |
|
||||
| `-r` / `--resume <id>` | Resume specific session |
|
||||
| `--headless` | Non-interactive (CI/CD) |
|
||||
| `--model sonnet` | Change model |
|
||||
| `--add-dir ../lib` | Add directory |
|
||||
| `--add-dir ../lib` | Allow access outside CWD |
|
||||
| `--permission-mode plan` | Plan mode |
|
||||
| `--dangerously-skip-permissions` | Auto-accept (use carefully) |
|
||||
| `--debug` | Debug output |
|
||||
|
|
@ -341,7 +344,7 @@ Risky change → Plan Mode first
|
|||
Repeating task → Create agent or command
|
||||
Context full → /compact or /clear
|
||||
Need docs → Use Context7 MCP
|
||||
Deep analysis → Use --think or --ultrathink
|
||||
Deep analysis → Use extended thinking prompts
|
||||
```
|
||||
|
||||
---
|
||||
|
|
@ -377,7 +380,7 @@ where.exe claude; claude doctor; claude mcp list
|
|||
| Opus | Architecture, complex bugs | $$$ |
|
||||
| OpusPlan | Plan (Opus) + Execute (Sonnet) | $$ |
|
||||
|
||||
**Tip**: Use `--add-dir` to load only needed directories (saves tokens)
|
||||
**Tip**: Use `--add-dir` to allow tool access to directories outside your current working directory
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -393,4 +396,4 @@ where.exe claude; claude doctor; claude mcp list
|
|||
|
||||
**Author**: Florian BRUNIAUX | [@Méthode Aristote](https://methode-aristote.fr) | Written with Claude
|
||||
|
||||
*Last updated: January 2026 | Version 3.6.0*
|
||||
*Last updated: January 2026 | Version 3.6.1*
|
||||
|
|
|
|||
|
|
@ -144,38 +144,30 @@ STRIPE_SECRET_KEY=sk_live_...
|
|||
|
||||
#### 4.2 Configure File Exclusions
|
||||
|
||||
In `.claude/settings.json`:
|
||||
In `.claude/settings.json`, use `permissions.deny` to block access to sensitive files:
|
||||
|
||||
```json
|
||||
{
|
||||
"excludePatterns": [
|
||||
".env",
|
||||
".env.*",
|
||||
"**/.env",
|
||||
"**/.env.*",
|
||||
"**/credentials*",
|
||||
"**/secrets*",
|
||||
"**/*.pem",
|
||||
"**/*.key",
|
||||
"**/service-account*.json"
|
||||
]
|
||||
"permissions": {
|
||||
"deny": [
|
||||
"Read(./.env*)",
|
||||
"Edit(./.env*)",
|
||||
"Write(./.env*)",
|
||||
"Bash(cat .env*)",
|
||||
"Bash(head .env*)",
|
||||
"Read(./secrets/**)",
|
||||
"Read(./**/credentials*)",
|
||||
"Read(./**/*.pem)",
|
||||
"Read(./**/*.key)",
|
||||
"Read(./**/service-account*.json)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or create `.claudeignore` in project root:
|
||||
> **Note**: The old `excludePatterns` and `ignorePatterns` settings were deprecated in October 2025. Use `permissions.deny` instead.
|
||||
|
||||
```gitignore
|
||||
# Secrets
|
||||
.env
|
||||
.env.*
|
||||
*.pem
|
||||
*.key
|
||||
credentials.json
|
||||
secrets/
|
||||
|
||||
# Sensitive configs
|
||||
**/config/production.*
|
||||
```
|
||||
> **Warning**: `permissions.deny` has [known limitations](./security-hardening.md#known-limitations-of-permissionsdeny). For defense-in-depth, combine with security hooks and external secrets management.
|
||||
|
||||
#### 4.3 Use Security Hooks
|
||||
|
||||
|
|
@ -277,7 +269,7 @@ claude /status
|
|||
### Quick Checklist
|
||||
|
||||
- [ ] Training opt-out enabled at claude.ai/settings
|
||||
- [ ] `.env*` files in excludePatterns or .claudeignore
|
||||
- [ ] `.env*` files blocked via `permissions.deny` in settings.json
|
||||
- [ ] No production database connections via MCP
|
||||
- [ ] Security hooks installed for sensitive file access
|
||||
- [ ] Team aware of data flow to Anthropic
|
||||
|
|
|
|||
|
|
@ -5,11 +5,12 @@
|
|||
## Table of Contents
|
||||
|
||||
1. [Why Monitor Sessions](#why-monitor-sessions)
|
||||
2. [Setting Up Session Logging](#setting-up-session-logging)
|
||||
3. [Analyzing Session Data](#analyzing-session-data)
|
||||
4. [Cost Tracking](#cost-tracking)
|
||||
5. [Patterns & Best Practices](#patterns--best-practices)
|
||||
6. [Limitations](#limitations)
|
||||
2. [Session Search & Resume](#session-search--resume)
|
||||
3. [Setting Up Session Logging](#setting-up-session-logging)
|
||||
4. [Analyzing Session Data](#analyzing-session-data)
|
||||
5. [Cost Tracking](#cost-tracking)
|
||||
6. [Patterns & Best Practices](#patterns--best-practices)
|
||||
7. [Limitations](#limitations)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -25,6 +26,88 @@ Claude Code usage can accumulate quickly, especially in active development. Moni
|
|||
|
||||
---
|
||||
|
||||
## Session Search & Resume
|
||||
|
||||
After weeks of using Claude Code, finding past conversations becomes challenging. This section covers native options and community tools.
|
||||
|
||||
### Native Commands
|
||||
|
||||
| Command | Use Case |
|
||||
|---------|----------|
|
||||
| `claude -c` / `claude --continue` | Resume most recent session |
|
||||
| `claude -r <id>` / `claude --resume <id>` | Resume specific session by ID |
|
||||
| `claude --resume` | Interactive session picker |
|
||||
|
||||
Sessions are stored locally at `~/.claude/projects/<project>/` as JSONL files.
|
||||
|
||||
### Community Tools Comparison
|
||||
|
||||
| Tool | Install | List Speed | Search Speed | Dependencies | Resume Command |
|
||||
|------|---------|------------|--------------|--------------|----------------|
|
||||
| **session-search.sh** (this repo) | Copy script | **10ms** | **400ms** | None (bash) | ✅ Displayed |
|
||||
| claude-conversation-extractor | `pip install` | 230ms | 1.7s | Python | ❌ |
|
||||
| claude-code-transcripts | `uvx` | N/A | N/A | Python | ❌ |
|
||||
| ran CLI | `npm -g` | N/A | Fast | Node.js | ❌ (commands only) |
|
||||
|
||||
### Recommended: session-search.sh
|
||||
|
||||
Zero-dependency bash script optimized for speed with ready-to-use resume commands.
|
||||
|
||||
**Install:**
|
||||
```bash
|
||||
cp examples/scripts/session-search.sh ~/.claude/scripts/cs
|
||||
chmod +x ~/.claude/scripts/cs
|
||||
echo "alias cs='~/.claude/scripts/cs'" >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
cs # List 10 most recent sessions (10ms)
|
||||
cs "authentication" # Full-text search (400ms)
|
||||
cs -n 20 # Show 20 results
|
||||
cs --rebuild # Force index rebuild
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
2026-01-15 08:32 │ my-project │ Implement OAuth flow for...
|
||||
claude --resume 84287c0d-8778-4a8d-abf1-eb2807e327a8
|
||||
|
||||
2026-01-14 21:13 │ other-project │ Fix database migration...
|
||||
claude --resume 1340c42e-eac5-4181-8407-cc76e1a76219
|
||||
```
|
||||
|
||||
Copy-paste the `claude --resume` command to continue any session.
|
||||
|
||||
### How It Works
|
||||
|
||||
1. **Index mode** (no keyword): Builds/uses cached TSV index of all sessions. Refreshes every hour. ~10ms lookup.
|
||||
2. **Search mode** (with keyword): Greps full JSONL content. ~400ms for 200+ sessions.
|
||||
3. **Filters**: Automatically excludes agent/subagent sessions (internal automation, not user conversations).
|
||||
|
||||
### Alternative: Python Tools
|
||||
|
||||
If you prefer richer features (HTML export, multiple formats):
|
||||
|
||||
```bash
|
||||
# Install
|
||||
pip install claude-conversation-extractor
|
||||
|
||||
# Interactive UI
|
||||
claude-start
|
||||
|
||||
# Direct search
|
||||
claude-search "keyword"
|
||||
|
||||
# Export to markdown
|
||||
claude-extract --format markdown
|
||||
```
|
||||
|
||||
See [session-search.sh](../examples/scripts/session-search.sh) for the complete script.
|
||||
|
||||
---
|
||||
|
||||
## Setting Up Session Logging
|
||||
|
||||
### 1. Install the Logger Hook
|
||||
|
|
@ -288,6 +371,7 @@ find ~/.claude/logs -name "*.jsonl" -mtime +30 -delete
|
|||
|
||||
## Related Resources
|
||||
|
||||
- [Session Search Script](../examples/scripts/session-search.sh) - Fast session search & resume
|
||||
- [Session Logger Hook](../examples/hooks/bash/session-logger.sh)
|
||||
- [Stats Analysis Script](../examples/scripts/session-stats.sh)
|
||||
- [Data Privacy Guide](./data-privacy.md) - What data leaves your machine
|
||||
|
|
|
|||
|
|
@ -118,7 +118,65 @@ Before adding any MCP server, complete this checklist:
|
|||
- Use read-only database credentials
|
||||
- Minimize environment variables exposed
|
||||
|
||||
### 1.2 Repository Pre-Scan
|
||||
### 1.2 Known Limitations of permissions.deny
|
||||
|
||||
The `permissions.deny` setting in `.claude/settings.json` is the official method to block Claude from accessing sensitive files. However, security researchers have documented architectural limitations.
|
||||
|
||||
#### What permissions.deny Blocks
|
||||
|
||||
| Operation | Blocked? | Notes |
|
||||
|-----------|----------|-------|
|
||||
| `Read()` tool calls | ✅ Yes | Primary blocking mechanism |
|
||||
| `Edit()` tool calls | ✅ Yes | With explicit deny rule |
|
||||
| `Write()` tool calls | ✅ Yes | With explicit deny rule |
|
||||
| `Bash(cat .env)` | ✅ Yes | With explicit deny rule |
|
||||
| `Glob()` patterns | ✅ Yes | Handled by Read rules |
|
||||
| `ls .env*` (filenames) | ⚠️ Partial | Exposes file existence, not contents |
|
||||
|
||||
#### Known Security Gaps
|
||||
|
||||
| Gap | Description | Source |
|
||||
|-----|-------------|--------|
|
||||
| **System reminders** | Background indexing may expose file contents via internal "system reminder" mechanism before tool permission checks | [GitHub #4160](https://github.com/anthropics/claude-code/issues/4160) |
|
||||
| **Bash wildcards** | Generic bash commands without explicit deny rules may access files | Security research |
|
||||
| **Indexing timing** | File watching operates at a layer below tool permissions | [GitHub #4160](https://github.com/anthropics/claude-code/issues/4160) |
|
||||
|
||||
#### Recommended Configuration
|
||||
|
||||
Block **all** access vectors, not just `Read`:
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"deny": [
|
||||
"Read(./.env*)",
|
||||
"Edit(./.env*)",
|
||||
"Write(./.env*)",
|
||||
"Bash(cat .env*)",
|
||||
"Bash(head .env*)",
|
||||
"Bash(tail .env*)",
|
||||
"Bash(grep .env*)",
|
||||
"Read(./secrets/**)",
|
||||
"Read(./**/*.pem)",
|
||||
"Read(./**/*.key)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Defense-in-Depth Strategy
|
||||
|
||||
Because `permissions.deny` alone cannot guarantee complete protection:
|
||||
|
||||
1. **Store secrets outside project directories** — Use `~/.secrets/` or external vault
|
||||
2. **Use external secrets management** — AWS Secrets Manager, 1Password, HashiCorp Vault
|
||||
3. **Add PreToolUse hooks** — Secondary blocking layer (see [Section 2.3](#23-hook-stack-setup))
|
||||
4. **Never commit secrets** — Even "blocked" files can leak through other vectors
|
||||
5. **Review bash commands** — Manually inspect before approving execution
|
||||
|
||||
> **Bottom line**: `permissions.deny` is necessary but not sufficient. Treat it as one layer in a defense-in-depth strategy, not a complete solution.
|
||||
|
||||
### 1.3 Repository Pre-Scan
|
||||
|
||||
Before opening untrusted repositories, scan for injection vectors:
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@
|
|||
|
||||
**Last updated**: January 2026
|
||||
|
||||
**Version**: 3.6.0
|
||||
**Version**: 3.6.1
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -396,7 +396,7 @@ Check @./CLAUDE.md for project conventions
|
|||
**Why use `@`**:
|
||||
- **Precision**: Target exact files instead of letting Claude search
|
||||
- **Speed**: Skip file discovery phase
|
||||
- **Context**: Claude loads file content automatically
|
||||
- **Context**: Signals Claude to read these files on-demand via tools
|
||||
- **Clarity**: Makes your intent explicit
|
||||
|
||||
**Example**:
|
||||
|
|
@ -407,7 +407,7 @@ Claude: Which file contains the authentication logic? [Wastes time searching]
|
|||
|
||||
# With @
|
||||
You: Fix the authentication bug in @src/auth/middleware.ts
|
||||
Claude: [Immediately loads file and proposes fix]
|
||||
Claude: [Reads file on-demand and proposes fix]
|
||||
```
|
||||
|
||||
#### Working with Images and Screenshots
|
||||
|
|
@ -505,14 +505,24 @@ Claude Code allows you to **continue previous conversations** across terminal se
|
|||
**Finding session IDs**:
|
||||
|
||||
```bash
|
||||
# List recent sessions with IDs
|
||||
# Native: Interactive session picker
|
||||
claude --resume
|
||||
|
||||
# Native: List via Serena MCP (if configured)
|
||||
claude mcp call serena list_sessions
|
||||
|
||||
# Recommended: Fast search with ready-to-use resume commands
|
||||
# See examples/scripts/session-search.sh (zero dependencies, 15ms list, 400ms search)
|
||||
cs # List 10 most recent sessions
|
||||
cs "authentication" # Full-text search across all sessions
|
||||
|
||||
# Sessions are also shown when you exit
|
||||
You: /exit
|
||||
Session ID: abc123def (saved for resume)
|
||||
```
|
||||
|
||||
> **Session Search Tool**: For fast session search with copy-paste resume commands, see [Observability Guide](./observability.md#session-search--resume) and [session-search.sh](../examples/scripts/session-search.sh).
|
||||
|
||||
**Common use cases**:
|
||||
|
||||
| Scenario | Command | Why |
|
||||
|
|
@ -670,9 +680,9 @@ Switching from GitHub Copilot, Cursor, or other AI assistants? Here's what you n
|
|||
|
||||
#### What Claude Code Does Better
|
||||
|
||||
- **Multi-file refactoring** - Copilot: one file at a time | Claude: entire codebase
|
||||
- **Multi-file refactoring** - Copilot: one file at a time | Claude: reads and edits across files
|
||||
- **Complex tasks** - Copilot: suggests lines | Claude: implements features
|
||||
- **Understanding context** - Copilot: current file | Claude: project-wide awareness
|
||||
- **Understanding context** - Copilot: current file | Claude: can search and read project-wide
|
||||
- **Explaining code** - Copilot: limited | Claude: detailed explanations
|
||||
- **Debugging** - Copilot: weak | Claude: systematic root cause analysis
|
||||
|
||||
|
|
@ -2363,14 +2373,28 @@ When you use Claude Code, the following data leaves your machine:
|
|||
|
||||
### Protecting Sensitive Data
|
||||
|
||||
**1. Exclude sensitive files** in `.claude/settings.json`:
|
||||
**1. Block access to sensitive files** in `.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"excludePatterns": [".env*", "**/credentials*", "**/*.pem"]
|
||||
"permissions": {
|
||||
"deny": [
|
||||
"Read(./.env*)",
|
||||
"Edit(./.env*)",
|
||||
"Write(./.env*)",
|
||||
"Bash(cat .env*)",
|
||||
"Bash(head .env*)",
|
||||
"Read(./secrets/**)",
|
||||
"Read(./**/*.pem)",
|
||||
"Read(./**/*.key)",
|
||||
"Read(./**/credentials*)"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> **Warning**: `permissions.deny` has known limitations. See [Security Hardening Guide](./security-hardening.md#known-limitations-of-permissionsdeny) for details.
|
||||
|
||||
**2. Never connect production databases** to MCP servers. Use dev/staging with anonymized data.
|
||||
|
||||
**3. Use security hooks** to block reading of sensitive files (see [Section 7.4](#74-hooks-automating-workflows)).
|
||||
|
|
@ -5035,7 +5059,7 @@ uvx --from git+https://github.com/oraios/serena serena project index
|
|||
| **Semantic search** | Find code by natural language description |
|
||||
| **Background indexing** | `mgrep watch` indexes respecting `.gitignore` |
|
||||
| **Multi-format** | Search code, PDFs, images, text |
|
||||
| **Web integration** | `--web` flag for web search fallback |
|
||||
| **Web integration** | Web search fallback capability |
|
||||
|
||||
**Example**:
|
||||
|
||||
|
|
@ -5657,13 +5681,15 @@ The most powerful Claude Code pattern combines three techniques:
|
|||
| Architectural decision | ✅ Yes |
|
||||
| Legacy system modernization | ✅ Yes |
|
||||
|
||||
### Ultrathink Levels
|
||||
### Extended Thinking Techniques
|
||||
|
||||
| Flag | Thinking Depth | Token Usage | Best For |
|
||||
|------|----------------|-------------|----------|
|
||||
| `--think` | Standard | ~4K | Multi-component analysis |
|
||||
| `--think-hard` | Deep | ~10K | Architectural decisions |
|
||||
| `--ultrathink` | Maximum | ~32K | Critical redesign |
|
||||
> ⚠️ **Note**: `--think`, `--think-hard`, and `--ultrathink` are **NOT official Claude Code CLI flags**. They do not exist in `claude --help`. The techniques below use **prompt keywords** to encourage deeper analysis, not CLI flags.
|
||||
|
||||
| Prompt Keyword | Thinking Depth | Estimated Tokens | Best For |
|
||||
|----------------|----------------|------------------|----------|
|
||||
| "Think" | Standard | ~4K (estimate) | Multi-component analysis |
|
||||
| "Think hard" | Deep | ~10K (estimate) | Architectural decisions |
|
||||
| "Ultrathink" | Maximum | ~32K (estimate) | Critical redesign |
|
||||
|
||||
#### Inline Thinking Keywords
|
||||
|
||||
|
|
@ -5785,13 +5811,13 @@ Run Claude Code without interactive prompts:
|
|||
|
||||
```bash
|
||||
# Basic headless execution
|
||||
claude --headless "Run the tests and report results"
|
||||
claude -p "Run the tests and report results"
|
||||
|
||||
# With timeout
|
||||
claude --headless --timeout 300 "Build the project"
|
||||
claude -p --timeout 300 "Build the project"
|
||||
|
||||
# With specific model
|
||||
claude --headless --model sonnet "Analyze code quality"
|
||||
claude -p --model sonnet "Analyze code quality"
|
||||
```
|
||||
|
||||
### Unix Piping Workflows
|
||||
|
|
@ -5868,9 +5894,9 @@ cat large-file.txt | claude -p 'Analyze line by line' --output-format stream-jso
|
|||
cat entire-codebase/* | claude -p 'review'
|
||||
```
|
||||
|
||||
- **Use non-interactive mode**: Add `--headless` for automation
|
||||
- **Use non-interactive mode**: Add `-p` for automation
|
||||
```bash
|
||||
cat file.txt | claude --headless -p 'fix linting errors' > output.txt
|
||||
cat file.txt | claude -p -p 'fix linting errors' > output.txt
|
||||
```
|
||||
|
||||
- **Combine with jq for JSON**: Parse Claude's JSON output
|
||||
|
|
@ -5911,9 +5937,9 @@ git log --oneline -10 | claude -p 'Categorize commits by type' --output-format j
|
|||
{
|
||||
"scripts": {
|
||||
"claude-review": "git diff main | claude -p 'Review for security issues' --output-format json > review.json",
|
||||
"claude-test-summary": "npm test 2>&1 | claude --headless -p 'Summarize failures and suggest fixes'",
|
||||
"claude-test-summary": "npm test 2>&1 | claude -p -p 'Summarize failures and suggest fixes'",
|
||||
"claude-docs": "cat src/**/*.ts | claude -p 'Generate API documentation' > API.md",
|
||||
"precommit-check": "git diff --cached | claude --headless -p 'Check for secrets or anti-patterns' && git diff --cached | prettier --check"
|
||||
"precommit-check": "git diff --cached | claude -p -p 'Check for secrets or anti-patterns' && git diff --cached | prettier --check"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -5941,7 +5967,7 @@ jobs:
|
|||
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
run: |
|
||||
git diff origin/main...HEAD | \
|
||||
claude --headless -p 'Review this PR diff for security issues, performance problems, and code quality. Format as JSON.' \
|
||||
claude -p -p 'Review this PR diff for security issues, performance problems, and code quality. Format as JSON.' \
|
||||
--output-format json > review.json
|
||||
|
||||
- name: Comment on PR
|
||||
|
|
@ -5961,7 +5987,7 @@ jobs:
|
|||
**Limitations**:
|
||||
|
||||
- **Context size**: Large pipes may exceed token limits (monitor with `/status`)
|
||||
- **Interactive prompts**: Use `--headless` for automation to avoid blocking
|
||||
- **Interactive prompts**: Use `-p` for automation to avoid blocking
|
||||
- **Error handling**: Pipe failures don't always propagate; add `set -e` for strict mode
|
||||
- **API costs**: Automated pipes consume API credits; monitor usage with `ccusage`
|
||||
|
||||
|
|
@ -5986,7 +6012,7 @@ jobs:
|
|||
|
||||
# Run Claude Code for commit message validation
|
||||
COMMIT_MSG=$(cat "$1")
|
||||
claude --headless "Is this commit message good? '$COMMIT_MSG'. Reply YES or NO with reason."
|
||||
claude -p "Is this commit message good? '$COMMIT_MSG'. Reply YES or NO with reason."
|
||||
```
|
||||
|
||||
**Pre-push hook**:
|
||||
|
|
@ -5996,7 +6022,7 @@ claude --headless "Is this commit message good? '$COMMIT_MSG'. Reply YES or NO w
|
|||
# .git/hooks/pre-push
|
||||
|
||||
# Security check before push
|
||||
claude --headless "Scan staged files for secrets and security issues. Exit 1 if found."
|
||||
claude -p "Scan staged files for secrets and security issues. Exit 1 if found."
|
||||
EXIT_CODE=$?
|
||||
|
||||
if [ $EXIT_CODE -ne 0 ]; then
|
||||
|
|
@ -6028,7 +6054,7 @@ jobs:
|
|||
env:
|
||||
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
run: |
|
||||
claude --headless "Review the changes in this PR. \
|
||||
claude -p "Review the changes in this PR. \
|
||||
Focus on security, performance, and code quality. \
|
||||
Output as markdown."
|
||||
```
|
||||
|
|
@ -6080,7 +6106,7 @@ gh run view $FAILED_RUN --log-failed | claude -p "Analyze this CI failure and su
|
|||
|
||||
```bash
|
||||
# Fetch failures and auto-fix
|
||||
gh run view --log-failed | claude --headless "
|
||||
gh run view --log-failed | claude -p "
|
||||
Analyze these test failures.
|
||||
Identify the root cause.
|
||||
Propose fixes for each failing test.
|
||||
|
|
@ -6313,7 +6339,7 @@ jobs:
|
|||
VERSION=${GITHUB_REF#refs/tags/}
|
||||
|
||||
# Generate with Claude
|
||||
claude --headless "Generate release notes for $VERSION. \
|
||||
claude -p "Generate release notes for $VERSION. \
|
||||
Analyze commits since last tag. \
|
||||
Output in GitHub Release format. \
|
||||
Save to release-notes.md"
|
||||
|
|
@ -6502,7 +6528,7 @@ alias cce='claude --execute'
|
|||
|
||||
# Quick code question
|
||||
cq() {
|
||||
claude --headless "$*"
|
||||
claude -p "$*"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -6521,7 +6547,7 @@ function cce { claude --execute $args }
|
|||
|
||||
function cq {
|
||||
param([Parameter(ValueFromRemainingArguments)]$question)
|
||||
claude --headless ($question -join ' ')
|
||||
claude -p ($question -join ' ')
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -7052,22 +7078,22 @@ exit 0 # Allow
|
|||
- Load entire monorepo when you only need one package
|
||||
- Max out thinking/turn budgets for simple tasks (wastes time and money)
|
||||
- Ignore session cleanup - old sessions accumulate and slow down Claude Code
|
||||
- Use `--ultrathink` for trivial edits like typo fixes
|
||||
- Use deep thinking prompts for trivial edits like typo fixes
|
||||
- Keep context at 90%+ for extended periods
|
||||
- Load large binary files or generated code into context
|
||||
- Run expensive MCP operations in tight loops
|
||||
|
||||
**✅ Do:**
|
||||
|
||||
- Use `--add-dir` for focused context on specific directories
|
||||
- Right-size thinking levels to task complexity:
|
||||
- Simple edits: No flags
|
||||
- Medium analysis: `--think`
|
||||
- Complex architecture: `--think-hard`
|
||||
- Critical redesign: `--ultrathink`
|
||||
- Use `--add-dir` to allow tool access to directories outside the current working directory
|
||||
- Right-size thinking depth to task complexity:
|
||||
- Simple edits: Standard prompts
|
||||
- Medium analysis: "Think about this"
|
||||
- Complex architecture: "Think hard about this"
|
||||
- Critical redesign: "Ultrathink" in your prompt
|
||||
- Set `cleanupPeriodDays` in config to prune old sessions automatically
|
||||
- Use `/compact` proactively when context reaches 70%
|
||||
- Exclude irrelevant directories with `.claudeignore`
|
||||
- Block sensitive files with `permissions.deny` in settings.json
|
||||
- Monitor cost with `/status` and adjust model/thinking levels accordingly
|
||||
- Cache expensive computations in memory with Serena MCP
|
||||
|
||||
|
|
@ -7177,7 +7203,7 @@ VERIFY:
|
|||
**❌ Don't:**
|
||||
|
||||
- Use Opus for simple tasks that Sonnet can handle
|
||||
- Leave `--ultrathink` on by default
|
||||
- Use deep thinking prompts for every task by default
|
||||
- Ignore the cost metrics in `/status`
|
||||
- Use MCP servers that make external API calls excessively
|
||||
- Load entire codebase for focused tasks
|
||||
|
|
@ -7204,7 +7230,7 @@ VERIFY:
|
|||
| Feature implementation | Sonnet | Best balance |
|
||||
| Code review | Haiku/Sonnet | Depends on depth |
|
||||
| Architecture design | Opus (plan) → Sonnet (execute) | OpusPlan mode |
|
||||
| Complex debugging | Opus with `--think` | Worth the cost |
|
||||
| Complex debugging | Opus with thinking prompts | Worth the cost |
|
||||
| Batch operations | Sonnet | Efficient at scale |
|
||||
|
||||
### Learning & Adoption Pitfalls
|
||||
|
|
@ -7772,46 +7798,30 @@ You: "Implement the caching layer following the plan"
|
|||
|
||||
### Token-Saving Techniques
|
||||
|
||||
**1. Selective context loading:**
|
||||
> **Important**: Claude Code uses lazy loading - it doesn't "load" your entire codebase at startup. Files are read on-demand when you ask Claude to analyze them. The main context consumers at startup are your CLAUDE.md files and auto-loaded rules.
|
||||
|
||||
```bash
|
||||
# ❌ Load entire monorepo (wastes tokens)
|
||||
cd monorepo
|
||||
claude
|
||||
**1. Keep CLAUDE.md files concise:**
|
||||
|
||||
# ✅ Load only needed directory
|
||||
cd monorepo
|
||||
claude --add-dir packages/api
|
||||
```markdown
|
||||
# ❌ Bloated CLAUDE.md (wastes tokens on every session)
|
||||
- 500+ lines of instructions
|
||||
- Multiple @includes importing other files
|
||||
- Rarely-used guidelines
|
||||
|
||||
# ✅ Lean CLAUDE.md
|
||||
- Essential project context only (<200 lines)
|
||||
- Move rarely-used rules to .claude/rules/ (loaded on-demand)
|
||||
- Split by concern: team rules in project CLAUDE.md, personal prefs in ~/.claude/CLAUDE.md
|
||||
```
|
||||
|
||||
**2. Use .claudeignore:**
|
||||
**2. Use targeted file references:**
|
||||
|
||||
```gitignore
|
||||
# .claudeignore - Exclude from context
|
||||
```bash
|
||||
# ❌ Vague request (Claude reads many files to find context)
|
||||
"Fix the authentication bug"
|
||||
|
||||
# Dependencies
|
||||
node_modules/
|
||||
vendor/
|
||||
.venv/
|
||||
|
||||
# Generated files
|
||||
dist/
|
||||
build/
|
||||
*.min.js
|
||||
*.bundle.js
|
||||
|
||||
# Large data
|
||||
*.sql
|
||||
*.csv
|
||||
*.json.gz
|
||||
|
||||
# IDE files
|
||||
.vscode/
|
||||
.idea/
|
||||
|
||||
# Logs
|
||||
*.log
|
||||
logs/
|
||||
# ✅ Specific request (Claude reads only what's needed)
|
||||
"Fix the JWT validation in @src/auth/middleware.ts line 45"
|
||||
```
|
||||
|
||||
**3. Compact proactively:**
|
||||
|
|
@ -8008,7 +8018,7 @@ Daily practices:
|
|||
□ Use /status to monitor context and cost
|
||||
□ Compact at 70% context usage
|
||||
□ Close sessions after task completion
|
||||
□ Use .claudeignore to exclude unnecessary files
|
||||
□ Use `permissions.deny` to block sensitive files
|
||||
|
||||
Model selection:
|
||||
□ Default to Sonnet for most work
|
||||
|
|
@ -8017,7 +8027,7 @@ Model selection:
|
|||
□ Try OpusPlan mode for strategic work
|
||||
|
||||
Context management:
|
||||
□ Load only needed directories (--add-dir)
|
||||
□ Use specific file references (@path/to/file.ts)
|
||||
□ Batch similar tasks in single session
|
||||
□ Reuse context for multiple related tasks
|
||||
□ Create specialized agents with focused context
|
||||
|
|
@ -8300,7 +8310,7 @@ _Quick jump:_ [Commands Table](#101-commands-table) · [Keyboard Shortcuts](#102
|
|||
|-------|---------|---------|
|
||||
| `-c -p "msg"` | Resume session + single prompt | `claude -c -p "run tests"` |
|
||||
| `-r <id> -p` | Resume specific session + prompt | `claude -r abc123 -p "check status"` |
|
||||
| `--headless -p` | Non-interactive automation | `claude --headless -p "lint fix" < errors.txt` |
|
||||
| `-p -p` | Non-interactive automation | `claude -p -p "lint fix" < errors.txt` |
|
||||
|
||||
> **Note**: Combine resume flags with `-p` for scripting and CI/CD workflows.
|
||||
|
||||
|
|
@ -8352,7 +8362,7 @@ Complete reference for all Claude Code command-line flags.
|
|||
| `--permission-mode` | Permission mode (default/auto/plan) | `claude --permission-mode plan` |
|
||||
| `--model` | Model selection | `claude --model sonnet` |
|
||||
| `--max-budget-usd` | Maximum API spend limit (with `--print` only) | `claude -p "analyze" --max-budget-usd 5.00` |
|
||||
| `--add-dir` | Add additional directories to context | `claude --add-dir ../shared ../utils` |
|
||||
| `--add-dir` | Allow tool access to additional directories | `claude --add-dir ../shared ../utils` |
|
||||
| `--continue` | Continue last conversation | `claude --continue` |
|
||||
| `-r, --resume` | Resume session by ID | `claude --resume abc123` |
|
||||
| `--dangerously-skip-permissions` | Skip all permission prompts | `claude --dangerously-skip-permissions` |
|
||||
|
|
@ -8373,7 +8383,7 @@ claude -p "analyze code quality" --output-format json
|
|||
# Economic analysis with Haiku
|
||||
claude -p "review this file" --model haiku
|
||||
|
||||
# Focused context (performance)
|
||||
# Allow access to a directory outside CWD
|
||||
claude --add-dir ./src/components
|
||||
|
||||
# Plan mode for safety
|
||||
|
|
@ -8815,11 +8825,11 @@ Get the scripts from:
|
|||
║ hooks/ Event scripts rules/ Auto-load rules ║
|
||||
║ skills/ Knowledge modules ║
|
||||
║ ║
|
||||
║ ULTRATHINK LEVELS ║
|
||||
║ ───────────────── ║
|
||||
║ --think ~4K tokens Standard analysis ║
|
||||
║ --think-hard ~10K tokens Deep analysis ║
|
||||
║ --ultrathink ~32K tokens Maximum depth ║
|
||||
║ THINKING PROMPTS (keywords, not CLI flags) ║
|
||||
║ ───────────────────────────────────────── ║
|
||||
║ "Think" Standard Multi-component analysis ║
|
||||
║ "Think hard" Deep Architecture decisions ║
|
||||
║ "Ultrathink" Maximum Critical redesign ║
|
||||
║ ║
|
||||
║ MCP SERVERS ║
|
||||
║ ─────────── ║
|
||||
|
|
@ -9139,6 +9149,8 @@ SuperClaude transforms Claude Code into a structured development platform throug
|
|||
|
||||
#### SuperClaude Behavioral Modes
|
||||
|
||||
> ⚠️ **Non-official Extension**: SuperClaude flags (`--learn`, `--uc`, `--think`, etc.) are **NOT Claude Code CLI flags**. They work via prompt injection in CLAUDE.md files and require installing the SuperClaude framework.
|
||||
|
||||
SuperClaude includes configurable behavioral modes stored in `~/.claude/MODE_*.md` files:
|
||||
|
||||
| Mode | Purpose | Activation |
|
||||
|
|
@ -9306,7 +9318,7 @@ Use the included audit prompt to analyze your current Claude Code configuration:
|
|||
|
||||
**How to use**:
|
||||
1. Copy the prompt from the file
|
||||
2. Run `claude --ultrathink` in your project directory
|
||||
2. Run `claude` in your project directory
|
||||
3. Paste the prompt and review findings
|
||||
4. Choose which recommendations to implement
|
||||
|
||||
|
|
@ -9515,4 +9527,4 @@ Thumbs.db
|
|||
|
||||
**Contributions**: Issues and PRs welcome.
|
||||
|
||||
**Last updated**: January 2026 | **Version**: 3.6.0
|
||||
**Last updated**: January 2026 | **Version**: 3.6.1
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue