brandon/oam

Fork 0

mirror of https://gitea.com/mcereda/oam.git synced 2026-02-25 12:54:23 +00:00

Files

Michele Cereda e2cfa1d235 chore(kb/ai): review and expand notes

2026-02-20 22:20:45 +01:00

13 KiB

Raw Blame History

Claude Code

TODO

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.

TL;DR
Grant access to tools
Using skills
Limit tool execution
Memory
Run on local models
Further readings
1. Sources

TL;DR

Warning

Normally requires an Anthropic account to be used.
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.
When multiple scopes are active, the more specific ones take precedence.

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)

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 this function"

# 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' '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'

From within Claude Code:

/mcp

Real world use cases

# 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'

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:

Add the desired MCP server.

Examples

claude mcp add --transport 'http' 'linear' 'https://mcp.linear.app/mcp' --scope 'user'

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 unnecessary 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:

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

TODO

Refer Manage Claude's memory.

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)

13 KiB Raw Blame History