### Initialize Netclaw Configuration

Source: https://github.com/netclaw-dev/netclaw/blob/dev/README.md

Run the guided setup wizard for Netclaw.

```bash
netclaw init
```

--------------------------------

### Complete Secrets Configuration Example

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/spec/configuration.md

An example of secrets.json, showing how to store API keys for providers.

```json
{
  "Providers": {
    "openrouter": {
      "ApiKey": "sk-or-v1-your-key-here"
    }
  }
}
```

--------------------------------

### Complete Netclaw Configuration Example

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/spec/configuration.md

A comprehensive example of netclaw.json, demonstrating configuration for multiple providers, models, session settings, and tools.

```json
{
  "Providers": {
    "local": {
      "Type": "ollama",
      "Endpoint": "http://localhost:11434"
    },
    "openrouter": {
      "Type": "openrouter",
      "Endpoint": "https://openrouter.ai/api/v1"
    }
  },
  "Models": {
    "Main": {
      "Provider": "local",
      "ModelId": "qwen3:30b",
      "ContextWindow": 32768
    },
    "Compaction": {
      "Provider": "local",
      "ModelId": "qwen3:8b"
    }
  },
  "Session": {
    "CompactionThreshold": 0.75,
    "SnapshotInterval": 20,
    "KeepRecentToolResults": 3,
    "MaxToolCallsPerTurn": 30,
    "TurnLlmTimeoutSeconds": 180,
    "ToolExecutionTimeoutSeconds": 90
  },
  "Tools": {
    "ShellTimeoutSeconds": 60,
    "MaxOutputChars": 32000
  }
}
```

--------------------------------

### Install Netclaw CLI Only (Linux/macOS)

Source: https://context7.com/netclaw-dev/netclaw/llms.txt

Installs only the CLI binary to `~/.netclaw/bin`. Use this if you only need the client interface.

```bash
curl -sSL https://releases.netclaw.dev/install.sh | bash -s -- cli
```

--------------------------------

### Netclaw Provider CLI Examples

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/ui/TUI-001-command-wireframes.md

These examples demonstrate the single-shot CLI usage of the `netclaw provider` command for adding, listing, and removing providers.

```bash
$ netclaw provider add --name my-anthropic --type anthropic --auth-method api-key
API key: ****
Provider 'my-anthropic' configured.
```

```bash
$ netclaw provider list
Name            Type         Auth         Status
my-anthropic    anthropic    API key      ✓ valid
local-ollama    ollama       none         ✓ reachable
my-openrouter   openrouter   API key      ✓ valid
```

```bash
$ netclaw provider remove my-openrouter
⚠ Model 'Compaction' references this provider. Reassign first.
```

--------------------------------

### Install Netclaw Daemon Only (Linux/macOS)

Source: https://context7.com/netclaw-dev/netclaw/llms.txt

Installs only the daemon binary to `~/.netclaw/bin`. Use this if you only need the background agent.

```bash
curl -sSL https://releases.netclaw.dev/install.sh | bash -s -- daemon
```

--------------------------------

### Conversational Tool Installation (IronClaw)

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/research/agent-patterns.md

Illustrates a conversational flow for installing and activating tools in IronClaw. This pattern involves searching for the tool via an MCP server, installing its configuration, authenticating through an OAuth flow, and finally activating it to register its capabilities.

```text
User: "add notion"
  -> tool_search("notion")      -> finds MCP server in registry
  -> tool_install("notion")     -> saves config
  -> tool_auth("notion")        -> OAuth flow, returns URL
  -> tool_activate("notion")    -> connects, registers tools
```

--------------------------------

### Install Netclaw CLI and Daemon on Linux

Source: https://github.com/netclaw-dev/netclaw/blob/dev/README.md

Installs both the Netclaw CLI and daemon to `~/.netclaw/bin`. Ensure your system has `curl` installed.

```bash
curl -sSL https://releases.netclaw.dev/install.sh | bash
```

--------------------------------

### Subagent Invocation Example (No Context)

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/runbooks/subagents.md

Example of calling the `spawn_agent` tool without providing additional context.

```json
{
  "agent": "research-assistant",
  "task": "Find the latest .NET 10 breaking changes for Akka.NET compatibility"
}
```

--------------------------------

### Install Specific Netclaw Components on Linux

Source: https://github.com/netclaw-dev/netclaw/blob/dev/README.md

Allows installation of only the CLI or only the daemon. Use this if you need to separate components or manage them independently.

```bash
curl -sSL https://releases.netclaw.dev/install.sh | bash -s -- cli
```

```bash
curl -sSL https://releases.netclaw.dev/install.sh | bash -s -- daemon
```

--------------------------------

### Subagent Invocation Example (With Context)

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/runbooks/subagents.md

Example of calling the `spawn_agent` tool with context, passing workspace state that the subagent might not otherwise see.

```json
{
  "agent": "code-analyst",
  "task": "Summarize the session lifecycle in LlmSessionActor.cs",
  "context": "Workspace is the netclaw repo on branch feature/subagent-stats. The user is investigating an adoption gap and wants a high-level map of how sessions create and reap subagents."
}
```

--------------------------------

### Start netclaw daemon (CLI)

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/runbooks/daemon-upgrade.md

Use this command to start the netclaw daemon after replacing binaries during a direct host upgrade.

```bash
netclaw daemon start
```

--------------------------------

### Tool Approval Prompt Example

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/runbooks/tool-approval-gates.md

Example of an interactive prompt displayed to the user when a tool requires approval. It shows the tool, command, extracted pattern, and response options.

```text
🔒 Tool approval required
> shell_execute: git push origin main
Pattern: git push

Reply with:
  A) Approve once
  B) Approve always
  C) Deny

```

--------------------------------

### Install Netclaw on Windows

Source: https://github.com/netclaw-dev/netclaw/blob/dev/README.md

Installs Netclaw to `%LOCALAPPDATA%\Programs\netclaw` using PowerShell. Ensure PowerShell is configured to run scripts.

```powershell
iwr -useb https://releases.netclaw.dev/install.ps1 | iex
```

--------------------------------

### Netclaw Setup Wizard Wireframe

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/ui/TUI-001-command-wireframes.md

This wireframe illustrates the visual layout of the Netclaw setup wizard's second step, focusing on Slack configuration. It shows input fields for bot and app tokens, along with navigation prompts.

```text
╭─ Netclaw Setup ──────────────────────────────────────────────╮
│                                                              │
│  Step 2 of 6: Slack Configuration        [■■□□□□□] 33%      │
│                                                              │
│  ╭─ Slack Bot Token ───────────────────────────────────────╮ │
│  │ xoxb-************************************               │ │
│  ╰─────────────────────────────────────────────────────────╯ │
│                                                              │
│  ╭─ Slack App Token ───────────────────────────────────────╮ │
│  │ xapp-************************************               │ │
│  ╰─────────────────────────────────────────────────────────╯ │
│                                                              │
│  ℹ  Socket Mode requires both tokens. See:                  │
│     https://api.slack.com/apis/socket-mode                   │
│                                                              │
│  [Enter] Next   [Esc] Back   [Ctrl+Q] Quit                  │
╰──────────────────────────────────────────────────────────────╯
```

--------------------------------

### Start netclaw daemon (systemd)

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/runbooks/daemon-upgrade.md

Use this command to start the netclaw daemon via systemd user services after replacing binaries during a direct host upgrade.

```bash
systemctl --user start netclaw
```

--------------------------------

### Netclaw Daemon Management Commands

Source: https://context7.com/netclaw-dev/netclaw/llms.txt

Commands to control the Netclaw daemon process, including starting, stopping, checking status, and installation as a systemd service.

```bash
# Start the daemon as a detached background process
netclaw daemon start
```

```bash
# Check running status (PID, uptime, port, active session count)
netclaw daemon status
```

```bash
# Stop gracefully (drains active sessions, then shuts down actor system)
netclaw daemon stop
```

```bash
# Install as a systemd user service (Linux — no sudo required)
netclaw daemon install
systemctl --user enable netclaw
systemctl --user start netclaw
```

```bash
# Uninstall systemd service
netclaw daemon uninstall
```

```bash
# Health endpoints exposed by the daemon
curl http://127.0.0.1:5199/api/health/ready    # readiness probe (200 = ready)
curl http://127.0.0.1:5199/api/health/status   # runtime status JSON
```

```bash
# Upgrade: stop → back up db → replace binaries → start → verify
netclaw daemon stop
cp ~/.netclaw/netclaw.db ~/.netclaw/netclaw.db.bak.$(date +%s)
# replace binaries …
netclaw daemon start
netclaw daemon status
```

--------------------------------

### Search Tools Query Examples

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/adr/ADR-003-progressive-tool-disclosure-and-dynamic-discovery.md

Demonstrates the different query types supported by the `search_tools` function for progressive tool discovery. Use `servers` to find capability servers, `all` to list all tools on a server, and a specific query with a server to find tools for a particular intent.

```go
search_tools(query: "servers")
search_tools(query: "all", server: "<server>")
search_tools(query: "<intent>", server: "<server>")
```

--------------------------------

### Start Smoke Sandbox

Source: https://github.com/netclaw-dev/netclaw/blob/dev/CONTRIBUTING.md

Starts the developer-only integration sandbox, including building the local image, starting Ollama, and pulling a model.

```bash
# Start sandbox (build local image + start Ollama + pull tiny model)
scripts/smoke/up.sh
```

```bash
# Start without rebuilding image (useful after pre-building or in CI)
SMOKE_BUILD=0 scripts/smoke/up.sh
```

--------------------------------

### Check for and Install Netclaw Updates

Source: https://context7.com/netclaw-dev/netclaw/llms.txt

Use this command to check for available updates and install them. Ensure you have the necessary permissions to modify the Netclaw installation.

```bash
netclaw update
```

--------------------------------

### Skill File Structure and Startup

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/adr/ADR-002-unified-context-discovery.md

Skills are organized as `.md` files in `~/.netclaw/skills/`. Built-in skills are copied on first run, preserving user-created files. The system prompt is injected with a compressed index of available skills.

```shell
~/.netclaw/skills/
  ├── netclaw-identity.md    (built-in, copied from embedded resources)
  ├── netclaw-diagnostics.md       (built-in)
  └── user-created-skill.md     (user-created)

Startup:
  CopyBuiltInSkills() → SkillScanner.Scan() → SkillRegistry → SkillIndexContextLayer

System prompt injection:
  SkillIndexContextLayer → "[skills — read with file_read for full instructions] 
    netclaw-identity (/home/user/.netclaw/skills/netclaw-identity.md)
      How to read and update Netclaw identity files ...
    memorizer-usage (/home/user/.netclaw/skills/memorizer-usage.md)
      How to use the Memorizer MCP server ...
    netclaw-diagnostics (/home/user/.netclaw/skills/netclaw-diagnostics.md)
      How to check Netclaw configuration ..."
```

--------------------------------

### Install Netclaw as a .NET Global Tool

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/spec/SPEC-011-daemon-architecture.md

For .NET developers, Netclaw can be installed as a global tool using the 'dotnet tool install' command. This method automatically handles PATH management.

```bash
dotnet tool install --global netclaw
```

--------------------------------

### Install Pinned Netclaw Version on Linux

Source: https://github.com/netclaw-dev/netclaw/blob/dev/README.md

Installs a specific version of Netclaw by setting the `NETCLAW_VERSION` environment variable before running the install script. Useful for reproducible builds or testing specific releases.

```bash
NETCLAW_VERSION=0.17.1 curl -sSL https://releases.netclaw.dev/install.sh | bash
```

--------------------------------

### Environment Inventory Example

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/prd/PRD-007-agent-personality-and-local-memory.md

Shows the format of the environment inventory JSON file, detailing the host system, available tools, their versions, and MCP server reachability.

```json
{
  "last_scan": "2026-02-21T10:00:00Z",
  "host": {
    "hostname": "pi1",
    "os": "linux",
    "arch": "arm64"
  },
  "tools": {
    "git": { "available": true, "version": "2.43.0", "hosts": ["github.com"] },
    "gh": { "available": true, "version": "2.44.0" },
    "claude": { "available": false },
    "opencode": { "available": false },
    "dotnet": { "available": true, "version": "10.0.100" },
    "node": { "available": false }
  },
  "mcp_servers": {
    "memorizer": { "configured": true, "reachable": true }
  }
}

```

--------------------------------

### Project Registry Example

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/prd/PRD-007-agent-personality-and-local-memory.md

Illustrates the structure of the project registry JSON file, which stores metadata for registered projects, including their paths and associated capabilities.

```json
{
  "projects": [
    {
      "name": "netclaw",
      "path": "/home/user/repos/netclaw",
      "agents_md": "/home/user/repos/netclaw/AGENTS.md",
      "channels": ["C0123NETCLAW"],
      "capabilities": {
        "language": "csharp",
        "framework": "akka.net",
        "has_tests": true,
        "has_ci": true
      }
    }
  ]
}

```

--------------------------------

### Initialize Netclaw and Run Evals

Source: https://github.com/netclaw-dev/netclaw/blob/dev/evals/README.md

One-time initialization of netclaw on the host to borrow identity files, followed by running the full eval suite against a specified LLM endpoint. Requires setting environment variables for provider type, endpoint, and model ID.

```bash
# One-time: run netclaw init on the host so the eval script can borrow
# your identity files (SOUL.md, AGENTS.md, TOOLING.md).
netclaw init

# Run the full suite against your preferred LLM endpoint.
NETCLAW_EVAL_PROVIDER_TYPE=ollama \
NETCLAW_EVAL_PROVIDER_ENDPOINT=http://my-gpu-server.tailnet.ts.net:11434 \
NETCLAW_EVAL_MODEL_ID=qwen3:30b \
  ./evals/run-evals.sh
```

--------------------------------

### Install Netclaw systemd Service

Source: https://github.com/netclaw-dev/netclaw/blob/dev/README.md

Use the CLI command to install a user-level systemd service for the Netclaw daemon on Linux.

```bash
netclaw daemon install
```

--------------------------------

### Example Generic Advice Query

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/research/deterministic-memory-retrieval-architecture.md

Shows a prompt that is considered a generic advice query, indicating low memory activation and suggesting it might be better served by world knowledge or live search.

```text
- `what's the best way to find cheap flights`
  - generic advice query
  - low memory activation
  - probably better served by world knowledge or live search
```

--------------------------------

### Install Script Regression Tests

Source: https://context7.com/netclaw-dev/netclaw/llms.txt

Run regression tests for the Netclaw installation scripts on Linux/macOS and Windows. These tests do not require network access or a .NET build.

```bash
bash scripts/smoke/install-smoke.sh            # Linux/macOS installer
```

```powershell
pwsh scripts/smoke/install-smoke.ps1           # Windows installer
```

--------------------------------

### Build and Test Netclaw Project

Source: https://github.com/netclaw-dev/netclaw/blob/dev/CONTRIBUTING.md

Commands to build the solution, run tests, and analyze with slopwatch.

```bash
dotnet build Netclaw.slnx
dotnet test Netclaw.slnx
dotnet slopwatch analyze
```

--------------------------------

### Tool Execution Audit Log Examples

Source: https://github.com/netclaw-dev/netclaw/blob/dev/docs/runbooks/tool-approval-gates.md

Illustrates different audit log entries for tool execution, including approved, previously approved, denied by user, and timed-out scenarios. Shows how approval decisions and patterns are recorded.

```text
Tool executed: shell_execute (approved, pattern=git push)
Tool executed: shell_execute (PreviouslyApproved, pattern=git push [persistent: git push in /home/user/repo])
Tool denied: shell_execute (denied_by_user, pattern=docker rm)
Tool denied: shell_execute (timed_out, pattern=kubectl apply)
```