# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Container Setup

This repository is configured with a secure development container based on Anthropic's reference devcontainer setup. The container provides:

- **Isolated environment**: Containerized Claude Code CLI with firewall restrictions
- **Security features**: Network access limited to whitelisted domains (GitHub, npm, Anthropic APIs, etc.)
- **Pre-configured tools**: Node.js 20, Claude Code CLI, git-delta, zsh with powerline10k, fzf, and more
- **Persistent storage**: Volumes for bash history and Claude configuration

### Opening in DevContainer

**Option 1: Using run-container.sh script (easiest for non-interactive usage)**

The repository includes a helper script for running Claude Code non-interactively:

```bash
# Make the script executable (first time only)
chmod +x run-container.sh

# Run with a prompt
./run-container.sh "explain the fibonacci sequence"

# Run with stdin
echo "create a hello world function in Python" | ./run-container.sh

# Analyze a file
./run-container.sh "explain this code" < myfile.js
```

The script automatically:
- Builds the Docker image if needed
- Creates persistent volumes for history and config
- Initializes the firewall
- Runs claude with streaming output and --dangerously-skip-permissions
- Cleans up the container after execution

**Option 2: Using devcontainer CLI (recommended for interactive development)**

Install the devcontainer CLI:
```bash
npm install -g @devcontainers/cli
```

Build and run the container:
```bash
# Build the container
devcontainer build --workspace-folder .

# Run the container and execute a command
devcontainer exec --workspace-folder . claude -p "your prompt" --dangerously-skip-permissions

# Or open an interactive shell
devcontainer exec --workspace-folder . zsh
```

**Option 3: Using Docker directly**

Build and run manually:
```bash
# Build the image
docker build -t claude-dev-container .devcontainer

# Create volumes for persistence
docker volume create claude-code-bashhistory
docker volume create claude-code-config

# Run interactively
docker run -it --rm \
  --cap-add=NET_ADMIN \
  --cap-add=NET_RAW \
  -v "$(pwd):/workspace" \
  -v claude-code-bashhistory:/commandhistory \
  -v claude-code-config:/home/node/.claude \
  -e NODE_OPTIONS="--max-old-space-size=4096" \
  -e CLAUDE_CONFIG_DIR="/home/node/.claude" \
  -w /workspace \
  --user node \
  claude-dev-container zsh

# Inside the container, initialize the firewall:
sudo /usr/local/bin/init-firewall.sh

# Then use Claude Code:
claude -p "your prompt" --dangerously-skip-permissions
```

**Option 4: VS Code**
1. Install the "Dev Containers" extension
2. Open this repository in VS Code
3. When prompted, click "Reopen in Container" (or use Command Palette: "Dev Containers: Reopen in Container")
4. Wait for the container to build and the firewall to initialize

**First-time setup:**
- You'll need to authenticate Claude Code on first use
- Run `claude` in the container terminal and follow the authentication prompts

### Running Claude Code Non-Interactively

The devcontainer's firewall allows running Claude Code with `--dangerously-skip-permissions` for non-interactive operation:

```bash
# Stream output in non-interactive mode
claude -p "your prompt here" --dangerously-skip-permissions

# Example: Analyze a file
claude -p "explain this code" --dangerously-skip-permissions < myfile.js

# Example: Generate code with streaming output
echo "create a fibonacci function" | claude -p --dangerously-skip-permissions
```

**Security notes:**
- The `--dangerously-skip-permissions` flag bypasses permission prompts
- This is safe within the devcontainer due to firewall restrictions
- Network access is limited to: GitHub, npm registry, Anthropic APIs, VS Code services
- All other outbound connections are blocked

### Container Configuration Files

- `.devcontainer/devcontainer.json` - Container and VS Code configuration
- `.devcontainer/Dockerfile` - Container image definition
- `.devcontainer/init-firewall.sh` - Network security rules (runs on container start)

### Environment Setup (Outside Container)

This repository uses [mise](https://mise.jdx.dev/) for tool version management.

- Node.js version: 24 (configured in `mise.toml`)
- Install tools: `mise install`