# hermes-speckl — Nix flake for Speckl SME Agent

A pre-configured [Hermes Agent](https://github.com/NousResearch/hermes-agent) instance
purpose-built for the **Speckl** specification language ecosystem.

## What this gives you

One `nixos-rebuild switch` and you have a self-learning AI agent that:

- Understands SpeckDL, the Dark Provenance model, and your compiler architecture
- Compounds expertise across every Speckl task (code review, spec writing, research)
- Runs as a hardened systemd service with declarative config
- Connects via Discord, Telegram, Slack, WhatsApp, or CLI
- Gets faster on recurring tasks the longer it runs

## Usage

Add to your system flake:

```nix
# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    hermes-speckl.url = "github:sscoble/hermes-speckl";
  };

  outputs = { nixpkgs, hermes-speckl, ... }: {
    nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        hermes-speckl.nixosModules.speckl
        ./configuration.nix
      ];
    };
  };
}
```

Then configure:

```nix
# configuration.nix
{ config, ... }: {
  services.hermes-speckl = {
    enable = true;

    # Declarative config (deep-merged into cli-config.yaml)
    settings = {
      model.default = "anthropic/claude-opus-4.6";
      toolsets = [ "all" ];
    };

    # LLM API keys (use sops-nix or agenix)
    environmentFiles = [ config.sops.secrets."hermes-env".path ];
  };
}
```

Apply:

```bash
nixos-rebuild switch --flake .#your-host
systemctl status hermes-speckl
journalctl -u hermes-speckl -f
```

## What's pre-configured

| Setting | Value |
|---|---|
| Model | `anthropic/claude-opus-4.6` (override via `settings.model.default`) |
| Memory | Enabled with skill generation + user modeling |
| Terminal | Local backend, 180s timeout |
| Context compression | On, 85% threshold, Gemini 3 Flash summarizer |
| Agent | 60 max turns, medium reasoning effort |
| Container mode | Enabled (agent can install packages for self-modification) |
| SOUL.md | Speckl domain expert persona (see `documents/SOUL.md`) |

## Container mode

The agent runs inside a persistent Ubuntu container with:

- **Node 22** via NodeSource (for MCP servers, js tooling)
- **Python 3.12 venv** via uv (for pip installs, custom tools)
- **Writable Nix store** (bind-mounted from host)
- **Sudo access** for the agent user (self-modification)

This means the agent can `npm i -g`, `pip install`, and modify its own
environment — essential for skill creation and tool discovery.

## Development

```bash
# Run directly
nix run github:sscoble/hermes-speckl -- setup

# Or from a local clone
git clone https://os.scoble.me/forgejo/sscoble/hermes-speckl
cd hermes-speckl
nix build
./result/bin/hermes setup
```