### AI Assistant Prompt for nix-clawdbot Setup

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/README.md

A prompt to be given to an AI assistant to automate the setup of nix-clawdbot. It outlines the repository, what Clawdbot is, and the steps the AI should take, including Nix installation, configuration file creation, secret management, and verification.

```text
I want to set up nix-clawdbot on my machine (macOS or Linux).

Repository: github:clawdbot/nix-clawdbot

What nix-clawdbot is:
- Batteries-included Nix package for Clawdbot (AI assistant gateway)
- Installs gateway + tools everywhere; macOS app only on macOS
- Runs as a launchd service on macOS, systemd user service on Linux

What I need you to do:
1. Check if Determinate Nix is installed (if not, install it)
2. Create a local flake at ~/code/clawdbot-local using templates/agent-first/flake.nix
3. Create a docs dir next to the config (e.g., ~/code/clawdbot-local/documents) with AGENTS.md, SOUL.md, TOOLS.md
   - If ~/.clawdbot/workspace already has these files, adopt them into the documents dir first
4. Help me create a Telegram bot (@BotFather) and get my chat ID (@userinfobot)
5. Set up secrets (bot token, Anthropic key) - plain files at ~/.secrets/ is fine
6. Fill in the template placeholders and run home-manager switch
7. Verify: service running, bot responds to messages

My setup:
- OS: [macOS / Linux]
- CPU: [arm64 / x86_64]
- System: [aarch64-darwin / x86_64-darwin / x86_64-linux]
- Home Manager config name: [FILL IN or "I don't have Home Manager yet"]

Reference the README and templates/agent-first/flake.nix in the repo for the module options.
```

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

### Linux Manual Setup for nix-clawdbot

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/README.md

Manual setup instructions for nix-clawdbot on Linux using systemd user services. This includes installing Determinate Nix, creating a local flake, configuring placeholders in `flake.nix`, applying the configuration with Home Manager, and verifying the service and logs.

```bash
mkdir -p ~/code/clawdbot-local && cd ~/code/clawdbot-local
nix flake init -t github:clawdbot/nix-clawdbot#agent-first

# Edit flake.nix placeholders:
# system = "x86_64-linux"
# home.username and home.homeDirectory (e.g., "/home/<user>")
# programs.clawdbot.documents with AGENTS.md, SOUL.md, TOOLS.md
# Provider secrets (Telegram/Discord tokens, Anthropic API key)

home-manager switch --flake .#<user>

systemctl --user status clawdbot-gateway
journalctl --user -u clawdbot-gateway -f
```

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

### macOS Manual Setup for nix-clawdbot

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/README.md

Manual setup instructions for nix-clawdbot on macOS using Home Manager and launchd. This involves installing Determinate Nix, initializing a local flake, editing configuration placeholders, applying the configuration, and verifying the service status.

```bash
mkdir -p ~/code/clawdbot-local && cd ~/code/clawdbot-local
nix flake init -t github:clawdbot/nix-clawdbot#agent-first

# Edit flake.nix placeholders:
# system = "aarch64-darwin" (Apple Silicon) or "x86_64-darwin" (Intel)
# home.username and home.homeDirectory
# programs.clawdbot.documents with AGENTS.md, SOUL.md, TOOLS.md
# Provider secrets (Telegram/Discord tokens, Anthropic API key)

home-manager switch --flake .#<user>

launchctl print gui/$UID/com.steipete.clawdbot.gateway | grep state
```

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

### Clawdbot Plugin SKILL.md Example

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/README.md

An example of a `SKILL.md` file for a Clawdbot plugin. This file teaches the AI how to use the plugin's functionality, including its name, a brief description, and instructions on how to invoke its associated CLI tools.

```markdown
---
name: hello-world
description: Prints hello world.
---

Use the `hello` CLI to print a greeting.
```

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

### Minimal Capability Plugin Example (Nix)

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/docs/plugins-maintainers.md

An example of a minimal Clawdbot plugin contract for a 'summarize' tool, written in Nix. It includes the plugin name, skills, and package.

```nix
clawdbotPlugin = {
  name = "summarize";
  skills = [ ./skills/summarize ];
  packages = [ self.packages.${system}.summarize-cli ];
  needs = { stateDirs = []; requiredEnv = []; };
};

```

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

### Add Community Plugins to Nix Clawdbot Configuration

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/README.md

This Nix configuration snippet demonstrates how to add community plugins to your Nix Clawdbot setup. Plugins are specified with their GitHub repository source. After adding the plugin to your configuration, you need to run `home-manager switch` to apply the changes and install the plugin.

```nix
plugins = [
  { source = "github:owner/repo-name"; }
];
```

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

### Initialize Clawdbot Flake Configuration (Bash)

Source: https://context7.com/clawdbot/nix-clawdbot/llms.txt

Guides users through bootstrapping a new Clawdbot configuration using the agent-first Nix flake template. It covers creating a project directory, initializing the flake, editing the `flake.nix` file with essential placeholders, setting up required document files (AGENTS.md, SOUL.md, TOOLS.md), and applying the initial configuration.

```bash
# Create a new Clawdbot configuration directory
mkdir -p ~/code/clawdbot-local && cd ~/code/clawdbot-local

# Initialize from the agent-first template
nix flake init -t github:clawdbot/nix-clawdbot#agent-first

# Edit flake.nix to fill in placeholders:
# - system: aarch64-darwin, x86_64-darwin, or x86_64-linux
# - home.username: your username (run `whoami`)
# - home.homeDirectory: /Users/<user> (macOS) or /home/<user> (Linux)
# - botTokenFile: path to your Telegram bot token
# - allowFrom: your Telegram user ID
# - apiKeyFile: path to your Anthropic API key

# Create documents directory with required files
mkdir -p documents
cat > documents/AGENTS.md << 'EOF'
# AGENTS.md
Principles:
- Be concise in chat
- Prefer explicit changes
EOF

cat > documents/SOUL.md << 'EOF'
# SOUL.md
You are a helpful assistant.
EOF

cat > documents/TOOLS.md << 'EOF'
# TOOLS.md
Available tools are listed below.
EOF

# Apply the configuration
home-manager switch --flake .#myuser

```

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

### Markdown Skill Example for gohome CLI

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/docs/rfc/2026-01-11-plugin-system.md

An example of how a skill might document the command-line interface for the 'gohome' plugin. It shows commands for controlling roborock devices and tado thermostats, as well as how to share media like device maps.

```markdown
## Friendly CLI
gohome-cli roborock status
gohome-cli roborock clean kitchen
gohome-cli tado set living-room 20

## Sending maps to users
MEDIA:http://gohome:8080/roborock/map.png?labels=names
```

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

### Nix Configuration for xuezh Plugin

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/docs/rfc/2026-01-11-plugin-system.md

An example Nix configuration for the 'xuezh' plugin, detailing its name, skills, packages, required state directories, and environment variables. This configuration ensures the plugin's binary is built, skills are linked, state directories are created, and necessary environment variables are validated upon installation.

```nix
clawdbotPlugin = {
  name = "xuezh";
  skills = [ ./skills/xuezh ];
  packages = [ self.packages.${system}.default ];
  needs = {
    stateDirs = [ ".config/xuezh" ];
    requiredEnv = [
      "XUEZH_AZURE_SPEECH_KEY_FILE"
      "XUEZH_AZURE_SPEECH_REGION"
    ];
  };
};
```

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

### Nix Flake for Dual Instance Clawdbot Setup

Source: https://context7.com/clawdbot/nix-clawdbot/llms.txt

This Nix flake defines the configuration for Nix Clawdbot, enabling a dual instance setup for both production and development environments. It imports necessary inputs like nixpkgs, home-manager, and the nix-clawdbot package itself. The configuration specifies system architecture, package overlays, and detailed settings for both 'prod' and 'dev' instances, including provider configurations and plugin sources.

```nix
# flake.nix - Dual instance setup (prod + dev)
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    nix-clawdbot.url = "github:clawdbot/nix-clawdbot?ref=v0.1.0";
  };

  outputs = { self, nixpkgs, home-manager, nix-clawdbot }:
    let
      system = "aarch64-darwin";
      pkgs = import nixpkgs { inherit system; overlays = [ nix-clawdbot.overlays.default ]; };

      # Shared base configuration
      prod = {
        enable = true;
        package = nix-clawdbot.packages.${system}.clawdbot-gateway;
        providers.telegram = {
          enable = true;
          botTokenFile = "/run/agenix/telegram-prod";
          allowFrom = [ 12345678 -1001234567890 ];
          groups = {
            "*" = { requireMention = true; };
            "-1001234567890" = { requireMention = false; }; # couples group
          };
        };
        providers.anthropic.apiKeyFile = "/run/agenix/anthropic-api-key";
        plugins = [
          { source = "github:clawdbot/nix-steipete-tools?dir=tools/oracle"; }
          { source = "github:clawdbot/nix-steipete-tools?dir=tools/peekaboo"; }
        ];
      };
    in {
      homeConfigurations."myuser" = home-manager.lib.homeManagerConfiguration {
        inherit pkgs;
        modules = [
          nix-clawdbot.homeManagerModules.clawdbot
          {
            home.username = "myuser";
            home.homeDirectory = "/Users/myuser";
            home.stateVersion = "24.11";
            programs.home-manager.enable = true;

            programs.clawdbot = {
              appPackage = nix-clawdbot.packages.${system}.clawdbot-app;
              documents = ./documents;

              instances = {
                prod = prod;

                dev = prod // {
                  providers.telegram.botTokenFile = "/run/agenix/telegram-dev";
                  gatewayPort = 18790;
                  gatewayPath = "/Users/myuser/code/clawdbot"; # Local checkout
                  plugins = prod.plugins ++ [
                    { source = "path:/Users/myuser/code/my-plugin"; }
                  ];
                };
              };
            };
          }
        ];
      };
    };
}

```

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

### Full Plugin Authoring Prompt for Clawdbot

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/README.md

A comprehensive prompt to guide an AI agent in making a repository a Nix-Clawdbot-native plugin. It outlines the contract to implement, including `flake.nix` outputs, environment configuration, `AGENTS.md`, and `SKILL.md` updates.

```text
Goal: Make this repo a nix-clawdbot-native plugin with the standard contract.

Contract to implement:
1) Add clawdbotPlugin output in flake.nix:
   - name
   - skills (paths to SKILL.md dirs)
   - packages (CLI packages to put on PATH)
   - needs (stateDirs + requiredEnv)

Example:
clawdbotPlugin = {
  name = "my-plugin";
  skills = [ ./skills/my-plugin ];
  packages = [ self.packages.${system}.default ];
  needs = {
    stateDirs = [ ".config/my-plugin" ];
    requiredEnv = [ "MYPLUGIN_AUTH_FILE" ];
  };
};

2) Make the CLI explicitly configurable by env (no magic defaults):
   - Support an auth file env (e.g., MYPLUGIN_AUTH_FILE)
   - Honor XDG_CONFIG_HOME or a plugin-specific config dir env

3) Provide AGENTS.md in the plugin repo:
   - Plain-English explanation of knobs + values
   - Generic placeholders only (no real secrets)
   - Explain where credentials live (e.g., /run/agenix/...)

4) Update SKILL.md to call the CLI by its PATH name.

Standard plugin config shape (Nix-native, no JSON strings):

plugins = [
  {
    source = "github:owner/my-plugin";
    config = {
      env = {
        MYPLUGIN_AUTH_FILE = "/run/agenix/myplugin-auth";
      };
      settings = {
        name = "EXAMPLE_NAME";
        enabled = true;
        retries = 3;
        tags = [ "alpha" "beta" ];
        window = { start = "08:00"; end = "18:00"; };
        options = { mode = "fast"; level = 2; };
      };
    };
  }
];

Config flags the host will use:
- `config.env` for required env vars (e.g., MYPLUGIN_AUTH_FILE)
- `config.settings` for typed config keys (rendered to config.json in the first stateDir)

CI note:
- If the repo uses Garnix, add the plugin build to its `garnix.yaml` (or equivalent) so CI verifies it.

Why: explicit, minimal, fail-fast, no inline JSON strings.
Deliverables: flake output, env overrides, AGENTS.md, skill update.
```

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

### Minimal Clawdbot Nix Configuration

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/README.md

A basic Nix configuration for Clawdbot, enabling the service and configuring essential providers like Telegram and Anthropic. It also includes an example of how to add built-in plugins.

```nix
{
  programs.clawdbot = {
    enable = true;
    providers.telegram = {
      enable = true;
      botTokenFile = "/run/agenix/telegram-bot-token"; # any file path works
      allowFrom = [ 12345678 ];  # your Telegram user ID
    };
    providers.anthropic = {
      apiKeyFile = "/run/agenix/anthropic-api-key"; # any file path works
    };

    # Built-ins (tools + skills) shipped via nix-steipete-tools.
    plugins = [
      { source = "github:clawdbot/nix-steipete-tools?dir=tools/summarize"; }
    ];
  };
}

Then: `home-manager switch --flake .#youruser`
```

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

### Configure Third-Party Clawdbot Plugins with Settings

Source: https://context7.com/clawdbot/nix-clawdbot/llms.txt

This Nix configuration shows how to integrate third-party plugins into Nix Clawdbot, including setting environment variables for authentication and defining custom settings that are rendered into the plugin's configuration file. It provides examples for a simple plugin and a more complex one with specific venue and time preferences. Telegram and Anthropic provider configurations are also included.

```nix
# Plugin configuration with env vars and settings
programs.clawdbot = {
  enable = true;

  plugins = [
    # Simple plugin without config
    { source = "github:acme/hello-world"; }

    # Plugin with environment variables and settings
    {
      source = "github:joshp123/padel-cli";
      config = {
        # Environment variables (paths to secrets/auth files)
        env = {
          PADEL_AUTH_FILE = "/run/agenix/padel-auth";
        };
        # Settings rendered to config.json in plugin's stateDir
        settings = {
          default_location = "Barcelona";
          preferred_times = [ "18:00" "20:00" ];
          preferred_duration = 90;
          venues = [
            {
              id = "venue-123";
              alias = "home-court";
              name = "Padel Barcelona Center";
              indoor = true;
              timezone = "Europe/Madrid";
            }
          ];
        };
      };
    }
  ];

  providers.telegram = {
    enable = true;
    botTokenFile = "~/.secrets/telegram-token";
    allowFrom = [ 12345678 ];
  };

  providers.anthropic.apiKeyFile = "~/.secrets/anthropic-key";
};

```

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

### Set Up Dual Clawdbot Instances (Prod & Dev) with Nix

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/README.md

Configures separate production and development instances of Clawdbot using a shared base configuration. This setup allows for local development overrides while maintaining a stable production environment. It involves pinning the macOS app and gateway from a specific Nix channel and overriding gateway paths or ports for development.

```nix
# flake inputs (pin prod + app)
inputs = {
  nix-clawdbot.url = "github:clawdbot/nix-clawdbot?ref=v0.1.0"; # pins macOS app + gateway bundle
};

let
  prod = {
    enable = true;
    # Prod gateway pin (comes from nix-clawdbot input @ v0.1.0 above).
    package = inputs.nix-clawdbot.packages.${pkgs.system}.clawdbot-gateway;
    providers.telegram.enable = true;
    providers.telegram.botTokenFile = "/run/agenix/telegram-prod";
    providers.telegram.allowFrom = [ 12345678 ];
    providers.anthropic.apiKeyFile = "/run/agenix/anthropic-api-key";
    plugins = [ { source = "github:owner/your-plugin"; } ];
  };
in {
  # Pinned macOS app (POC: no local app builds, uses nix-clawdbot @ v0.1.0 above).
  programs.clawdbot.appPackage =
    inputs.nix-clawdbot.packages.${pkgs.system}.clawdbot-app;
  programs.clawdbot.documents = ./documents;
  programs.clawdbot.instances = {
    prod = prod;
    dev = prod // {
      # Dev uses the same pinned macOS app (from nix-clawdbot input),
      # but overrides the gateway package to a local checkout.
      providers.telegram.botTokenFile = "/run/agenix/telegram-dev";
      gatewayPort = 18790;
      # Local gateway checkout (path). App stays pinned.
      gatewayPath = "/Users/you/code/clawdbot";
      # Local plugin overrides prod if names collide (last wins).
      plugins = prod.plugins ++ [
        { source = "path:/Users/you/code/your-plugin"; }
        {
          source = "github:joshp123/padel-cli";
          config = {
            env = { PADEL_AUTH_FILE = "/run/agenix/padel-auth-dev"; };
            settings = {
              default_location = "CITY_NAME";
              preferred_times = [ "18:00" ];
              preferred_duration = 90;
              venues = [];
            };
          };
        }
      ];
    };
  };
}
```

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

### Enable First-Party Clawdbot Plugins in Home Manager

Source: https://context7.com/clawdbot/nix-clawdbot/llms.txt

This Nix configuration snippet demonstrates how to enable and disable various first-party plugins for Nix Clawdbot within a Home Manager setup. It allows granular control over features like summarization, screen capture, web search, and more by setting boolean flags. The configuration also includes settings for Telegram and Anthropic providers.

```nix
# In your Home Manager configuration
programs.clawdbot = {
  enable = true;

  # Toggle first-party plugins (all from nix-steipete-tools)
  firstParty = {
    summarize.enable = true;    # Summarize URLs, PDFs, YouTube videos
    peekaboo.enable = true;     # Screenshot your screen
    oracle.enable = true;       # Web search
    poltergeist.enable = false; # Click, type, control macOS UI
    sag.enable = false;         # Text-to-speech
    camsnap.enable = false;     # Camera snapshots
    gogcli.enable = false;      # Google Calendar integration
    bird.enable = false;        # Twitter/X integration
    sonoscli.enable = false;    # Sonos speaker control
    imsg.enable = false;        # iMessage send/read
  };

  providers.telegram = {
    enable = true;
    botTokenFile = "~/.secrets/telegram-token";
    allowFrom = [ 12345678 ];
  };

  providers.anthropic.apiKeyFile = "~/.secrets/anthropic-key";
};

```

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

### nix-clawdbot Plugin Configuration in User's flake.nix

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/docs/rfc/2026-01-11-plugin-system.md

Illustrates how to configure clawdbot plugins within a user's Nix flake configuration. It shows examples of specifying remote plugins via GitHub repositories, local development paths, and enabling first-party plugins.

```nix
# User's flake.nix
programs.clawdbot.plugins = [
  # Remote: point at GitHub repo
  { source = "github:joshp123/xuezh"; }
  { source = "github:joshp123/padel-cli"; }

  # Local dev: point at directory
  { source = "path:/Users/josh/code/my-plugin"; }
];

# Or enable first-party plugins (pinned in nix-clawdbot):
programs.clawdbot.firstParty.summarize.enable = true;
programs.clawdbot.firstParty.oracle.enable = true;
```

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

### Voice-call CLI Commands for Webhook Handling

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/docs/rfc/2026-01-11-plugin-system.md

Demonstrates the command-line interface commands used to manage webhook handling for the voice-call feature. This includes starting a webhook server, initiating a call, and checking call status, illustrating how the agent interacts with the CLI for real-time webhook functionality.

```bash
voicecall expose --mode funnel    # Start webhook server
voicecall init --to +1... --message "..."  # Agent calls CLI
voicecall status --call-id abc123  # Check for responses
```

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

### Home Manager Rollback Command

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/README.md

Demonstrates how to list available generations and perform a rollback using home-manager.

```bash
# Rollback
home-manager generations  # list
home-manager switch --rollback  # revert
```

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

### Configure Clawdbot with Sensible Defaults (Nix)

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/README.md

Sets up Clawdbot with default configurations, enabling Telegram and Anthropic providers, and specifying plugins. It uses `instances.default` to manage per-group mention rules. Dependencies include `pkgs.clawdbot` for the package.

```nix
{ programs.clawdbot = {
    documents = ./documents;
    instances.default = {
      enable = true;
      package = pkgs.clawdbot; # batteries-included
      stateDir = "~/.clawdbot";
      workspaceDir = "~/.clawdbot/workspace";

      providers.telegram = {
        enable = true;
        botTokenFile = "/run/agenix/telegram-bot-token";
        allowFrom = [
          12345678         # you (DM)
          -1001234567890   # couples group (no @mention required)
          -1002345678901   # noisy group (require @mention)
        ];
        groups = {
          "*" = { requireMention = true; };
          "-1001234567890" = { requireMention = false; }; # couples group
          "-1002345678901" = { requireMention = true; };  # noisy group
        };
      };

      providers.anthropic.apiKeyFile = "/run/agenix/anthropic-api-key";

      launchd.enable = true;

      # Plugins (prod: pinned GitHub). Built-ins are via nix-steipete-tools.
      # MVP target: repo pointers resolve to tools + skills automatically.
      plugins = [
        { source = "github:clawdbot/nix-steipete-tools?dir=tools/oracle"; }
        { source = "github:clawdbot/nix-steipete-tools?dir=tools/peekaboo"; }
        { source = "github:joshp123/xuezh"; }
        {
          source = "github:joshp123/padel-cli";
          config = {
            env = { PADEL_AUTH_FILE = "/run/agenix/padel-auth"; };
            settings = {
              default_location = "CITY_NAME";
              preferred_times = [ "18:00" "20:00" ];
              preferred_duration = 90;
              venues = [
                {
                  id = "VENUE_ID";
                  alias = "VENUE_ALIAS";
                  name = "VENUE_NAME";
                  indoor = true;
                  timezone = "TIMEZONE";
                }
              ];
            };
          };
        }
      ];
    };
  };
}
```

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

### Enable First-Party Nix Clawdbot Plugins

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/README.md

This Nix configuration snippet shows how to enable various first-party plugins for Clawdbot. Each plugin offers a specific functionality, such as summarizing content, taking screenshots, or web searching. To use a plugin, set its corresponding `.enable` attribute to `true` in your configuration.

```nix
programs.clawdbot.firstParty = {
  summarize.enable = true;   # Summarize web pages, PDFs, videos
  peekaboo.enable = true;    # Take screenshots
  oracle.enable = false;     # Web search
  poltergeist.enable = false; # Control your macOS UI
  sag.enable = false;        # Text-to-speech
  camsnap.enable = false;    # Camera snapshots
  gogcli.enable = false;     # Google Calendar
  bird.enable = false;       # Twitter/X
  sonoscli.enable = false;   # Sonos control
  imsg.enable = false;       # iMessage
};
```

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

### Build Go CLI Tool and Clawdbot Plugin (Nix)

Source: https://context7.com/clawdbot/nix-clawdbot/llms.txt

Defines a Nix package for a Go CLI tool named 'hello-world' and configures it as a Clawdbot plugin. It specifies dependencies like nixpkgs and flake-utils, and defines the plugin's name, skills, and package requirements.

```nix
{
  description = "Hello-world Clawdbot plugin";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = import nixpkgs { inherit system; };
      in {
        # Build the CLI tool
        packages.default = pkgs.buildGoModule {
          pname = "hello-world";
          version = "0.1.0";
          src = ./.;
          vendorHash = null;
        };

        # Plugin contract - required for nix-clawdbot integration
        clawdbotPlugin = {
          name = "hello-world";
          skills = [ ./skills/hello-world ];           # Paths to SKILL.md directories
          packages = [ self.packages.${system}.default ]; # CLI packages to put on PATH
          needs = {
            stateDirs = [];          # Directories to create (relative to ~)
            requiredEnv = [];        # Required environment variables
          };
        };
      }
    );
}

```

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

### Enabling a Plugin in Host Configuration (Nix)

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/docs/plugins-maintainers.md

Demonstrates how to enable a specific plugin, like 'summarize', within the host's Clawdbot configuration using Nix. It specifies the source of the plugin.

```nix
programs.clawdbot.instances.default.plugins = [
  { source = "github:clawdbot/nix-steipete-tools?dir=tools/summarize"; }
];

```

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

### Exclude Built-in Clawdbot Tools (Nix)

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/README.md

Allows exclusion of specific built-in tools from Clawdbot's package, useful when these tools are managed externally. For example, excluding 'git' if `programs.git.enable` is set to true in Home Manager.

```nix
programs.clawdbot.excludeTools = [ "git" "jq" "ripgrep" ];
```

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

### Host-side Plugin Configuration in Nix

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/docs/plugins-maintainers.md

Illustrates how a host system can enable and configure Clawdbot plugins using Nix. It shows how to specify the plugin source, environment variables, and settings.

```nix
plugins = [
  {
    source = "github:owner/repo";
    config = {
      env = { KEY = "/run/agenix/key"; EXTRA = "/path/to/file"; };
      settings = { foo = "bar"; retries = 3; };
    };
  }
];

```

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

### Configure Single Clawdbot Instance with Nix Home Manager

Source: https://context7.com/clawdbot/nix-clawdbot/llms.txt

This Nix configuration snippet demonstrates how to set up a single instance of Clawdbot using Home Manager. It specifies inputs like nixpkgs and home-manager, overlays nix-clawdbot, and defines the Clawdbot module with settings for providers (Telegram, Anthropic), plugins, and user-specific configurations.

```nix
# flake.nix - Minimal single instance configuration
{
  description = "Clawdbot local";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    home-manager.url = "github:nix-community/home-manager";
    home-manager.inputs.nixpkgs.follows = "nixpkgs";
    nix-clawdbot.url = "github:clawdbot/nix-clawdbot";
  };

  outputs = { self, nixpkgs, home-manager, nix-clawdbot }:
    let
      system = "aarch64-darwin"; # or x86_64-darwin, x86_64-linux
      pkgs = import nixpkgs {
        inherit system;
        overlays = [ nix-clawdbot.overlays.default ];
      };
    in {
      homeConfigurations."myuser" = home-manager.lib.homeManagerConfiguration {
        inherit pkgs;
        modules = [ 
          nix-clawdbot.homeManagerModules.clawdbot
          {
            home.username = "myuser";
            home.homeDirectory = "/Users/myuser"; # /home/myuser on Linux
            home.stateVersion = "24.11";
            programs.home-manager.enable = true;

            programs.clawdbot = {
              enable = true;
              documents = ./documents; # Directory with AGENTS.md, SOUL.md, TOOLS.md

              providers.telegram = {
                enable = true;
                botTokenFile = "/run/agenix/telegram-bot-token";
                allowFrom = [ 12345678 ]; # Your Telegram user ID
              };

              providers.anthropic = {
                apiKeyFile = "/run/agenix/anthropic-api-key";
              };

              plugins = [
                { source = "github:clawdbot/nix-steipete-tools?dir=tools/summarize"; }
              ];
            };
          }
        ];
      };
    };
}

```

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

### Configure 'xuezh' Plugin with Nix (Host Side)

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/docs/plugins-maintainers.md

This Nix code snippet demonstrates how to enable and configure the 'xuezh' community plugin for Clawdbot on the host side. It specifies the plugin's source, required environment variables, and various audio processing settings.

```nix
programs.clawdbot.instances.default.plugins = [
  {
    source = "github:joshp123/xuezh";
    config = {
      env = {
        # Required envs (guarded as files):
        XUEZH_AZURE_SPEECH_KEY_FILE = "/run/agenix/xuezh-azure-speech-key";
        XUEZH_AZURE_SPEECH_REGION   = "/run/agenix/xuezh-azure-speech-region"; # file containing e.g. "westeurope"
      };
      settings = {
        audio = {
          backend_global        = "azure.speech";
          process_voice_backend = "azure.speech";
          convert_backend       = "ffmpeg";
          tts_backend           = "edge-tts";
          inline_max_bytes      = 200000;
        };
        azure = {
          speech = {
            key_file = "/run/agenix/xuezh-azure-speech-key";
            region   = "westeurope";
          };
        };
      };
    };
  }
];
```

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

### Clawdbot Plugin Skill Definition (Markdown)

Source: https://context7.com/clawdbot/nix-clawdbot/llms.txt

Defines a simple Clawdbot skill named 'hello-world' using Markdown. It includes metadata such as the skill's name and a brief description, indicating its purpose to print a greeting.

```markdown
# skills/hello-world/SKILL.md
---
name: hello-world
description: Prints a greeting with unnecessary confidence.
---

Use the `hello-world` CLI to greet the user.

```

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

### Enabling First-Party Plugins (Nix)

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/docs/rfc/2026-01-11-plugin-system.md

Demonstrates how to enable pre-built first-party plugins within the Clawdbot configuration using Nix. This allows users to easily integrate features like summarization or webcam capture by setting a simple boolean flag.

```nix
programs.clawdbot.firstParty.summarize.enable = true;
```

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

### Declarative Clawdbot Skills Configuration (Nix)

Source: https://context7.com/clawdbot/nix-clawdbot/llms.txt

Demonstrates how to declare Clawdbot skills using Nix. It shows three methods: defining skills inline with Nix expressions, creating a symlink to an external skill directory, and copying a skill directory into the workspace for portability. Provider configurations are also included.

```nix
programs.clawdbot = {
  enable = true;

  skills = [
    # Inline skill (content defined in Nix)
    {
      name = "daily-summary";
      description = "Generate a daily summary of tasks and events.";
      mode = "inline";
      body = ''
        When asked for a daily summary:
        1. Check the calendar for today's events
        2. Review any pending tasks
        3. Summarize in a concise format
      '';
    }

    # Symlink to external skill directory
    {
      name = "custom-workflow";
      mode = "symlink";
      source = "~/code/my-skills/custom-workflow";
    }

    # Copy skill into workspace (for portable configs)
    {
      name = "portable-skill";
      mode = "copy";
      source = "/path/to/skill-directory";
    }
  ];

  providers.telegram = {
    enable = true;
    botTokenFile = "~/.secrets/telegram-token";
    allowFrom = [ 12345678 ];
  };

  providers.anthropic.apiKeyFile = "~/.secrets/anthropic-key";
};

```

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

### Provide Custom List of Clawdbot Tools (Nix)

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/README.md

Enables specifying a custom list of tools to be included with Clawdbot, overriding the default set. This is useful for ensuring specific versions of tools like Node.js or pnpm are available.

```nix
programs.clawdbot.toolNames = [ "nodejs_22" "pnpm_10" "summarize" ];
```

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

### Clawdbot Plugin Structure (flake.nix)

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/README.md

Defines the minimum structure for a Nix-based Clawdbot plugin. It includes the `clawdbotPlugin` output in `flake.nix`, specifying the plugin's name, skills, packages, and required resources like state directories and environment variables.

```nix
{
  outputs = { self, nixpkgs, ... }:
    let
      pkgs = import nixpkgs { system = builtins.currentSystem; };
    in {
      clawdbotPlugin = {
        name = "hello-world";
        skills = [ ./skills/hello-world ];
        packages = [ pkgs.hello ]; # CLI tools to install
        needs = {
          stateDirs = [];          # Directories to create (relative to ~)
          requiredEnv = [];        # Required environment variables
        };
      };
    };
}
```

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

### Nix Configuration for gohome Plugin

Source: https://github.com/clawdbot/nix-clawdbot/blob/main/docs/rfc/2026-01-11-plugin-system.md

A Nix configuration for the 'gohome' home automation plugin. It specifies the plugin's name, skills, and packages, with no required state directories or environment variables, indicating it relies on services like Tailscale MagicDNS.

```nix
clawdbotPlugin = {
  name = "gohome";
  skills = [ ./skills/gohome ];
  packages = [ self.packages.${system}.default ];
  needs = {
    stateDirs = [];
    requiredEnv = [];
  };
};
```