Claude Code & Cowork Integration

Claude Code gives developers an autonomous coding agent with terminal, filesystem, and git access. Claude Cowork takes the same agentic foundation and puts it in the hands of everyone else — marketing, ops, finance, HR, legal. Anyone can point Claude at a folder on their machine and say "organize these receipts into a spreadsheet" or "draft a report from these notes."

That's transformative. It's also terrifying from a governance perspective.

Why This Matters

Claude Code has guardrails built into developer culture — git history, code review, CI pipelines, pull requests. If an agent writes bad code, the PR catches it.

Cowork has none of that. A marketing manager asking Claude to "clean up the Q4 reports folder" doesn't have git. There's no PR review for a spreadsheet. There's no CI pipeline for a slide deck. When Claude deletes the wrong files, overwrites a customer list, or writes PII into a shared document, there's no safety net.

And it's not just accidental damage. Cowork gives Claude filesystem access on real business machines — the same machines with .env files, SSH keys, AWS credentials, HR documents, and financial records sitting in ~/Documents.

Waxell is the governance layer that makes Claude Code and Cowork safe for enterprise adoption. Every session is traced, every file operation passes through security guardrails, costs are tracked per user, and everything is auditable.

The Cowork Risk Profile

Developers understand what rm -rf does. Your marketing team doesn't. That's not a knock on your marketing team — it's the reality of giving an autonomous agent filesystem access to non-technical users.

Scenarios that keep security teams up at night

Sensitive Document Exposure

A sales ops manager asks Cowork to "compile all the customer contracts into a summary." Claude reads through ~/Documents/Contracts/ and writes a summary file that includes customer SSNs, payment terms, and contract values — then the user shares it in Slack. The Secret Scanning policy detects PII patterns in Claude's output before it's written to disk.

Accidental Data Destruction

An executive asks Cowork to "organize my Downloads folder." Claude decides to delete 200 "duplicate" files that turn out to be different versions of critical board presentations. The Destructive Command guard blocks rm -rf and recursive deletes, requiring explicit confirmation before any mass file operations.

Credential Harvesting

Claude is working in a project folder and discovers a .env file, ~/.aws/credentials, or an SSH private key. Whether through hallucination or a prompt injection buried in a document, it tries to write those credentials into a new file or include them in output. The Sensitive File Protection guard blocks reads and writes to credential files by default.

Cloud Metadata SSRF

On a company laptop connected to AWS, Claude tries to fetch http://169.254.169.254/latest/meta-data/ — the cloud instance metadata endpoint that exposes IAM credentials. The Network Access guard blocks all requests to internal IPs, link-local addresses, and cloud metadata endpoints.

Shadow IT Sprawl

Ten people on your team are using Cowork with no visibility into what Claude is doing, how much it costs, or what files it's accessing. One user is burning $50/day on Opus. Another has Claude editing production config files. Without Waxell, you have no way to know. Session tracing and cost tracking give you a complete picture across every user.

Path Traversal

A user asks Cowork to work on files in ~/Projects/website/. Claude decides it needs to read ../../.ssh/id_rsa to "check SSH config for deployment." The Path Boundary guard blocks file access outside the designated working directory.

Runaway Sessions

A Cowork user gives Claude a vague prompt like "improve all the documents in this folder." Claude starts modifying every file it can find — 60 files edited and counting. The Session Scope guard warns at 20 files and prompts at 50, catching runaway sessions before they cause unreviewable damage.

What You Get

Feature	Description
Session tracing	Every Claude Code and Cowork session recorded as an agent run with full trace
Tool call tracking	File reads, writes, edits, bash commands, web fetches — all captured as spans
LLM cost tracking	Token usage and estimated cost per session, per user
Local guard	Instant, zero-latency security checks on every file operation (8 protection layers)
Server-side policies	Budget limits, rate limits, scheduling, kill switch — enforced server-side
Secret & PII scanning	Detect leaked credentials, API keys, SSNs, and credit cards in outputs
Path boundary enforcement	Prevent Claude from accessing files outside the project directory
MCP tools	Claude can proactively check policies and record decisions
Full audit trail	Every file operation, every LLM invocation, every policy decision — logged and searchable

Quick Start

# 1. Install waxell-observe
pip install waxell-observe

# 2. Configure your API key
wax configure

# 3. Set up hooks (works for both Claude Code and Cowork)
wax observe claude-code setup --governance

That's it. Both Claude Code and Cowork use the same hooks system under the hood, so one setup covers both.

For Cowork Users

If you're setting up guardrails for non-technical Cowork users, use --global so the protection applies to every folder they give Claude access to — not just one project:

wax observe claude-code setup --global --governance

Setup Options

Basic Observability

Traces sessions, tool calls, and LLM usage — no blocking:

wax observe claude-code setup

With Governance (Recommended)

Adds PreToolUse policy enforcement — Claude must pass your security guardrails before executing commands, file edits, and file writes:

wax observe claude-code setup --governance

With MCP Tools

Registers a local MCP server so Claude can proactively check policies, query budget status, and record decisions:

wax observe claude-code setup --governance --mcp

Global Configuration

Apply to all projects and folders (writes to ~/.claude/settings.json). Recommended for Cowork deployments so every folder a user gives Claude access to is protected:

wax observe claude-code setup --global --governance --mcp

Per-Project Configuration

wax observe claude-code setup --project-dir /path/to/project

How It Works

Both Claude Code and Cowork are built on the same agent foundation and share the same hooks system. The setup command writes hook entries into .claude/settings.json. When Claude runs, it calls wax observe claude-code hook at each lifecycle event:

Claude Code / Cowork Session
    │
    ├─ SessionStart  → Creates an agent run in Waxell
    ├─ PreToolUse    → Runs local guard + server policy check (governance mode)
    ├─ PostToolUse   → Records tool call span, tracks modified files
    ├─ SubagentStart → Records subagent span start
    ├─ SubagentStop  → Records subagent span with token usage
    ├─ Stop          → Parses transcript, batch-records LLM calls, completes run
    └─ SessionEnd    → Cleanup

Local Guard

The local guard runs before every tool call — zero network latency, pure pattern matching. It provides 8 layers of protection out of the box. This is especially critical for Cowork, where non-technical users may not recognize dangerous operations.

Destructive Command Blocking

Commands that destroy data are blocked immediately:

Blocked (deny)	Warned (ask user)
rm -rf /, rm -rf ~, rm -rf .	Any rm -rf
mkfs, dd if=, > /dev/sd	kill -9, pkill -9
Fork bombs, shutdown, reboot	docker system prune
chmod -R 777 /	DROP TABLE, DELETE FROM without WHERE
curl ... | bash, wget ... | sh

Sensitive File Protection

Writes to credential files are blocked:

.env, .env.*, .env.production       # Environment variables
**/credentials*, **/secrets.*       # Secrets files
**/*.pem, **/*.key, **/id_rsa      # Private keys
**/.ssh/*, **/.aws/credentials     # Cloud credentials
.git/config, **/.netrc, **/.npmrc  # Auth configs

Writes to lock files and .gitignore trigger a confirmation prompt.

Git Safety

Operation	Action
git push --force to protected branch	Deny
git reset --hard	Deny
git clean -f, git checkout ., git restore .	Deny
git config modifications	Deny
git push to protected branch (non-force)	Ask
git branch -D	Ask
git rebase on protected branch	Ask

Default protected branches: main, master, develop, release/*, production.

Path Boundary Enforcement

When enabled (default), writes outside the project directory are blocked. This is a critical guardrail for Cowork — it prevents Claude from reaching into ~/.ssh, ~/.aws, or other sensitive directories when a user gives it access to ~/Documents/Reports.

Reads are always allowed. Exceptions: /tmp and system temp directories.

Network Access Control

Blocks WebFetch to internal/private URLs:

• localhost, 127.0.0.1, 0.0.0.0
• Private networks: 10.*, 172.16-31.*, 192.168.*
• Cloud metadata: 169.254.169.254, metadata.google.internal

CI/CD & Infrastructure Protection

Writes to infrastructure files require confirmation:

Dockerfile, docker-compose*.yml         # Container configs
.github/**, .gitlab-ci.yml, Jenkinsfile # CI/CD pipelines
**/*.tf, **/terraform/**                # Infrastructure as code
**/k8s/**, **/kubernetes/**, **/helm/** # Kubernetes
Makefile, Procfile, vercel.json         # Build & deploy

Session Scope Control

Tracks unique files modified per session. Warns at 20 files, prompts at 50 files. Prevents runaway sessions from touching too many files — especially important for Cowork where a vague prompt like "organize everything" can spiral.

Multi-Session Conflict Detection

When multiple Claude sessions are active in the same directory (e.g., two Claude Code instances via agent teams, or overlapping Cowork sessions), the guard detects when one session tries to edit a file another session already modified and warns before overwriting.

Customizing the Guard

Create .waxell/guard.json in your project root (or ~/.waxell/guard.json for global config) to override defaults. Only specified keys are changed — everything else keeps the built-in defaults.

Example: Strict Config for Cowork Users

Lock down filesystem access for non-technical users:

{
  "path_boundary_enabled": true,
  "max_file_changes": 15,
  "warn_file_changes": 8,
  "blocked_domains": ["competitor.com"],
  "protected_file_patterns": [
    ".env", ".env.*",
    "**/credentials*", "**/secrets.*",
    "**/*.pem", "**/*.key",
    "**/.ssh/*", "**/.aws/*",
    "**/payroll/**", "**/hr/**",
    "**/financial/**"
  ]
}

Example: Developer Config

Developers need more freedom but still want safety rails:

{
  "git_protected_branches": ["main", "master", "staging", "production"],
  "max_file_changes": 50,
  "warn_file_changes": 20,
  "path_boundary_enabled": true
}

Example: Relaxed Dev Config

For local experimentation where you want minimal friction:

{
  "path_boundary_enabled": false,
  "max_file_changes": 200,
  "git_block_hard_reset": false,
  "infra_file_patterns": []
}

Configuration Priority

1. .waxell/guard.json in project root (highest priority)
2. ~/.waxell/guard.json (user global)
3. Built-in defaults (always present)

All Configuration Fields

Field	Type	Default	Description
blocked_command_patterns	string[]	15 patterns	Regex patterns — matching commands are denied
warn_command_patterns	string[]	12 patterns	Regex patterns — matching commands prompt user
protected_file_patterns	string[]	24 patterns	Glob patterns — writes are denied
warn_file_patterns	string[]	5 patterns	Glob patterns — writes prompt user
path_boundary_enabled	bool	true	Block writes outside project directory
git_protected_branches	string[]	["main","master","develop","release/*","production"]	Branches protected from force push
git_block_force_push	bool	true	Block force push to protected branches
git_block_hard_reset	bool	true	Block git reset --hard
git_block_config_edit	bool	true	Block git config modifications
blocked_domains	string[]	[]	Domains blocked for WebFetch
block_internal_urls	bool	true	Block WebFetch to localhost/private IPs
max_file_changes	int	50	Prompt after this many unique file modifications
warn_file_changes	int	20	Warn at this many file modifications
detect_file_conflicts	bool	true	Warn when another session modified the same file
infra_file_patterns	string[]	22 patterns	Glob patterns — writes prompt user

Server-Side Policies

Beyond the local guard, Waxell enforces server-side policies for capabilities that require persistent state (budgets, rate limits, scheduling). These run after the local guard check.

Available Policy Templates

Configure these in the Waxell dashboard under Governance > Policies:

Template	Category	What It Does
Session Budget	cost	Token and dollar limits per session
Daily Budget	cost	Token and dollar limits per day
Model Restriction	llm	Restrict which models can be used
Business Hours	scheduling	Allow sessions only during work hours
Kill Switch	kill	Auto-halt on high error rates
Full Audit	audit	Log all inputs/outputs with secret redaction
Rate Limit	rate-limit	Requests per minute/hour, concurrent sessions
Secret Scanning	content	Detect leaked credentials and PII
Webhook Notifications	control	Slack/Teams notifications on events

Session Budget Example

Set a $5 / 500K token limit per session:

{
  "per_workflow_token_limit": 500000,
  "per_workflow_cost_limit": 5.00,
  "warning_threshold_percent": 80,
  "action_on_exceed": "warn"
}

When 80% of the budget is consumed, Claude receives a warning. At 100%, the action triggers (warn or block).

Business Hours Example

Restrict Claude to weekdays, 8am-8pm Eastern:

{
  "allowed_days": [1, 2, 3, 4, 5],
  "start_hour": 8,
  "end_hour": 20,
  "timezone": "America/New_York"
}

MCP Tools

When set up with --mcp, Claude gains three proactive tools:

Tool	Description
waxell_check_policy	Check if a planned action is allowed before attempting it
waxell_budget_status	Query remaining budget (tokens, cost) for the current session
waxell_record_decision	Record a decision for the audit trail

These let Claude self-regulate — it can check budget before starting an expensive operation, or record why it chose a particular approach.

CLI Commands

Check Active Sessions

wax observe claude-code status

Shows a table of all active Claude Code and Cowork sessions with session ID, run ID, model, span count, start time, and working directory.

Clean Up Stale State

wax observe claude-code clean

Removes session state files older than 24 hours.

Environment Variables

Variable	Description
WAXELL_API_KEY	Your Waxell API key (wax_sk_...)
WAXELL_API_URL	Waxell platform URL
WAXELL_OBSERVE	Set to false to disable all telemetry

Governance Decision Flow

When governance mode is enabled (--governance), every Bash, Edit, and Write tool call goes through this flow:

PreToolUse fires (Bash/Edit/Write)
    │
    ├─ 1. LOCAL GUARD (instant, no network)
    │     ├─ Check destructive commands
    │     ├─ Check git operations
    │     ├─ Check file protection
    │     ├─ Check path boundaries
    │     ├─ Check network access
    │     ├─ Check infrastructure files
    │     ├─ Check session scope
    │     └─ Check multi-session conflicts
    │
    │     ├─ DENY → Block tool call immediately
    │     └─ ASK  → Queue warning
    │
    ├─ 2. SERVER POLICY CHECK (budget, scheduling, etc.)
    │     ├─ BLOCK → Deny tool call
    │     └─ WARN  → Queue warning
    │
    ├─ 3. Any warnings queued?
    │     └─ Yes → Prompt user for confirmation
    │
    └─ 4. All clear → Allow tool call

Deploying for Your Team

For Developer Teams (Claude Code)

1. Add .waxell/guard.json to your repo with your team's protected branches and file patterns
2. Run wax observe claude-code setup --governance in each project
3. Configure session and daily budgets in the Waxell dashboard
4. Review session traces to tune policies over time

For Non-Technical Teams (Cowork)

1. Install waxell-observe on each user's machine: pip install waxell-observe
2. Run global setup: wax observe claude-code setup --global --governance
3. Create ~/.waxell/guard.json with strict defaults (low file change limits, protected file patterns for sensitive business documents)
4. Configure daily budget policies per user in the Waxell dashboard
5. Set up Slack/Teams webhook notifications so IT gets alerts on policy violations

For Enterprise (Both)

1. Deploy waxell-observe via your package manager or MDM
2. Use global config (--global) with managed .waxell/guard.json pushed via config management
3. Enable full audit logging with 90-day retention
4. Configure business hours policies to prevent after-hours usage
5. Set up kill switch policies for automatic incident response
6. Route webhook notifications to your SIEM

Best Practices

1. Always use --governance — the local guard has sensible defaults that protect against accidental damage without being overly restrictive
2. Use --global for Cowork deployments — non-technical users shouldn't have to set up guardrails per folder
3. Set stricter limits for Cowork than Claude Code — developers need more freedom, business users need more protection
4. Add --mcp for budget-conscious teams — lets Claude self-regulate its spending
5. Use .waxell/guard.json for project-specific rules — commit it to your repo so the whole team gets the same guardrails
6. Set up server-side budgets — local guard handles safety, server policies handle cost
7. Review the dashboard — session traces show exactly what Claude did, helping you tune policies over time

Next Steps

• Governance Features -- Configure server-side policies
• Cost Management -- Track and control AI spending
• Multi-Agent -- Observe coordinated agent systems
• Auto-Instrumentation -- Instrument LLM calls in your own code