oam/knowledge base/ai/claude/claude code.md

Claude Code

Agentic coding tool that reads and edits files, runs commands, and integrates with tools.
Works in a terminal, IDE, browser, and as a desktop app.

1. TL;DR
2. Grant access to tools
3. Using skills
4. Limit tool execution
5. Memory
6. Using plugins
7. Delegating work
   1. Sub agents
   2. Agent teams
8. Run on local models
9. Further readings
   1. Sources

TL;DR

Claude can run in multiple shell sessions.
Prefer using git worktrees to isolate sessions in the same repository.

Fully multimodal.
Can access and understand images and other file types.
Can use tools, and do it in parallel.

Normally:

• Tied to Anthropic's Claude models (Sonnet and Opus).
• Requires a Claude API key or Anthropic plan.
  Usage is metered by the token.

Tip

One can use Claude Code router or Ollama to run on a locally server or shared LLM instead.

Uses a scope system to determine where configurations apply and who they're shared with.

Scope	Location	Area of effect	Shared
Managed (A.K.A. System)	System-level managed-settings.json	All users on the host	Yes (usually deployed by IT)
User	$HOME/.claude/ directory	Single user, across all projects	No
Project	.claude/ directory in a repository	All collaborators, repository only	Yes (usually committed to the repository)
Local	.claude/*.local.* files	Single user, repository only	No (usually gitignored)

The settings' schema is available on schemastore.org.
Config file example.

When multiple scopes are active, settings are merged as follows:

flowchart LR
  u("User") --> p("Project") --> l("Local") --> cli("CLI arguments") --> m("Managed")

Supports a plugin system for extending its capabilities.

Sends Statsig telemetry data by default. Includes operational metrics (latency, reliability, usage patterns).
Disable it by setting the DISABLE_TELEMETRY environment variable to 1.

Gives better results when asked to make a plan before writing code, and when tries multiple times (iterates).
Common workflows:

• Explore, plan, ask for confirmation, write code, commit.

  Example

  Figure out the root cause for issue #43, then propose possible fixes.
  Let me choose an approach before you write code.
  Ultrathink.

• Write tests, commit, write code, iterate, commit, push, create a PR.

  Example

  Write tests for @utils/markdown.ts to make sure links render properly.
  Note these tests will not pass yet since links are not yet implemented.
  Commit.
  Update the code to make the tests pass.
  Commit. Push. PR.

• Write code, screenshot the result, track progress, iterate.

  Example

  Implement [mock.png], then screenshot it with Puppeteer and iterate until it looks like the mock.
  Write down notes for yourself at every iteration. Think hard.

Hit esc once to stop Claude.
This action is usually safe. Claude will then resume or make things differently, but will have a context.

Prefer using Sonnet for quicker, smaller tasks (e.g. as sub-agent, greenfield coding, app initialization).
Consider using Opus for broader, longer, higher-level tasks (e.g. planning, refactoring, orchestrating sub-agents).
Consider using Haiku for quick responses.

Use memory and context files (CLAUDE.md) to instruct Claude Code on commands, style guidelines, and give it key context. Try to keep them small.

Consider allowing specific tools to reduce interruption and avoid fatigue due to too many requests.
Prefer using CLI tools over MCP servers.

Make sure to use /clear or /compact regularly to allow Claude to maintain focus on the conversation.
Or make it create notes to self and restart it once the context goes above a threshold (usually best at 60%).

Setup

brew install --cask 'claude-code'

Usage

# Start in interactive mode.
claude

# Run a one-time task.
claude "fix the build error"

# Run a one-off task, then exit.
claude -p 'Hi! Are you there?'
claude -p "explain the function in @someFunction.ts"
claude -p 'What did I do this week?' --allowedTools 'Bash(git log:*)' --output-format 'json'
cat 'minutes.md' | claude -p "summarize this"

# Resume the most recent conversation that happened in the current directory
claude -c

# Resume a previous conversation
claude -r

# Add MCP servers.
# Defaults to the 'local' scope if not specified.
claude mcp add --transport 'http' 'GitLab' 'https://some.local.gitlab.com/api/v4/mcp'
claude mcp add --transport 'http' 'linear' 'https://mcp.linear.app/mcp' --scope 'user'

# List configured MCP servers.
claude mcp list

# Show MCP servers' details
claude mcp get 'github'

# Remove MCP servers.
claude mcp remove 'github'

# Load local plugins.
claude --plugin-dir './path/to/plugin'

# Install plugins.
# Marketplace defaults to 'claude-plugins-official`.
# Scope defaults to 'user'.
claude plugin install 'gitlab'
claude plugin i 'aws-cost-saver@aws-cost-saver-marketplace' --scope 'project'

# List installed plugins only.
claude plugin list

# List all plugins.
claude plugin list --available --json

# Enable plugins.
claude plugin enable 'gitlab@claude-plugins-official'

# Disable plugins.
claude plugin disable 'gitlab@claude-plugins-official'

# Update plugins.
claude plugin update 'gitlab@claude-plugins-official'

From within Claude Code:

/mcp  manage MCP servers

Real world use cases

# Run Claude Code on a model served locally by Ollama.
ollama launch claude --model 'lfm2.5-thinking:1.2b'
ANTHROPIC_AUTH_TOKEN='ollama' ANTHROPIC_BASE_URL='http://localhost:11434' ANTHROPIC_API_KEY='' \
  claude --model 'lfm2.5-thinking:1.2b'

Grant access to tools

Add MCP servers to give Claude Code access to tools, databases, and APIs in general.

Caution

MCPs are not verified, nor otherwise checked for security issues.
Be especially careful when using MCP servers that cat fetch untrusted content, as they can fall victim of prompt injections.

Procedure:

1. Add the desired MCP server.

   Examples

   # Defaults to the 'local' scope if not specified.
   claude mcp add --transport 'http' 'GitLab' 'https://some.local.gitlab.com/api/v4/mcp'
   claude mcp add --transport 'http' 'linear' 'https://mcp.linear.app/mcp' --scope 'user'
   

2. From within Claude Code, run the /mcp command to configure it.

AWS API MCP server

Refer AWS API MCP Server.

Enables AI assistants to interact with AWS services and resources through AWS CLI commands.

Run as Docker container

Manually add the MCP server definition to $HOME/.claude.json:

{
  "mcpServers": {
    "aws-api": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--interactive",
        "--env",
        "AWS_REGION=eu-west-1",
        "--env",
        "AWS_API_MCP_TELEMETRY=false",
        "--env",
        "REQUIRE_MUTATION_CONSENT=true",
        "--env",
        "READ_OPERATIONS_ONLY=true",
        "--volume",
        "/Users/yourUserHere/.aws:/app/.aws",
        "public.ecr.aws/awslabs-mcp/awslabs/aws-api-mcp-server:latest"
      ]
    }
  }
}

AWS Cost Explorer MCP server

Refer Cost Explorer MCP Server.

Enables AI assistants to analyze AWS costs and usage data through the AWS Cost Explorer API.

Run as Docker container

FIXME: many of those environment variable are probably not necessary here.

Manually add the MCP server definition to $HOME/.claude.json:

{
  "mcpServers": {
    "aws-cost-explorer": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "--interactive",
        "--env",
        "AWS_REGION=eu-west-1",
        "--env",
        "AWS_API_MCP_TELEMETRY=false",
        "--env",
        "REQUIRE_MUTATION_CONSENT=true",
        "--env",
        "READ_OPERATIONS_ONLY=true",
        "--volume",
        "/Users/yourUserHere/.aws:/app/.aws",
        "public.ecr.aws/awslabs-mcp/awslabs/cost-explorer-mcp-server:latest"
      ]
    }
  }
}

Using skills

Refer Skills.
See also:

• Create custom skills.
• Prat011/awesome-llm-skills.

Claude Skills follow and extend the Agent Skills standard format.

Skills superseded commands.
Existing .claude/commands/ files will currently still work, but skills with the same name will take precedence.

Claude Code automatically discovers skills from:

• The user's $HOME/.claude/skills/ directory, and sets them up as user-level skills.
• A project's .claude/skills/ folder, and sets them up as project-level skills.
• A plugin's <plugin>/skills/ folder, if such plugin is enabled.

Whatever the scope, skills must follow the <scope-dir>/<skill-name>/SKILL.md tree format, e.g. $HOME/.claude/skills/aws-action/SKILL.md for a user-level skill.

User-level skills are available in all projects.
Project-level skills are limited to the current project.

Claude Code activates relevant skills automatically based on the request context.

When working with files in subdirectories, Claude Code automatically discovers skills from nested .claude/skills/ directories.

When skills share the same name across different scopes, the more specific scope wins (enterprise > personal > project > subdirectory).
Plugin skills use a plugin-name:skill-name namespace, so they cannot conflict with other levels.
Files in .claude/commands/ work the same way, but the skill will take precedence if a skill and a command share the same name.

Each skill is a directory, with the SKILL.md file as the entrypoint:

some-skill/
├── SKILL.md           # Main instructions (required)
├── template.md        # Template for Claude to fill in
├── examples/
│   └── sample.md      # Example output, showing its expected format
└── scripts/           # Scripts that Claude can execute
    └── validate.sh

The SKILL.md files contains a description of the skill and the main, essentials instructions that teach Claude how to use it.
This file is required. All other files are optional and are considered supporting files.
Optional files allow to specify more details and materials, like Large reference docs, API specifications, or example collections that do not need to be loaded into context every time the skill runs.
Reference optional files in SKILL.md to instruct Claude of what they contain and when to load them.

Tip

Prefer keeping SKILL.md under 500 lines. Move detailed reference material to supporting files.

Limit tool execution

Leverage Sandboxing to provide filesystem and network isolation for tool execution.
The sandboxed bash tool uses OS-level primitives to enforce defined boundaries upfront, and controls network access through a proxy server running outside the sandbox.
Attempts to access resources outside the sandbox trigger immediate notifications.

Warning

Effective sandboxing requires both filesystem and network isolation.
Without network isolation, compromised agents could exfiltrate sensitive files like SSH keys.
Without filesystem isolation, compromised agents could backdoor system resources to gain network access.
When configuring sandboxing, it is important to ensure that configured settings do not bypass these systems.

The sandboxed tool:

• Grants default read and write access to the current working directory and its subdirectories.
• Grants default read access to the entire computer, except specific denied directories.
• Blocks modifying files outside the current working directory without explicit permission.
• Allows defining custom allowed and denied paths through settings.
• Allows accessing only approved domains.
• Prompts the user when tools request access to new domains.
• Allows implementing custom rules on outgoing traffic.
• Applies restrictions to all scripts, programs, and subprocesses spawned by commands.

On Mac OS X, Claude Code uses the built-in Seatbelt framework. On Linux and WSL2, it requires installing containers/bubblewrap before activation.

Sandboxes can be configured to execute commands within the sandbox without requiring approval.
Commands that cannot be sandboxed fall back to the regular permission flow.

Customize sandbox behavior through the settings.json file.

Memory

Refer Manage Claude's memory.

Claude Code can save learnings, patterns, and insights gained during active sessions, and load them in a later sessions.

One can write and maintain CLAUDE.md Markdown files with instructions, rules, and preferences themselves (or ask Claude to do it on their behalf).
When auto memory is enabled, Claude automatically updates ~/.claude/projects/<project>/memory/MEMORY.md files. The first 200 lines of those are loaded at the start of every session.

Auto memory is enabled by default.
It can be disabled via the /memory toggle, settings.json, or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Memory hierarchy (from broadest to most specific):

Type	Location
Managed policy	/Library/Application Support/ClaudeCode/CLAUDE.md (macOS)
Project memory	./CLAUDE.md or ./.claude/CLAUDE.md
Project rules	./.claude/rules/*.md
User memory	~/.claude/CLAUDE.md
Project overrides	./CLAUDE.local.md
Auto memory	~/.claude/projects/<project>/memory/

Key commands:

Command	Summary
/memory	View, edit, or toggle auto memory on/off
/init	Bootstrap a CLAUDE.md file for the current project

Using plugins

Reusable packages that bundle Skills, agents, hooks, MCP servers, and LSP configurations.
They allow extending Claude Code's functionality, and sharing extensions across projects and teams.

Can be installed at all different scopes.

Commands

# Browse, install, enable/disable, or manage plugins
/plugin

# Load local plugins.
claude --plugin-dir './path/to/plugin'

# Install plugin marketplaces.
claude plugin marketplace add 'owner/repo'      # github
claude plugin marketplace add 'path/to/plugin'  # local

# Install plugins.
# Marketplace defaults to 'claude-plugins-official`.
# Scope defaults to 'user'.
claude plugin install 'gitlab'
claude plugin i 'aws-cost-saver@aws-cost-saver-marketplace' --scope 'project'

# List installed plugins only.
claude plugin list

# List all plugins.
claude plugin list --available --json

# Enable plugins.
claude plugin enable 'gitlab@claude-plugins-official'

# Disable plugins.
claude plugin disable 'gitlab@claude-plugins-official'

# Update plugins.
claude plugin update 'gitlab@claude-plugins-official'

# Uninstall plugins.
claude plugin uninstall 'gitlab@claude-plugins-official'

Delegating work

Agent teams generally perform parallel tasks in less time, but consume more tokens.
Sub agents currently consistently produce better quality output than teams.

Sub agents

Refer to Create custom subagents.

Specialized AI assistants that handle specific types of tasks.
Each runs in its own context window with a custom system prompt, specific tool access, and independent permissions.

When Claude encounters a task that matches a subagent's description, it delegates the task to that subagent.
It which works independently, and returns results once finished.

Most effective for sequential tasks, same-file edits, or tasks with many dependencies.
They only report results back to the main agent, and never talk to each other.

Claude Code includes several built-in subagents like Explore, Plan, and general-purpose.
One can create custom subagents to handle specific tasks.

Subagents are defined in Markdown files with YAML frontmatter.
Create them manually or use the /agents command.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

One can ask Claude to use subagents in sequence when dealing with multi-step workflows.
Each subagent completes its task and returns its results to Claude, which then passes relevant context to the next subagent.

Agent teams

Warning

Experimental feature as of 2026-03-02.

Refer to Orchestrate teams of Claude Code sessions.

Multiple Claude Code instances can work together as a team.
One session acts as the team lead and coordinates work, assigns tasks, and synthesizes results.
Teammates work independently, have their own context window, and communicate directly with each other.

One can interact with individual teammates directly, without going through the lead.

Most effective when teammates can operate independently.
They do exhibit coordination overhead, and use more tokens than a single session.

Currently disabled by default.
Enable them by setting the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to 1, either in a shell environment or through settings.json.

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Tell Claude to create an agent team, describing the task and the desired team structure in natural language.
Claude creates the team with a shared task list, spawns teammates for each task, coordinates work based on the prompt, and attempts to clean up the team when finished.

Note

The three roles are independent, so they can explore the problem without waiting on each other.

I'm designing a CLI tool that helps developers track TODO comments across their codebase.
Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, and one
playing devil's advocate.

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to each other to try to disprove each
other's theories, like a scientific debate.
Update the findings doc with whatever consensus emerges.

One can specify conditions and requirements in the prompt, like the number of teammates and wether they need to ask the lead for approval before acting.

When requiring approvals:

• Teammates work in read-only mode until they need to act.

• Once finished planning, teammates send a plan approval request to the lead.

• The lead reviews the plan, and either approves it or rejects it with feedback.

  Important

  The lead makes approval decisions autonomously.
  Give the lead criteria in the prompt to influence its judgment.

• If rejected, that teammate stays in plan mode, revises based on the feedback, and resubmits.

• Once approved, that teammate exits plan mode and begins implementation.

Gracefully end teammates' sessions by just asking the lead.
The lead sends them shutdown requests that the teammates can approve, exiting gracefully, or reject with an explanation.

Ask the researcher teammate to shut down

Clean up the team after termination by just asking the lead to clean up.
The lead will fails if any teammate is still running.

Run on local models

Claude can use other models and engines by setting the ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY environment variables.

E.g.:

# Run Claude Code on a model served locally by Ollama.
ANTHROPIC_AUTH_TOKEN='ollama' ANTHROPIC_BASE_URL='http://localhost:11434' ANTHROPIC_API_KEY='' \
  claude --model 'lfm2.5-thinking:1.2b'

Warning

Performances do tend to drop substantially depending on the context size and the executing host.

Examples

Prompt: Hi! Are you there?.
The model was run once right before the tests started to remove loading times.
Requests have been sent in headless mode (claude -p 'prompt').

glm-4.7-flash:q4_K_M on an M3 Pro MacBook Pro 36 GB

Model: glm-4.7-flash:q4_K_M.
Host: M3 Pro MacBook Pro 36 GB.
Claude Code version: v2.1.41.

Engine	Context	RAM usage	Used swap	Average response time	System remained responsive
llama.cpp (ollama)	4096	19 GB	No	19s	No
llama.cpp (ollama)	8192	19 GB	No	48s	No
llama.cpp (ollama)	16384	20 GB	No	2m 16s	No
llama.cpp (ollama)	32768	22 GB	No	7.12s	No
llama.cpp (ollama)	65536	25 GB	No? (unsure)	10.25s	Meh (minor stutters)
llama.cpp (ollama)	131072	33 GB	Yes	3m 42s	No (major stutters)

Further readings

• Website
• Codebase
• Blog
• AI agents
• Alternatives: Gemini CLI, OpenCode, Pi
• Claude Code router
• Settings
• Prat011/awesome-llm-skills
• Claude Skills vs. MCP: A Technical Comparison for AI Workflows

Sources

• Documentation
• pffigueiredo/claude-code-sheet.md
• Mastering Claude Code in 30 minutes by Boris Cherny, Anthropic