commit 2491f5c73254244b64134a75c3c7d2cf544b2da9 Author: Kjell Tore Guttormsen Date: Thu Mar 26 09:47:29 2026 +0100 feat: initial companion repo for OpenClaw vs Claude Code article 40 files demonstrating every major OpenClaw capability using Claude Code: - 3 agents (researcher, writer, reviewer) - 3 skills (daily-briefing, slack-message, web-research) - 2 security hooks (pre-tool-use blocker, post-tool-use logger) - 10 self-contained examples with copy-paste prompts - Complete feature map (20 capabilities, 11 full match, 7 different, 2 gap) - Security docs including NemoClaw comparison - Automation, messaging, browser, memory documentation Zero dependencies. Clone and run. Co-Authored-By: Claude Opus 4.6 (1M context) diff --git a/.claude/agents/researcher.md b/.claude/agents/researcher.md new file mode 100644 index 0000000..d97d7fa --- /dev/null +++ b/.claude/agents/researcher.md @@ -0,0 +1,34 @@ +--- +name: researcher +description: Web research agent that searches, reads, and summarizes information from multiple sources. Use when you need current facts, comparisons, or background context. +tools: ["WebSearch", "WebFetch", "Read", "Write", "Glob", "Grep"] +model: sonnet +--- + +# Researcher Agent + +You are a focused research agent. Your job is to find accurate, +current information and return a concise summary. + +## How you work + +1. Break the research question into 2-3 specific search queries +2. Search the web for each query +3. Read the most relevant results +4. Cross-reference claims across sources +5. Write a summary with source URLs + +## Rules + +- Never guess. If you cannot verify a claim, say so explicitly. +- Include source URLs for every factual claim. +- Prefer primary sources (official docs, announcements) over blog posts. +- Keep summaries under 500 words unless the caller asks for more. +- Flag conflicting information between sources. + +## Output format + +Return a markdown summary with: +- **Answer:** 2-3 sentence direct answer +- **Details:** Supporting information with inline source links +- **Confidence:** High / Medium / Low based on source quality diff --git a/.claude/agents/reviewer.md b/.claude/agents/reviewer.md new file mode 100644 index 0000000..85800e7 --- /dev/null +++ b/.claude/agents/reviewer.md @@ -0,0 +1,36 @@ +--- +name: reviewer +description: Quality review agent that checks content for accuracy, clarity, and completeness. Use before publishing or sharing any content. +tools: ["Read", "Glob", "Grep", "WebSearch", "WebFetch"] +model: sonnet +--- + +# Reviewer Agent + +You are a critical reviewer. Your job is to find problems before +they reach the reader. + +## What you check + +1. **Accuracy:** Are all claims verifiable? Any outdated info? +2. **Clarity:** Can the target audience understand every paragraph? +3. **Completeness:** Are there gaps the reader would notice? +4. **Links:** Do all referenced files, URLs, or resources exist? +5. **Tone:** Is it consistent? Any unintended shifts? + +## How you work + +1. Read the content thoroughly +2. Check factual claims against web sources when uncertain +3. Verify internal references (file paths, code snippets) +4. Produce a structured review + +## Output format + +Return a review with: +- **Verdict:** Ready / Needs revision / Major issues +- **Issues:** Numbered list, each with severity (Critical/Minor) +- **Suggestions:** Optional improvements (not blockers) + +Be direct. "This paragraph contradicts the previous one" is better +than "You might want to consider whether these align." diff --git a/.claude/agents/writer.md b/.claude/agents/writer.md new file mode 100644 index 0000000..1a30c68 --- /dev/null +++ b/.claude/agents/writer.md @@ -0,0 +1,32 @@ +--- +name: writer +description: Content drafting agent that produces clear, structured writing. Use for blog posts, documentation, reports, and summaries. +tools: ["Read", "Write", "Edit", "Glob", "Grep"] +model: sonnet +--- + +# Writer Agent + +You are a content drafting agent. You produce clear, well-structured +writing that serves the reader. + +## How you work + +1. Read any source material or research provided +2. Identify the audience and purpose +3. Draft content with clear structure (headings, short paragraphs) +4. Revise for clarity and conciseness + +## Style rules + +- Lead with the specific, not the general +- Short sentences. Short paragraphs. +- No filler words or throat-clearing openers +- No "In today's world..." or "It's important to note..." +- Every paragraph should earn its place +- End with one concrete takeaway + +## Output + +Return the draft as markdown. Flag any sections where you +need more information from the caller with `[NEEDS INPUT: ...]`. diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..0ec678d --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,50 @@ +{ + "permissions": { + "allow": [ + "Bash(ls:*)", + "Bash(cat:*)", + "Bash(echo:*)", + "Bash(pwd)", + "Bash(date)", + "Bash(wc:*)", + "Read", + "Write", + "Edit", + "Glob", + "Grep", + "WebSearch", + "WebFetch" + ], + "deny": [ + "Bash(rm -rf *)", + "Bash(sudo *)", + "Bash(chmod 777 *)", + "Bash(curl * | bash)", + "Bash(wget * | bash)" + ] + }, + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "bash hooks/pre-tool-use.sh" + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "bash hooks/post-tool-use.sh" + } + ] + } + ] + } +} diff --git a/.claude/skills/daily-briefing.md b/.claude/skills/daily-briefing.md new file mode 100644 index 0000000..3522ad3 --- /dev/null +++ b/.claude/skills/daily-briefing.md @@ -0,0 +1,40 @@ +--- +name: daily-briefing +description: Generate a morning briefing with weather, calendar summary, and top news for your focus areas. Demonstrates cron/automation capability. +--- + +# Daily Briefing + +Generate a concise morning briefing. This skill demonstrates how +Claude Code can replicate OpenClaw's HEARTBEAT.md autonomous tasks. + +## Steps + +1. Search for today's top AI news (3 items max) +2. Search for any breaking tech news +3. Summarize in a structured briefing + +## Output format + +``` +## Morning Briefing - [date] + +### Top AI News +- [headline]: [one-sentence summary] ([source]) +- ... + +### Action Items +- [anything that needs attention today] + +### Weather +[Not available without location API - add your own MCP server] +``` + +## Automation + +To run this daily, see `automation/README.md` for cron and +launchd setup instructions. You can schedule this with: + +```bash +claude -p "Run /daily-briefing" --output-format text +``` diff --git a/.claude/skills/send-slack-message.md b/.claude/skills/send-slack-message.md new file mode 100644 index 0000000..98b16bd --- /dev/null +++ b/.claude/skills/send-slack-message.md @@ -0,0 +1,48 @@ +--- +name: send-slack-message +description: Send a message to a Slack channel via MCP. Demonstrates multi-channel messaging capability. +--- + +# Send Slack Message + +Send a message to a Slack channel. This demonstrates how Claude Code +handles messaging through MCP servers, compared to OpenClaw's 15+ +native channel integrations. + +## Prerequisites + +You need a Slack MCP server configured in `.mcp.json`. Example: + +```json +{ + "mcpServers": { + "slack": { + "command": "npx", + "args": ["@anthropic-ai/mcp-slack@latest"], + "env": { + "SLACK_BOT_TOKEN": "xoxb-your-token-here" + } + } + } +} +``` + +## Usage + +Tell Claude Code: "Send a message to #general saying [your message]" + +Claude Code will use the Slack MCP server's `send_message` tool. + +## How this compares to OpenClaw + +OpenClaw has native Slack integration (Bolt SDK, no config needed +beyond token). Claude Code uses MCP as the integration layer. The +result is the same: a message arrives in Slack. The setup differs: +OpenClaw is plug-and-play, Claude Code requires MCP configuration. + +## Other messaging channels + +- **Telegram:** Native via Claude Code Channels (v2.1.80+) +- **Discord:** Via MCP server +- **Email:** Via MCP server (e.g., Gmail MCP) +- **Teams:** Via MCP server or webhook diff --git a/.claude/skills/web-research.md b/.claude/skills/web-research.md new file mode 100644 index 0000000..0db03cb --- /dev/null +++ b/.claude/skills/web-research.md @@ -0,0 +1,50 @@ +--- +name: web-research +description: Deep web research with source verification. Searches multiple queries, cross-references results, and produces a sourced summary. +--- + +# Web Research + +Conduct thorough web research on a topic. This skill demonstrates +Claude Code's built-in WebSearch and WebFetch tools, which match +OpenClaw's Brave Search + Firecrawl combination. + +## How it works + +1. Take the user's research question +2. Generate 3-5 targeted search queries +3. Search and read the top results for each +4. Cross-reference claims across sources +5. Produce a structured summary with citations + +## Output format + +``` +## Research: [topic] + +### Key Findings +1. [finding] ([source URL]) +2. [finding] ([source URL]) +3. [finding] ([source URL]) + +### Details +[Longer explanation with inline citations] + +### Sources +- [title] - [URL] +- [title] - [URL] + +### Confidence +[High/Medium/Low] - [reason] + +### Gaps +[What could not be verified or found] +``` + +## Comparison to OpenClaw + +OpenClaw uses Brave Search API with Firecrawl as anti-bot fallback. +Claude Code uses WebSearch (built-in, no API key needed) and WebFetch +for full page reading. Both achieve the same outcome. Claude Code's +advantage: zero configuration. OpenClaw's advantage: configurable +search provider and caching. diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e0e724e --- /dev/null +++ b/.gitignore @@ -0,0 +1,19 @@ +# OS +.DS_Store +Thumbs.db + +# Editor +.vscode/ +.idea/ +*.swp +*.swo + +# Local overrides +*.local.md + +# Environment +.env +.env.* + +# Logs +*.log diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..d83d048 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,10 @@ +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": ["@anthropic-ai/mcp-playwright@latest"], + "disabled": true, + "env": {} + } + } +} diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a9c4bd2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,35 @@ +# Claude Code Complete Agent + +This is a working companion repo for the article +"Every OpenClaw Feature, Covered by Claude Code." + +## What This Repo Does + +It demonstrates that Claude Code's ecosystem (tools, MCP servers, +plugins, hooks, agents, skills, and triggers) covers the same +20 capabilities that made OpenClaw the fastest-growing open-source +project in history. + +## How to Use It + +1. Open this directory in Claude Code: `claude` +2. Try any example from `examples/` by pasting the prompt +3. Explore agents in `.claude/agents/` and skills in `.claude/skills/` +4. Review security hooks in `hooks/` + +## Project Memory + +This file is the project's persistent memory. Claude Code reads it +at the start of every session. You can add notes, preferences, and +context here. Unlike OpenClaw's vector-search memory, Claude Code +uses a file hierarchy: + +- `CLAUDE.md` (this file) - project-level instructions +- `~/.claude/CLAUDE.md` - global personal instructions +- `.claude/settings.json` - permissions and tool configuration + +## Convention + +- All examples are self-contained. No dependencies to install. +- Hooks use bash. They work on macOS and Linux. +- MCP config in `.mcp.json` uses Playwright (browser automation). diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..1105208 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Kjell Tore Guttormsen + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..7cf9755 --- /dev/null +++ b/README.md @@ -0,0 +1,126 @@ +# Claude Code Complete Agent + +A working setup that demonstrates every major OpenClaw capability +using Claude Code's ecosystem: tools, MCP servers, plugins, hooks, +agents, skills, and triggers. + +Companion repo for the article +[Every OpenClaw Feature, Covered by Claude Code](https://fromaitochitta.com/openclaw-vs-claude-code-every-feature-compared). + +## Why this exists + +OpenClaw has 247K GitHub stars and 20 major capabilities. It is the +fastest-growing open-source project in history. This repo shows that +Claude Code covers 18 of those 20 capabilities, with 11 full matches +and 7 different approaches. Two gaps remain: Gateway/Control Plane +and Canvas/A2UI. + +This is not a theoretical comparison. Clone this repo, open Claude +Code, and try each example yourself. + +## Prerequisites + +- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) v2.1.81+ +- Node.js 18+ (only needed for Playwright MCP) +- A terminal (macOS or Linux) + +No npm install. No Docker. No build step. + +## Quickstart + +```bash +git clone https://git.fromaitochitta.com/ktg/claude-code-complete-agent.git +cd claude-code-complete-agent +claude +``` + +Then try: + +``` +Paste the prompt from examples/01-agent-runtime/prompt.md +``` + +## What is in this repo + +### Working configuration + +| Path | What it does | +|------|-------------| +| `CLAUDE.md` | Project memory and instructions | +| `.claude/settings.json` | Permissions, deny lists, hook config | +| `.claude/agents/` | Three agents: researcher, writer, reviewer | +| `.claude/skills/` | Three skills: daily-briefing, slack-message, web-research | +| `.mcp.json` | Playwright MCP (disabled by default) | +| `hooks/` | Security hooks (pre-tool-use blocker, post-tool-use logger) | + +### Documentation + +| Path | What it covers | +|------|---------------| +| `security/` | Permission modes, hook patterns, NemoClaw comparison | +| `memory/` | How Claude Code memory works vs OpenClaw's vector search | +| `automation/` | Cron, launchd, /loop, /schedule | +| `messaging/` | Slack MCP, Telegram Channels, channel comparison | +| `browser/` | Playwright MCP setup and usage | + +### Examples (try these) + +| # | Example | Capability | OpenClaw equivalent | +|---|---------|-----------|-------------------| +| 01 | Agent Runtime | Tool execution loop | Long-running daemon | +| 02 | Shell and Files | Bash + file I/O | exec tool + read/write | +| 03 | Web Search | WebSearch + WebFetch | Brave Search + Firecrawl | +| 04 | Browser Automation | Playwright MCP | CDP/Playwright built-in | +| 05 | Memory System | CLAUDE.md + auto-memory | Daily logs + vector search | +| 06 | Multi-Agent | Agent Teams + SendMessage | Sub-agents + mesh | +| 07 | Messaging | MCP + Telegram Channels | 15+ native channels | +| 08 | Cron/Automation | /loop, CronCreate, /schedule | HEARTBEAT.md + cron | +| 09 | Security Hooks | PreToolUse/PostToolUse | Exec approvals + Docker | +| 10 | Full Pipeline | All capabilities combined | Complete workflow | + +Each example has a self-contained prompt you can paste directly +into Claude Code. + +## The feature map + +See [feature-map.md](feature-map.md) for the complete 20-row +comparison table with verdicts and version requirements. + +**Summary:** 11 full match, 7 different approach, 2 gaps. + +## What Claude Code does not do (today) + +**Gateway/Control Plane:** OpenClaw runs a WebSocket server with a +control UI and OpenAI-compatible API. Claude Code has no equivalent. +If you need a programmable HTTP interface to your agent, OpenClaw +is the better choice. + +**Canvas/A2UI:** OpenClaw's canvas is an interactive HTML workspace +served by the gateway. Claude Code can generate HTML and preview it +via Playwright, but there is no persistent interactive surface. + +These gaps matter most for always-on, multi-user automation. For +development and task execution, they are less relevant. + +## Security note + +The hooks in this repo demonstrate security patterns, but they are +examples, not a production security configuration. Review and +customize them for your environment: + +- `hooks/pre-tool-use.sh` blocks known-dangerous commands +- `hooks/post-tool-use.sh` logs all tool executions +- `.claude/settings.json` has a permission deny list + +Read `security/permission-modes-explained.md` before running +Claude Code on anything sensitive. + +## License + +MIT. See [LICENSE](LICENSE). + +## About + +Built by [Kjell Tore Guttormsen](https://fromaitochitta.com) as +part of the From AI to Chitta project, exploring the intersection +of AI tools and inner development. diff --git a/automation/README.md b/automation/README.md new file mode 100644 index 0000000..b78af9d --- /dev/null +++ b/automation/README.md @@ -0,0 +1,64 @@ +# Automation + +Four ways to schedule or trigger Claude Code tasks, with OpenClaw equivalents. + +## 1. `/loop` - In-session recurring tasks + +Run a task repeatedly within a single Claude Code session. + +``` +/loop Run /health-check every 30 minutes +``` + +**Best for:** Monitoring during active work sessions, watch loops, polling. +**OpenClaw equivalent:** `HEARTBEAT.md` pattern - agent checks a file on each tick +and executes tasks listed there. + +## 2. `CronCreate` - Claude Code built-in cron + +Claude Code can create system crontab entries directly via the `CronCreate` tool. + +``` +# In a Claude Code session: +Create a cron job that runs /daily-briefing every day at 7 AM +``` + +Claude calls `CronCreate` and writes the entry to your system crontab. +List with `CronList`, remove with `CronDelete`. + +**Best for:** Simple recurring tasks, no manual crontab editing. +**OpenClaw equivalent:** OpenClaw's scheduler daemon with task definitions in config. + +## 3. `/schedule` - Remote triggers via claude.ai/code + +Trigger Claude Code runs remotely through claude.ai/code using the `RemoteTrigger` +tool or the web interface. + +**Best for:** Event-driven automation, triggering from external systems. +**OpenClaw equivalent:** OpenClaw's webhook receiver (listens on a local port). + +## 4. `launchd` - macOS native scheduler + +More reliable than cron on macOS. Survives sleep/wake cycles, logs stdout/stderr, +and integrates with the macOS service manager. + +See `daily-briefing.sh` and `launchd-example.plist` in this directory. + +```bash +# Install: +cp launchd-example.plist ~/Library/LaunchAgents/com.example.claude-briefing.plist +launchctl load ~/Library/LaunchAgents/com.example.claude-briefing.plist +``` + +**Best for:** Production schedules on Mac, anything that needs to survive reboots. +**OpenClaw equivalent:** Same - OpenClaw also recommends launchd on macOS for its +daemon process. + +## Comparison + +| Approach | Setup | Reliability | Use case | +|---------------|----------|-------------|-------------------------------| +| `/loop` | Zero | Session | Active monitoring | +| `CronCreate` | Minimal | Good | Simple recurring tasks | +| `/schedule` | Moderate | Good | Remote/event triggers | +| `launchd` | Manual | Best on Mac | Production daily jobs | diff --git a/automation/daily-briefing.sh b/automation/daily-briefing.sh new file mode 100755 index 0000000..5e8fbdb --- /dev/null +++ b/automation/daily-briefing.sh @@ -0,0 +1,8 @@ +#!/bin/bash +# Run the daily briefing skill via Claude Code headless mode +# Schedule this with cron or launchd + +cd "$(dirname "$0")/.." +claude -p "Run /daily-briefing and save output to briefings/$(date +%Y-%m-%d).md" \ + --output-format text \ + --max-turns 10 diff --git a/automation/launchd-example.plist b/automation/launchd-example.plist new file mode 100644 index 0000000..d739802 --- /dev/null +++ b/automation/launchd-example.plist @@ -0,0 +1,53 @@ + + + + + + Label + com.example.claude-daily-briefing + + + ProgramArguments + + /bin/bash + + /path/to/claude-code-complete-agent/automation/daily-briefing.sh + + + + StartCalendarInterval + + Hour + 7 + Minute + 0 + + + + StandardOutPath + /tmp/claude-daily-briefing.log + + + StandardErrorPath + /tmp/claude-daily-briefing.err + + + RunAtLoad + + + + + diff --git a/browser/README.md b/browser/README.md new file mode 100644 index 0000000..f9ca9a0 --- /dev/null +++ b/browser/README.md @@ -0,0 +1,28 @@ +# Browser Automation + +## OpenClaw: Built-in CDP/Playwright + +OpenClaw ships with browser control built in. It manages multiple browser +instances, supports profiles, and exposes `act` commands that combine +navigation, interaction, and extraction in one step. No setup required. + +## Claude Code: Playwright MCP server + +Claude Code uses the `@playwright/mcp` server. Same underlying engine +(Playwright), different integration model: the browser runs in a separate +process, and Claude communicates with it over MCP. + +**Tradeoff:** The decoupled approach means the browser can be swapped or +updated independently. The cost is one extra setup step. + +## Comparison + +| Property | OpenClaw | Claude Code | +|---------------------|-----------------------|-----------------------| +| Engine | CDP/Playwright | Playwright | +| Setup | Zero | Enable in .mcp.json | +| Multi-instance | Yes | One per MCP server | +| Browser profiles | Yes | Via Playwright config | +| `act` shorthand | Yes | No (compose manually) | + +For setup, see `playwright-mcp-setup.md`. diff --git a/browser/playwright-mcp-setup.md b/browser/playwright-mcp-setup.md new file mode 100644 index 0000000..f6705d6 --- /dev/null +++ b/browser/playwright-mcp-setup.md @@ -0,0 +1,50 @@ +# Playwright MCP Setup + +## 1. Enable in .mcp.json + +The `.mcp.json` in this repo already has Playwright configured but disabled. +To enable, change `"disabled": true` to `"disabled": false`: + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": ["-y", "@playwright/mcp"], + "disabled": false + } + } +} +``` + +## 2. Requirements + +Node.js must be installed. The server runs via `npx` and downloads automatically +on first use. No separate install step needed. + +## 3. Available tools + +Once enabled, Claude has access to: + +| Tool | Description | +|-------------|--------------------------------------------| +| `navigate` | Go to a URL | +| `screenshot`| Capture the current page | +| `click` | Click an element | +| `type` | Type text into a field | +| `snapshot` | Get accessibility tree (faster than screenshot) | + +## 4. Example usage + +``` +Go to https://example.com, take a screenshot, and tell me what's on the page +``` + +``` +Fill out the login form at https://myapp.com with username "test" and password "test" +``` + +## 5. Headless vs headed + +By default Playwright runs headless. To see the browser window, add `--headed` +to the args array in `.mcp.json`. diff --git a/examples/01-agent-runtime/prompt.md b/examples/01-agent-runtime/prompt.md new file mode 100644 index 0000000..41165cb --- /dev/null +++ b/examples/01-agent-runtime/prompt.md @@ -0,0 +1,49 @@ +# Example 01: Agent Runtime + +**Capability:** Claude Code executes tools autonomously, streams output as it works, +and loops until the task is complete. No user input needed between steps. + +**OpenClaw equivalent:** Long-running daemon with tool execution and streaming output. + +--- + +## The Prompt + +``` +Research the top 3 AI frameworks released this month, compare their GitHub stars, +and write a summary to research-output.md + +For each framework include: +- Name and release date +- GitHub URL and current star count +- One sentence on what problem it solves +- Your verdict on whether it's worth watching + +End the file with a "Verdict" section that ranks all three. +``` + +--- + +## What Happens + +Claude Code will: + +1. Use WebSearch to find AI framework releases from the current month +2. Use WebFetch to retrieve GitHub pages and extract star counts +3. Loop through each framework, gathering data tool call by tool call +4. Use Write to create `research-output.md` with the structured summary +5. Report completion with a summary of what was written + +You will see each tool call streamed as it happens. Claude does not ask for +confirmation between steps unless it hits something ambiguous. + +--- + +## Why This Matters + +This is the agent loop in action: plan, execute, observe, repeat. The same +loop that runs a 300-step pipeline also runs this 5-step research task. +The difference is only scale. + +Claude Code v2.1.84 added adaptive thinking, which adjusts reasoning depth +automatically. Complex sub-tasks get more thought; simple ones proceed fast. diff --git a/examples/02-shell-and-files/prompt.md b/examples/02-shell-and-files/prompt.md new file mode 100644 index 0000000..c81ccd5 --- /dev/null +++ b/examples/02-shell-and-files/prompt.md @@ -0,0 +1,50 @@ +# Example 02: Shell Execution and File I/O + +**Capability:** Claude Code runs shell commands and reads/writes files as part of the +same task. Shell output becomes input to the next step automatically. + +**OpenClaw equivalent:** `exec` tool with PTY support + read/write/edit file tools. + +--- + +## The Prompt + +``` +Create a directory called 'project-scaffold', add these files inside it: + +1. package.json with name "my-project", version "0.1.0", and description + "A scaffolded project created by Claude Code" + +2. README.md with a project overview section and a "Getting Started" section + with placeholder install instructions + +3. .gitignore for Node.js (node_modules, .env, dist, .DS_Store) + +Then run 'find project-scaffold -type f' to verify all three files exist +and show me the contents of package.json. +``` + +--- + +## What Happens + +Claude Code will: + +1. Use Bash to run `mkdir project-scaffold` +2. Use Write to create each of the three files +3. Use Bash to run `find project-scaffold -type f` and capture the output +4. Use Read to show the contents of `package.json` +5. Report back with the directory tree and file verification + +--- + +## Why This Matters + +Shell execution and file I/O are the foundation of every automation. Claude Code +handles both in the same task context, so shell output can feed directly into +file content decisions. + +The permission system controls what shell commands are allowed. In the +`settings.json` in this repo, `rm -rf` and a handful of other destructive +patterns are blocked by the `pre-tool-use.sh` hook before execution reaches +the shell. See `examples/09-security-hooks/` for details. diff --git a/examples/03-web-search/prompt.md b/examples/03-web-search/prompt.md new file mode 100644 index 0000000..6fe661b --- /dev/null +++ b/examples/03-web-search/prompt.md @@ -0,0 +1,54 @@ +# Example 03: Web Search and Fetch + +**Capability:** Claude Code can search the web and fetch full page content as part of +any task. Both tools are built-in; no MCP server required. + +**OpenClaw equivalent:** Brave Search API + web_fetch with Firecrawl fallback. + +--- + +## The Prompt + +``` +Search for the latest Claude Code release notes, summarize the 5 most impactful +features added in recent versions, and write the summary to changelog-summary.md + +For each feature include: +- Feature name and the version it shipped in +- One sentence on what it does +- One sentence on why it matters for agent workflows + +At the top of the file add a "Researched on" line with today's date and the +source URLs you used. +``` + +--- + +## What Happens + +Claude Code will: + +1. Use WebSearch to find Claude Code release notes and changelog pages +2. Use WebFetch to retrieve the full changelog content from Anthropic's docs +3. Parse and rank features by impact on agent workflows +4. Use Write to create `changelog-summary.md` with source attribution +5. Confirm the file was written + +--- + +## Why This Matters + +Web search makes Claude Code's knowledge current. The training cutoff becomes +less relevant when Claude can verify facts before writing them down. + +The combination of WebSearch (for discovery) and WebFetch (for depth) mirrors +what a human researcher does: scan headlines, then read the full article. +This is the same pattern used in the PREP phase of the article production +pipeline that drives the `fromaitochitta.com` content workflow. + +--- + +## Note on Sources + +Claude Code cites sources when writing research outputs. If you need full +traceability, add "include the exact URL next to each claim" to the prompt. diff --git a/examples/04-browser-automation/prompt.md b/examples/04-browser-automation/prompt.md new file mode 100644 index 0000000..a6f3c2f --- /dev/null +++ b/examples/04-browser-automation/prompt.md @@ -0,0 +1,63 @@ +# Example 04: Browser Automation + +**Capability:** Claude Code can control a real browser via Playwright MCP, take +screenshots, and extract structured data from live pages. + +**OpenClaw equivalent:** CDP/Playwright browser automation with screenshot and act commands. + +--- + +## Prerequisites + +Playwright MCP must be enabled. Add this to `.mcp.json`: + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": ["@playwright/mcp@latest"] + } + } +} +``` + +This repo's `.mcp.json` already includes it. If Claude Code does not show +Playwright tools at startup, run `npm install` to ensure the package is +available, then restart. + +--- + +## The Prompt + +``` +Navigate to https://news.ycombinator.com, take a screenshot of the current +front page, and list the top 5 stories with their point counts and submitter +names. + +Save the list to hacker-news-top5.md with the format: +1. [title] - [points] points by [submitter] + +Include a note at the bottom with the timestamp of when you fetched this. +``` + +--- + +## What Happens + +Claude Code will: + +1. Use the Playwright MCP `browser_navigate` tool to load the page +2. Use `browser_screenshot` to capture the current state +3. Use `browser_snapshot` or `browser_get_text` to extract story data +4. Use Write to save the structured list to `hacker-news-top5.md` + +--- + +## Why This Matters + +Browser automation handles pages that cannot be reached with WebFetch alone: +JavaScript-rendered content, login-protected pages, and interactive workflows. + +OpenClaw bundles Playwright natively. Claude Code uses the same underlying +engine via MCP. The setup takes two minutes; the capability is identical. diff --git a/examples/05-memory-system/prompt.md b/examples/05-memory-system/prompt.md new file mode 100644 index 0000000..a7cd198 --- /dev/null +++ b/examples/05-memory-system/prompt.md @@ -0,0 +1,58 @@ +# Example 05: Memory System + +**Capability:** Claude Code maintains persistent memory across sessions through a +hierarchy of markdown files. What is written in one session is available in the next. + +**OpenClaw equivalent:** Daily markdown logs + MEMORY.md + vector search (SQLite-vec). + +--- + +## How the Hierarchy Works + +Claude Code loads context in this order, from broadest to narrowest: + +1. `~/.claude/CLAUDE.md` - global preferences, always loaded +2. `CLAUDE.md` in the project root - project-specific config, always loaded +3. `memory/MEMORY.md` - session state, loaded if referenced in CLAUDE.md +4. `.claude/` managed memory - auto-updated by Claude when `--memory` is active + +The file loaded earlier provides the frame. Later files narrow it. + +--- + +## The Prompt + +``` +Read this project's CLAUDE.md and summarize what you learn about the project +in three bullet points. + +Then create a file at memory/project-notes.md with: +- Today's date as a header +- The three-bullet summary +- A note that says "Memory system demonstrated successfully" + +Finally, explain in one paragraph how this file will be available in the +next Claude Code session without re-reading CLAUDE.md. +``` + +--- + +## What Happens + +Claude Code will: + +1. Use Read to load `CLAUDE.md` from the project root +2. Synthesize the project context into three bullets +3. Use Write to create `memory/project-notes.md` +4. Explain how CLAUDE.md references cause files to be auto-loaded + +--- + +## Why This Matters + +OpenClaw uses SQLite-vec for semantic memory search across sessions. Claude Code +uses structured markdown with explicit file references. Both achieve persistence. +The markdown approach is more inspectable: you can read, edit, and version control +every piece of memory Claude has about your project. + +The `memory/MEMORY.md` file in this repo shows the pattern at scale. diff --git a/examples/06-multi-agent/prompt.md b/examples/06-multi-agent/prompt.md new file mode 100644 index 0000000..1460a74 --- /dev/null +++ b/examples/06-multi-agent/prompt.md @@ -0,0 +1,57 @@ +# Example 06: Multi-Agent Orchestration + +**Capability:** Claude Code can spawn sub-agents with distinct roles, run them in +parallel or in sequence, and combine their outputs into a final result. + +**OpenClaw equivalent:** Sub-agents, agent-to-agent messaging, mesh workflows. + +--- + +## Prerequisites + +This example uses the agents defined in `.claude/agents/`: +- `researcher.md` - web research and source gathering +- `writer.md` - structured content drafting +- `reviewer.md` - accuracy and quality review + +These agents load automatically when Claude Code opens this project. + +--- + +## The Prompt + +``` +Use the researcher agent to find information about how Claude Code handles +agent isolation and worktree sandboxing (introduced in v2.1.49 and v2.1.50). + +Then use the writer agent to draft a 300-word technical summary of the findings, +written for a developer audience. No jargon without explanation. + +Finally, use the reviewer agent to check the draft for technical accuracy. +If the reviewer finds any issues, have the writer fix them before showing +me the final version. +``` + +--- + +## What Happens + +Claude Code will: + +1. Invoke the researcher agent via the Agent tool with the research task +2. Receive the research output and pass it to the writer agent +3. Invoke the writer agent to produce the 300-word draft +4. Invoke the reviewer agent with both the draft and source material +5. If the reviewer flags issues, loop back to the writer for a revision +6. Present the final reviewed draft + +--- + +## Why This Matters + +Agent Teams (v2.1.32) gives Claude Code a mesh model that matches OpenClaw's +sub-agent architecture. Worktree isolation (v2.1.50) means each agent gets +its own working directory, preventing file conflicts in parallel runs. + +The researcher-writer-reviewer pattern is the same loop that produces articles +for `fromaitochitta.com`. The agents here are minimal versions of that pipeline. diff --git a/examples/07-messaging/prompt.md b/examples/07-messaging/prompt.md new file mode 100644 index 0000000..7145276 --- /dev/null +++ b/examples/07-messaging/prompt.md @@ -0,0 +1,83 @@ +# Example 07: Messaging + +**Capability:** Claude Code can send and receive messages via external channels. +Native Telegram support arrived in v2.1.80. Other channels use MCP servers. + +**OpenClaw equivalent:** 15+ native channels (WhatsApp, Telegram, Discord, Slack, +Signal, iMessage, IRC, Matrix, Teams, and more). + +--- + +## Architecture Difference + +OpenClaw ships with all 15+ channels built in. Claude Code takes an MCP approach: +each channel is a separate server you opt into. This means more setup per channel, +but also more control over what data leaves your machine. + +As of v2.1.80, Telegram is the first native channel in Claude Code. More are +expected to follow the same pattern. + +--- + +## Option A: Telegram (Native, v2.1.80+) + +Start Claude Code with the Channels flag: + +```bash +claude --channels +``` + +Then in session: + +``` +Send a Telegram message to my personal chat that says: +"Claude Code pipeline completed. Check research-output.md for results." +``` + +Requires the Telegram plugin configured in `.claude/settings.json`. The +permission relay (v2.1.81) lets you approve tool calls from Telegram directly, +without returning to the terminal. + +--- + +## Option B: Slack (via MCP) + +Add to `.mcp.json`: + +```json +{ + "mcpServers": { + "slack": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-slack"], + "env": { + "SLACK_BOT_TOKEN": "xoxb-your-token", + "SLACK_TEAM_ID": "T0123456" + } + } + } +} +``` + +Then use the `/skills/send-slack-message` skill in this repo: + +``` +/send-slack-message channel=#general message="Pipeline finished successfully." +``` + +--- + +## What Happens + +For Telegram: Claude Code calls the native Channels API to deliver the message. +For Slack: Claude Code calls the Slack MCP server, which relays via the Slack API. + +Both confirm delivery in the terminal output. + +--- + +## Honest Comparison + +If you need 15 channels working out of the box, OpenClaw wins today. Claude Code +has Telegram natively and the rest via MCP. The gap is narrowing with each +release. For most personal automation needs, Telegram is sufficient. diff --git a/examples/08-cron-automation/prompt.md b/examples/08-cron-automation/prompt.md new file mode 100644 index 0000000..f50f8ea --- /dev/null +++ b/examples/08-cron-automation/prompt.md @@ -0,0 +1,67 @@ +# Example 08: Cron and Scheduled Automation + +**Capability:** Claude Code supports scheduled and automated execution through +three complementary mechanisms, covering in-session polling through to +system-level cron jobs. + +**OpenClaw equivalent:** HEARTBEAT.md, cron scheduler, webhooks, auto-reply. + +--- + +## Three Approaches + +### Approach 1: /loop (In-session polling, v2.1.71) + +For tasks that should repeat while Claude Code is running: + +``` +/loop interval=60 + +Every 60 seconds, check if a file called 'trigger.txt' exists in this +directory. If it does, read its contents, execute the task described inside, +delete the file, and write the result to 'loop-output.md'. Then wait for +the next trigger. +``` + +Use this for development and testing. The loop runs as long as the session +is active. + +--- + +### Approach 2: CronCreate (System-level scheduling, v2.1.71) + +For tasks that should run on a schedule even when Claude Code is not open: + +``` +Create a cron job that runs the 'daily-briefing' skill every morning at 07:00. +Use the automation/daily-briefing.sh wrapper script. Show me the cron entry +before creating it so I can verify it. +``` + +Claude Code calls `CronCreate` to register the job with the system cron daemon. +Use `CronList` to see all registered jobs and `CronDelete` to remove them. +The `automation/daily-briefing.sh` script in this repo is a ready-made wrapper. + +--- + +### Approach 3: /schedule (Remote trigger, web only) + +For triggering runs from anywhere, including from a phone: + +``` +/schedule "Run the web-research skill on 'latest Anthropic news' and +email me a summary" at 2025-04-01T08:00:00 +``` + +`/schedule` is available in the Claude web interface. It queues a headless +Claude Code run for the specified time. Combines with the Telegram permission +relay (v2.1.81) for approval-gated automation. + +--- + +## Why This Matters + +OpenClaw uses HEARTBEAT.md as a persistent loop marker. Claude Code achieves +the same outcome with more granularity: /loop for in-process polling, CronCreate +for system scheduling, /schedule for remote triggering. The `automation/` directory +in this repo provides macOS launchd examples as an alternative to cron. diff --git a/examples/09-security-hooks/prompt.md b/examples/09-security-hooks/prompt.md new file mode 100644 index 0000000..6392781 --- /dev/null +++ b/examples/09-security-hooks/prompt.md @@ -0,0 +1,62 @@ +# Example 09: Security Hooks + +**Capability:** Claude Code executes hook scripts before and after every tool call. +PreToolUse hooks can block dangerous operations. PostToolUse hooks create audit trails. + +**OpenClaw equivalent:** Docker sandbox, exec approvals, tool deny lists, allowlists. + +--- + +## How the Hooks Work + +The `hooks/` directory in this repo contains two scripts: + +- `pre-tool-use.sh` - runs before every Bash tool call. Blocks destructive patterns. +- `post-tool-use.sh` - runs after every tool call. Appends to `hooks/audit.log`. + +Both are registered in `.claude/settings.json` under the `hooks` key. + +--- + +## The Prompt + +``` +Try running this shell command: rm -rf /tmp/test-deletion-target + +Before running it, explain what you expect the PreToolUse hook to do. +After the attempt, check hooks/audit.log and show me the last 5 entries. +Then explain what was blocked and why it was flagged by the hook. +``` + +--- + +## What Happens + +1. Claude Code calls the Bash tool with `rm -rf /tmp/test-deletion-target` +2. Before execution, `pre-tool-use.sh` receives the command as input +3. The hook matches the `rm -rf` pattern and exits with a non-zero code +4. Claude Code receives the block signal and does not execute the command +5. `post-tool-use.sh` logs the blocked attempt with timestamp and tool name +6. Claude Code reports what happened and shows the audit log + +--- + +## Reading the Audit Log + +```bash +tail -20 hooks/audit.log +``` + +Each entry has the format: `[timestamp] TOOL: bash | STATUS: blocked | CMD: rm -rf ...` + +--- + +## Architecture Difference from OpenClaw + +OpenClaw sandboxes via Docker: the agent runs inside a container that limits +what it can affect on the host. Claude Code sandboxes via permission layers and +hooks: PreToolUse intercepts at the call level, before any syscall happens. + +For personal use, hooks are more flexible. You write exactly the rules you need. +For untrusted third-party agents, Docker isolation is stronger. See +`security/nemoclaw-comparison.md` for a full breakdown. diff --git a/examples/10-full-pipeline/prompt.md b/examples/10-full-pipeline/prompt.md new file mode 100644 index 0000000..1b2e8f3 --- /dev/null +++ b/examples/10-full-pipeline/prompt.md @@ -0,0 +1,72 @@ +# Example 10: Full Pipeline + +**Capability:** A complete workflow combining web search, multi-agent orchestration, +file I/O, memory, hooks, and logging in a single Claude Code run. + +**OpenClaw equivalent:** End-to-end agent pipeline with messaging, skills, and hooks. + +--- + +## What This Demonstrates + +Every capability from examples 01-09 working together: + +| Step | Capability | Example | +|------|-----------|---------| +| 1 | Web search | 03-web-search | +| 2 | Researcher agent | 06-multi-agent | +| 3 | Writer agent | 06-multi-agent | +| 4 | Reviewer agent | 06-multi-agent | +| 5 | File I/O | 02-shell-and-files | +| 6 | Memory update | 05-memory-system | +| 7 | Security logging | 09-security-hooks | +| 8 | Agent runtime loop | 01-agent-runtime | + +--- + +## The Prompt + +``` +Run a full research-to-output pipeline on the topic: "How Claude Code handles +permission modes: plan, autoEdit, and bypassPermissions" + +Pipeline steps: +1. Use the researcher agent to gather information from the web and official docs +2. Pass the research to the writer agent to draft a 400-word explainer +3. Send the draft to the reviewer agent for accuracy and clarity feedback +4. Incorporate the reviewer's feedback into a final version +5. Save the final version to pipeline-output/permission-modes.md +6. Append a pipeline execution summary to memory/pipeline-log.md with: + - Date and time + - Topic researched + - Word count of final output + - Any issues encountered +7. Show me the first 10 lines of the output file to confirm everything worked +``` + +--- + +## What Happens + +Claude Code will coordinate the full pipeline autonomously: + +- The researcher agent uses WebSearch and WebFetch +- The writer agent produces structured prose +- The reviewer agent critiques and returns specific feedback +- A revision loop runs if needed (bounded by maxTurns in settings.json) +- File writes are intercepted by PostToolUse for audit logging +- Memory is updated so the next session knows this pipeline ran + +You will see each agent invocation streamed in sequence. The entire pipeline +typically completes in 2-4 minutes depending on web fetch latency. + +--- + +## Why This Matters + +This is what Claude Code looks like as an actual agent platform, not a +chat assistant. The same architecture, with different prompts and agents, +runs the article production pipeline at `fromaitochitta.com`. + +The companion repo you are reading is the minimal version of that setup. +Clone it, open Claude Code, and run this prompt to see the full stack work. diff --git a/feature-map.md b/feature-map.md new file mode 100644 index 0000000..a447f04 --- /dev/null +++ b/feature-map.md @@ -0,0 +1,78 @@ +# OpenClaw vs Claude Code: Complete Feature Map + +Every major OpenClaw capability, mapped to its Claude Code equivalent. + +## Verdict legend + +| Icon | Verdict | Meaning | +|------|---------|---------| +| ✅ | Full match | Claude Code achieves the same outcome | +| ~ | Different approach | Achievable but requires more setup or different architecture | +| ❌ | Gap | Not possible today without significant workarounds | + +## The map (20 capabilities) + +| # | Capability | OpenClaw | Claude Code | Verdict | +|---|-----------|----------|-------------|---------| +| 1 | Agent Runtime | Long-running daemon, tool exec, streaming | CLI agent loop, tool exec, streaming | ✅ | +| 2 | Shell Execution | `exec` tool, PTY, background, elevated | Bash tool with permission system | ✅ | +| 3 | File I/O | read, write, edit, apply_patch | Read, Write, Edit, Glob, Grep | ✅ | +| 4 | Web Search | Brave Search, Firecrawl fallback | WebSearch + WebFetch (built-in) | ✅ | +| 5 | Browser | CDP/Playwright, screenshots, act | Playwright MCP (same engine) | ✅ | +| 6 | Memory | Daily logs + vector search | CLAUDE.md hierarchy + auto-memory | ~ | +| 7 | Multi-Agent | Sub-agents, mesh, agent-to-agent | Agent Teams, SendMessage, worktree | ✅ | +| 8 | Messaging | 15+ native channels | MCP + Telegram native (v2.1.80) | ~ | +| 9 | Model Providers | 20+ providers, failover | Opus/Sonnet/Haiku + overrides | ~ | +| 10 | Cron/Automation | HEARTBEAT.md, cron, webhooks | /loop, CronCreate, /schedule, hooks | ✅ | +| 11 | Plugin System | openclaw.plugin.json, 20+ hooks | plugin.json, hooks, commands, agents | ✅ | +| 12 | Skills | SKILL.md, ClawHub (5,700+) | Skills + marketplace (2,300+) | ✅ | +| 13 | Security | Docker sandbox, DM pairing | Permission modes, hooks, sandbox | ~ | +| 14 | Voice/TTS | Talk Mode, wake word | Via MCP/scripts (not built-in) | ~ | +| 15 | Companion Apps | macOS, iOS, Android native | VS Code, JetBrains, Desktop, Web | ~ | +| 16 | Gateway | WebSocket server, Control UI | No equivalent (Remote Control partial) | ❌ | +| 17 | Configuration | JSON5, hot-reload, profiles | settings.json hierarchy, CLAUDE.md | ✅ | +| 18 | Canvas/A2UI | Agent-driven HTML workspace | HTML generation + Playwright preview | ❌ | +| 19 | Chat Commands | /status, /model, /think, /mesh | Built-in + custom skills | ✅ | +| 20 | CLI | onboard, gateway, tui, doctor | claude CLI with subcommands | ✅ | + +## Score + +| Verdict | Count | % | +|---------|-------|---| +| ✅ Full match | 11 | 55% | +| ~ Different approach | 7 | 35% | +| ❌ Gap | 2 | 10% | + +## What the gaps mean + +**Gateway/Control Plane (❌):** OpenClaw runs a WebSocket server +with a control UI, webchat, and an OpenAI-compatible API. Claude +Code has no equivalent. Remote Control (research preview) partially +addresses phone access but is not a programmable gateway. + +**Canvas/A2UI (❌):** OpenClaw's canvas is an interactive, +agent-driven HTML workspace served by the gateway. Claude Code can +generate HTML files and preview them via Playwright, but there is +no persistent, interactive canvas surface. + +These are real gaps. They matter most for always-on automation and +visual agent interfaces. For development and task execution, they +are less relevant. + +## Version requirements + +Minimum Claude Code version for full coverage: **v2.1.81** + +| Feature | Version | OpenClaw equivalent | +|---------|---------|-------------------| +| Agent Teams | v2.1.32 | Multi-agent mesh | +| Auto-memory | v2.1.32 | Vector memory | +| Channels + Telegram | v2.1.80 | Multi-channel messaging | +| Permission relay | v2.1.81 | DM approval | +| /loop + CronCreate | v2.1.71 | HEARTBEAT.md + cron | +| Worktree isolation | v2.1.50 | Agent sandboxing | +| disallowedTools | v2.1.78 | Tool deny lists | +| Background agents | v2.1.49 | Sub-agent spawning | +| HTTP hooks | v2.1.63 | Webhook integrations | +| Plugin marketplace | v2.1.6 | ClawHub | +| managed-settings.d | v2.1.84 | Enterprise policy | diff --git a/hooks/README.md b/hooks/README.md new file mode 100644 index 0000000..33e3c7d --- /dev/null +++ b/hooks/README.md @@ -0,0 +1,75 @@ +# Hooks + +Claude Code hooks are shell scripts or HTTP endpoints that run +before or after tool execution. They are the primary security +mechanism for Claude Code, equivalent to OpenClaw's exec approvals +and Docker sandboxing. + +## Files in this directory + +| File | Hook event | Purpose | +|------|-----------|---------| +| `pre-tool-use.sh` | PreToolUse | Blocks dangerous shell commands | +| `post-tool-use.sh` | PostToolUse | Logs all tool executions | +| `audit.log` | (generated) | Append-only audit trail | + +## How hooks work + +Hooks are configured in `.claude/settings.json`: + +```json +{ + "hooks": { + "PreToolUse": [{ + "matcher": "Bash", + "hooks": [{ + "type": "command", + "command": "bash hooks/pre-tool-use.sh" + }] + }] + } +} +``` + +### PreToolUse + +Runs before a tool executes. The script receives JSON on stdin +with `tool_name` and `tool_input`. Return decisions: + +- Exit 0: allow (no output needed) +- Exit 2 + JSON `{"decision": "block", "reason": "..."}`: block the tool call + +### PostToolUse + +Runs after a tool executes. Same stdin format plus `tool_output`. +Cannot block (already executed). Use for logging, notifications, +or triggering follow-up actions. + +### Other hook events + +Claude Code supports these additional events: + +| Event | When it fires | +|-------|--------------| +| SessionStart | When Claude Code launches | +| SessionEnd | When the session closes | +| Stop | When Claude Code finishes a response | +| SubagentStop | When a subagent completes | +| UserPromptSubmit | Before processing user input | +| PreCompact | Before context compaction | +| Notification | When Claude Code shows a notification | + +## Comparison to OpenClaw + +| Feature | OpenClaw | Claude Code | +|---------|----------|-------------| +| Exec blocking | /approve command + DM pairing | PreToolUse hooks | +| Audit logging | command-logger hook | PostToolUse hooks | +| Tool deny lists | Per-session/agent config | disallowedTools + settings.json deny | +| Container isolation | Docker sandbox (off/non-main/all) | macOS sandbox-exec | +| Policy engine | NemoClaw YAML policies | Hook scripts (any logic) | +| HTTP webhooks | Built-in webhook system | HTTP hooks (POST JSON to URL) | + +Claude Code hooks are more flexible (arbitrary shell logic) but +require more setup. OpenClaw's approach is more structured but +less customizable. diff --git a/hooks/post-tool-use.sh b/hooks/post-tool-use.sh new file mode 100755 index 0000000..642a26b --- /dev/null +++ b/hooks/post-tool-use.sh @@ -0,0 +1,21 @@ +#!/bin/bash +# PostToolUse hook: Log all tool executions to an audit trail. +# +# This hook runs AFTER every tool execution and appends a log entry +# to hooks/audit.log. Useful for reviewing what Claude Code did +# during a session. +# +# OpenClaw equivalent: command-logger hook + OpenTelemetry (NemoClaw) +# Claude Code approach: PostToolUse hooks with custom logging + +input=$(cat) +tool_name=$(echo "$input" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null) +tool_input=$(echo "$input" | python3 -c "import sys,json; d=json.load(sys.stdin).get('tool_input',{}); print(d.get('command', d.get('file_path', d.get('pattern', str(d)[:100])))" 2>/dev/null) + +timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ") +log_dir="$(dirname "$0")" +log_file="$log_dir/audit.log" + +echo "$timestamp | $tool_name | $tool_input" >> "$log_file" + +exit 0 diff --git a/hooks/pre-tool-use.sh b/hooks/pre-tool-use.sh new file mode 100755 index 0000000..e619e72 --- /dev/null +++ b/hooks/pre-tool-use.sh @@ -0,0 +1,53 @@ +#!/bin/bash +# PreToolUse hook: Block dangerous shell commands before execution. +# +# This hook reads the tool input from stdin (JSON with tool_name and tool_input) +# and blocks commands that could cause serious damage. +# +# How it works: +# - Claude Code calls this script BEFORE executing any Bash command +# - If the script exits with code 2, the command is BLOCKED +# - The "decision" field in stdout JSON controls the outcome +# +# OpenClaw equivalent: exec approvals + tool deny lists + Docker sandbox +# Claude Code approach: hook-based guardrails (more flexible, user-controlled) + +input=$(cat) +tool_name=$(echo "$input" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null) +command=$(echo "$input" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('command',''))" 2>/dev/null) + +# Only check Bash commands +if [ "$tool_name" != "Bash" ]; then + exit 0 +fi + +# Blocked patterns +blocked_patterns=( + "rm -rf /" + "rm -rf ~" + "rm -rf \$HOME" + "mkfs" + "dd if=" + ":(){:|:&};:" + "chmod -R 777 /" + "curl.*|.*bash" + "wget.*|.*bash" + "curl.*|.*sh" + "wget.*|.*sh" + "> /dev/sda" + "sudo rm" + "shutdown" + "reboot" + "init 0" + "init 6" +) + +for pattern in "${blocked_patterns[@]}"; do + if echo "$command" | grep -qi "$pattern"; then + echo '{"decision": "block", "reason": "Blocked by security hook: command matches dangerous pattern '"'$pattern'"'"}' + exit 2 + fi +done + +# Allow everything else +exit 0 diff --git a/memory/MEMORY.md b/memory/MEMORY.md new file mode 100644 index 0000000..653a588 --- /dev/null +++ b/memory/MEMORY.md @@ -0,0 +1,13 @@ +# Project Memory + +Last updated: [date] + +## Notes + +This is the project's persistent memory. Add notes here that should persist +across Claude Code sessions. + +CLAUDE.md is for instructions (how Claude should behave, what rules to follow). +MEMORY.md is for state (what happened, what was decided, what to pick up next). + +## Preferences diff --git a/memory/README.md b/memory/README.md new file mode 100644 index 0000000..700fc05 --- /dev/null +++ b/memory/README.md @@ -0,0 +1,53 @@ +# Memory System + +How Claude Code and OpenClaw handle cross-session persistence. + +## Claude Code: File-based memory + +Claude Code reads files at session start and writes them back on request. + +**Mechanism:** +- `CLAUDE.md` files at `~/.claude/CLAUDE.md` (global), repo root, and subdirectories +- Auto-memory: files listed in `CLAUDE.md` under `memory:` are auto-loaded +- Project files: any file you explicitly tell Claude to read at session start +- No background process, no indexing, no database + +**Properties:** +- Deterministic: Claude reads exactly what you wrote +- No semantic search: retrieval is positional, not by meaning +- Fully transparent: open any file to see what Claude knows +- Hierarchical: global < project < subdirectory, each level can override + +## OpenClaw: Hybrid memory + +OpenClaw maintains memory through a combination of structured logs and vector search. + +**Mechanism:** +- Daily markdown logs with structured entries +- `MEMORY.md` as a curated summary file +- SQLite-vec or LanceDB for vector storage +- BM25 + cosine similarity for retrieval (hybrid search) + +**Properties:** +- Semantic search: "find notes about authentication" works even without exact keywords +- Automatic logging: entries written by the agent during execution +- Higher complexity: requires a running database +- Retrieval can surface relevant context not explicitly linked + +## Comparison + +| Property | Claude Code | OpenClaw | +|----------------------|---------------------|---------------------------| +| Storage | Plain files | Files + SQLite/LanceDB | +| Retrieval | Positional/explicit | BM25 + cosine (hybrid) | +| Semantic search | No | Yes | +| Setup complexity | Zero | Moderate | +| Transparency | Full | Partial | +| Cross-session | Yes (manual) | Yes (automatic) | + +## Recommendation + +For most projects, Claude Code's file-based approach is sufficient. Keep MEMORY.md +short and curated. Long files degrade quality faster than missing context does. + +Use this directory (`memory/`) to store any project state that should outlast a session. diff --git a/messaging/README.md b/messaging/README.md new file mode 100644 index 0000000..36cb90f --- /dev/null +++ b/messaging/README.md @@ -0,0 +1,45 @@ +# Messaging + +How Claude Code sends and receives messages, compared to OpenClaw. + +## OpenClaw: Native channel integrations + +OpenClaw ships with 15+ channel connectors out of the box: +Slack, Discord, Telegram, Email, SMS, WhatsApp, and others. +Each is configured in a single YAML block. No additional setup. + +## Claude Code: MCP servers + native Telegram + +Claude Code uses MCP servers for most messaging channels. +Telegram is the exception: it has native support since v2.1.80. + +### Native Telegram (no MCP needed) + +Since v2.1.80, Claude Code has a Channels feature with Telegram support. +Since v2.1.81, permission relay allows approving tool calls from your phone. + +Install the Telegram plugin in Claude Code settings, connect your account, +and Claude can send messages and wait for your approval before executing +sensitive actions - from your phone, without opening a laptop. + +This is the closest to OpenClaw's native channel experience. +See `telegram-channels-setup.md`. + +### MCP servers for other channels + +| Channel | MCP Server | Notes | +|----------|-------------------------------|--------------------------| +| Slack | `@modelcontextprotocol/slack` | Official MCP server | +| Discord | Community MCP servers | Search MCP registry | +| Email | SMTP/IMAP MCP servers | Several available | + +The `.mcp.json` in this repo includes commented examples. +See `slack-setup.md` for a complete walkthrough. + +## Honest assessment + +OpenClaw is easier for multi-channel messaging: install once, configure in YAML, +done. Claude Code requires setting up separate MCP servers per channel. + +For single-channel use (Telegram), Claude Code's native support is now comparable. +For complex multi-channel workflows, OpenClaw has the advantage. diff --git a/messaging/slack-setup.md b/messaging/slack-setup.md new file mode 100644 index 0000000..0cd5ecf --- /dev/null +++ b/messaging/slack-setup.md @@ -0,0 +1,56 @@ +# Slack Setup via MCP + +## 1. Create a Slack App + +Go to https://api.slack.com/apps and click "Create New App". +Choose "From scratch". Give it a name and select your workspace. + +## 2. Add Bot Token Scopes + +Navigate to "OAuth & Permissions" in the sidebar. +Under "Bot Token Scopes", add: +- `chat:write` - post messages +- `channels:read` - list channels +- `channels:history` - read messages (if needed) + +## 3. Install to workspace + +Click "Install to Workspace" at the top of the OAuth & Permissions page. +Authorize. Copy the "Bot User OAuth Token" (starts with `xoxb-`). + +## 4. Add to .mcp.json + +```json +{ + "mcpServers": { + "slack": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-slack"], + "env": { + "SLACK_BOT_TOKEN": "xoxb-your-token-here", + "SLACK_TEAM_ID": "T0123456789" + } + } + } +} +``` + +Find your Team ID in the Slack URL when logged into the web app: +`https://app.slack.com/client/T0123456789/...` + +Store the token in an environment variable rather than hardcoding it. + +## 5. Test + +Start Claude Code in your project directory. Try: + +``` +Send a message to #general saying "Claude Code Slack integration is working" +``` + +Claude will use the `slack_post_message` tool from the MCP server. + +## Troubleshooting + +- "not_in_channel": Invite the bot to the channel first (`/invite @your-bot-name`) +- Token not found: verify the env var is exported before launching Claude Code diff --git a/messaging/telegram-channels-setup.md b/messaging/telegram-channels-setup.md new file mode 100644 index 0000000..8868093 --- /dev/null +++ b/messaging/telegram-channels-setup.md @@ -0,0 +1,41 @@ +# Telegram Channels Setup + +Native Telegram support was added in Claude Code v2.1.80. No MCP server needed. + +## What you get + +- **v2.1.80+**: Claude Code can send messages to Telegram +- **v2.1.81+**: Permission relay - Claude pauses on sensitive actions and sends + you an approval request on Telegram. You approve or deny from your phone. + +This is the closest Claude Code equivalent to OpenClaw's native channel integrations. + +## Setup + +1. Open Claude Code settings (gear icon or `/config`) +2. Navigate to Channels or Integrations +3. Select Telegram and click Connect +4. A Telegram bot will send you a link or code to authorize +5. Complete authorization in the Telegram app + +## Usage + +Once connected, Claude Code can: + +``` +Send me a Telegram message when the build finishes +``` + +``` +Ask for my approval before deleting any files +``` + +For permission relay specifically, Claude will send a message like: +"I'm about to run `rm -rf ./dist`. Approve? [Yes] [No]" +You tap Yes or No. Claude proceeds or stops based on your response. + +## Note on MCP alternative + +If you need Telegram features not covered by the native integration, +the `telegram-bot-api` MCP server is available as a fallback. +For most use cases, the native integration is sufficient and simpler. diff --git a/security/README.md b/security/README.md new file mode 100644 index 0000000..266a456 --- /dev/null +++ b/security/README.md @@ -0,0 +1,15 @@ +# Security + +Security in Claude Code is layered: permission modes set the +baseline, hooks enforce custom rules, and settings.json defines +tool restrictions. This is architecturally different from OpenClaw's +container-based isolation but achieves the same goal: controlled +agent behavior. + +## Documents in this directory + +| File | What it covers | +|------|---------------| +| `permission-modes-explained.md` | The three permission modes and when to use each | +| `hook-based-guardrails.md` | Building custom security with PreToolUse hooks | +| `nemoclaw-comparison.md` | Honest comparison with NemoClaw's enterprise security | diff --git a/security/hook-based-guardrails.md b/security/hook-based-guardrails.md new file mode 100644 index 0000000..c07929d --- /dev/null +++ b/security/hook-based-guardrails.md @@ -0,0 +1,108 @@ +# Hook-Based Guardrails + +Hooks are Claude Code's most powerful security mechanism. +Unlike static deny lists, hooks can run arbitrary logic to +decide whether a tool call should proceed. + +## Pattern 1: Block dangerous commands + +See `hooks/pre-tool-use.sh` for a working example. The core +pattern: + +```bash +# Read tool input from stdin +input=$(cat) +command=$(echo "$input" | python3 -c \ + "import sys,json; print(json.load(sys.stdin)['tool_input']['command'])") + +# Check against blocked patterns +if echo "$command" | grep -qi "rm -rf /"; then + echo '{"decision": "block", "reason": "Blocked: recursive delete at root"}' + exit 2 +fi +``` + +## Pattern 2: Restrict file paths + +Block writes outside the project directory: + +```bash +file_path=$(echo "$input" | python3 -c \ + "import sys,json; print(json.load(sys.stdin)['tool_input']['file_path'])") + +project_dir=$(pwd) +if [[ "$file_path" != "$project_dir"* ]]; then + echo '{"decision": "block", "reason": "Blocked: write outside project"}' + exit 2 +fi +``` + +## Pattern 3: Rate limiting + +Prevent runaway API calls: + +```bash +log_file="/tmp/claude-api-calls.log" +echo "$(date +%s)" >> "$log_file" + +# Count calls in last 60 seconds +now=$(date +%s) +recent=$(awk -v now="$now" '$1 > now-60' "$log_file" | wc -l) + +if [ "$recent" -gt 10 ]; then + echo '{"decision": "block", "reason": "Rate limit: >10 calls/minute"}' + exit 2 +fi +``` + +## Pattern 4: Audit trail with HTTP webhook + +Send every tool call to an external logging service: + +```json +{ + "hooks": { + "PostToolUse": [{ + "matcher": "", + "hooks": [{ + "type": "http", + "url": "https://your-logging-service.com/audit", + "headers": { + "Authorization": "Bearer $AUDIT_TOKEN" + } + }] + }] + } +} +``` + +## Pattern 5: Conditional approval + +Block commands only in certain directories: + +```bash +cwd=$(pwd) +if [[ "$cwd" == */production/* ]] && echo "$command" | grep -qi "deploy"; then + echo '{"decision": "block", "reason": "Blocked: deploy from production dir"}' + exit 2 +fi +``` + +## Comparison to OpenClaw security + +OpenClaw uses container isolation (the agent runs inside Docker, +so even if it tries to delete everything, the damage is contained). +Claude Code uses permission layers (the agent is prevented from +trying dangerous things in the first place). + +Neither approach is strictly better: + +- **Container isolation** (OpenClaw): Handles unknown threats. + If a new attack vector emerges, the container still limits damage. +- **Permission hooks** (Claude Code): Handles known threats with + precision. You can write exactly the rules you need. But you must + anticipate the threat. + +For personal use, hooks are more flexible and easier to customize. +For enterprise/multi-tenant environments, container isolation +provides stronger guarantees. diff --git a/security/nemoclaw-comparison.md b/security/nemoclaw-comparison.md new file mode 100644 index 0000000..50fa39c --- /dev/null +++ b/security/nemoclaw-comparison.md @@ -0,0 +1,86 @@ +# NemoClaw vs Claude Code Security + +An honest comparison of security architectures. NemoClaw is +NVIDIA's enterprise layer on top of OpenClaw. Claude Code is +Anthropic's agent platform. They solve security differently. + +## Architecture comparison + +### NemoClaw (4 security layers) + +| Layer | Mechanism | Enforcement | +|-------|-----------|-------------| +| Network | Block non-allowlisted outbound | Kernel (netns) | +| Filesystem | Restrict to /sandbox and /tmp | Kernel (Landlock) | +| Process | Block privilege escalation | Kernel (seccomp) | +| Inference | Route API calls through gateway | Proxy | + +All enforcement is out-of-process. The agent cannot override its +own constraints because they are enforced by the Linux kernel. + +### Claude Code (3 security layers) + +| Layer | Mechanism | Enforcement | +|-------|-----------|-------------| +| Permissions | Allow/deny lists, modes | Claude Code runtime | +| Hooks | PreToolUse/PostToolUse scripts | Shell scripts | +| Sandbox | macOS sandbox-exec | OS-level | + +Hooks run in-process (same machine) but as separate shell processes. +The agent cannot modify hook scripts during execution because file +writes can be restricted. + +## Where NemoClaw wins + +1. **Kernel-level isolation.** Landlock + seccomp + network namespaces + cannot be bypassed by the agent, period. Claude Code hooks can + theoretically be circumvented if permission mode is too permissive. + +2. **Enterprise compliance.** NemoClaw is designed for SOC2, audit + trails, OpenTelemetry integration. Claude Code has basic logging + via hooks but no compliance framework. + +3. **Multi-tenant safety.** NemoClaw sandboxes isolate agents from + each other. Claude Code agents share the host environment (worktree + isolation helps but is git-level, not OS-level). + +## Where Claude Code wins + +1. **Flexibility.** Hooks can contain any logic. NemoClaw policies + are declarative YAML with fixed categories. If you need custom + rules, Claude Code is easier to extend. + +2. **No infrastructure.** NemoClaw requires Docker, 4 vCPU, 8GB RAM, + a 2.4GB sandbox image. Claude Code hooks are bash scripts. + +3. **Speed.** No container startup. Hooks add milliseconds, not + seconds. + +4. **Ecosystem maturity.** Claude Code's permission model is + battle-tested across millions of sessions. NemoClaw is in early + alpha (announced March 2026). + +## Known vulnerabilities + +- **OpenClaw:** CVE-2026-25253 (CVSS 8.8) allowed remote code + execution through crafted skill files. 135K+ instances were + exposed before the patch. +- **ClawHub:** Cisco research found 12% of community-submitted + skills contained malicious code (data exfiltration or prompt + injection payloads). +- **Claude Code:** No known CVEs. The marketplace has a review + process, though its effectiveness varies. + +## Practical recommendation + +| Use case | Better choice | +|----------|--------------| +| Personal automation | Claude Code (simpler, no infra) | +| Enterprise/multi-tenant | NemoClaw (kernel isolation) | +| Compliance-required | NemoClaw (audit trails) | +| Custom security rules | Claude Code (hook flexibility) | +| Untrusted skill ecosystem | NemoClaw (sandbox) or Claude Code (review + hooks) | + +They are not mutually exclusive. You can use Claude Code for +development work and OpenClaw+NemoClaw for always-on automation +where stronger isolation matters. diff --git a/security/permission-modes-explained.md b/security/permission-modes-explained.md new file mode 100644 index 0000000..01d33e3 --- /dev/null +++ b/security/permission-modes-explained.md @@ -0,0 +1,74 @@ +# Permission Modes + +Claude Code has three permission modes that control how much +autonomy the agent has. This is the first line of defense. + +## The three modes + +### 1. Default mode (recommended for learning) + +Claude Code asks permission before every potentially dangerous +action: writing files, running shell commands, making web requests. +You approve or deny each one. + +``` +Claude wants to run: npm install express +Allow? [y/n/always] +``` + +**OpenClaw equivalent:** DM pairing with exec approvals enabled. + +### 2. Auto-edit mode (`--allowedTools`) + +You pre-approve specific tools and patterns. Claude Code runs +those without asking but still prompts for everything else. + +Configured in `.claude/settings.json`: +```json +{ + "permissions": { + "allow": [ + "Read", + "Write", + "Bash(npm test)", + "Bash(ls:*)" + ] + } +} +``` + +**OpenClaw equivalent:** Tool allowlists per agent/session. + +### 3. Bypass mode (`--dangerously-skip-permissions`) + +No permission checks at all. Claude Code executes everything. + +**Never use this for:** +- Untrusted code or repos +- Automated pipelines without hooks +- Any environment with sensitive data + +**Only appropriate for:** +- Isolated sandbox environments +- Testing with expendable data +- CI/CD with compensating controls (hooks) + +**OpenClaw equivalent:** Elevated mode with Docker sandbox. + +## How permission modes interact with hooks + +Hooks run regardless of permission mode. Even in bypass mode, +a PreToolUse hook can block dangerous commands. This is your +safety net. + +``` +Permission mode: decides IF Claude Code can use a tool +Hooks: decide HOW the tool can be used +Settings deny list: decides WHICH tools exist at all +``` + +## Recommendation + +Start with default mode. Move to auto-edit mode once you +understand which operations you trust. Never use bypass mode +outside of sandboxes.