Driving RunWisp with an AI agent

If you let an AI coding agent edit this project, RunWisp is built to be easy for it to pick up. Everything an agent needs is either in the binary it already has or at a stable URL — no guessing at the config format, no scraping help text.

Here’s the short version you can hand to any agent.

Point your agent at the guide

Run this and paste the output into your project’s AGENTS.md, CLAUDE.md, or README:

runwisp agent-guide >> AGENTS.md

It drops in a compact block that tells the agent RunWisp is here, that runwisp.toml is the source of truth, and which commands emit JSON.

The config file has a schema

runwisp.toml has a JSON Schema (draft 2020-12) describing every table, key, type, and default. Print it from the binary:

runwisp schema

It’s also published at https://docs.runwisp.com/config.schema.json. Any runwisp.toml that RunWisp scaffolds (first run, or runwisp import) starts with a #:schema line, so editors with TOML support — Even Better TOML, taplo — validate and autocomplete it as you type. Add it yourself to an existing file:

#:schema https://docs.runwisp.com/config.schema.json

[tasks.backup]
cron = "0 3 * * *"
run  = "pg_dump mydb > /backups/db.sql"

The edit → validate → run loop

Edit the TOML, then validate. In --json mode the command exits non-zero on failure and every error carries a structured location, so an agent jumps straight to the offending line instead of parsing prose:

runwisp validate --json

{
    "valid": false,
    "errors": [
        {
            "message": "unknown key \"schedule\" at line 4:1",
            "key": "tasks.backup.schedule",
            "line": 4,
            "column": 1
        }
    ]
}

Once it’s valid, run a task and read the outcome — the result is a single JSON document on stdout; live log lines go to stderr, so stdout stays clean:

runwisp exec backup --json

{ "run_id": "01J…", "status": "ended", "exit_code": 0, "duration_ms": 812, "failed": false }

runwisp status --json and runwisp list --json round out the picture: the daemon’s health plus each task’s last run, and the configured task set.

Talking to a running daemon

RunWisp binds a Unix socket at <data-dir>/runwisp.sock (default .runwisp/runwisp.sock). Requests over that socket are trusted as local — no password, no login. That’s exactly what the CLI does, and it’s the path an agent on the same host should use too: runwisp status, runwisp exec, and runwisp reload all connect over it automatically.

Everything the API exposes is read state or trigger/stop a run. Nothing over HTTP or the socket ever edits a task definition — that only happens by editing runwisp.toml and reloading. So an agent’s job is always: change the file, runwisp validate --json, runwisp reload.

Going deeper

• Agent reference — a dense, token-optimized dump of the full runwisp.toml schema, CLI, and REST surface. Start here if you’re an agent.
• OpenAPI spec — the REST API in full, or runwisp openapi offline.
• CLI reference — every subcommand and flag, for humans.