# botctl

botctl is a process manager for long-running, autonomous Claude agents. If you want a Claude bot that wakes up every 5 minutes, does a thing, and optionally resumes its previous conversation when you poke it, botctl is the supervisor that keeps it alive. Single Go binary, cross-platform (macOS/Linux/Windows, AMD64/ARM64), TUI + web UI + CLI over the same daemon.

The core abstraction is a `BOT.md` file per bot. YAML frontmatter sets the knobs — `interval_seconds`, `max_turns`, tool list, workspace path, environment — and the markdown body is the system prompt Claude receives on every execution. This is the same pattern Claude Code uses for CLAUDE.md and SKILL.md, scaled up to describe not just a conversation but a scheduled process. A bot directory is self-describing; you can commit it to git and someone else can run the same bot tomorrow.

Under the hood, each bot runs through a harness loop with four explicit states:

- **running** — an API call is in flight, tools are executing
- **sleeping** — waiting out `interval_seconds` before the next tick
- **paused** — session preserved in storage, not scheduled until resumed
- **stopped** — no active process, no session context in memory

Transitions are observable via `botctl logs` or the dashboards, which makes debugging autonomous bots tractable in a way that raw cron + shell scripts isn't. Sessions survive pauses, so a bot that was in the middle of a multi-turn conversation picks up exactly where it left off when you unpause it.

Hot reload is a notable design choice: edit `BOT.md` while the bot is running and the changes apply on the next tick with no restart. This is load-bearing for the intended use case — you're supposed to iterate on the prompt and config while watching the bot's behavior, not do a deploy cycle every time you tweak a word.

Operator messaging is the other distinctive feature. `botctl start my-bot --message "check the error log"` injects a user message into a running bot's next turn. This gives you a cheap out-of-band redirect primitive for autonomous agents — the bot can be doing its scheduled work, and you can steer it mid-run without killing the session. The same primitive is what the Telegram MCP integration in this environment uses to route chat messages into a live Claude session.

## Skills system

Skills are reusable capability modules defined by `SKILL.md` files — same frontmatter-plus-prompt shape as `BOT.md`, but scoped to "a thing a bot can do" rather than "a bot." The lookup order is hierarchical with first-match precedence:

1. Global skills (cross-agent, shared across all users of botctl)
2. botctl-wide (this install)
3. Per-bot (inside the bot directory)

Claude doesn't see the full skills catalog upfront. Instead, a dedicated tool lists available skills (with descriptions) and fetches a skill's body on demand. This is the same "progressive disclosure of capabilities" pattern Claude Code uses for its skill system — load the index into context, fetch the body only when the model decides it needs it. Keeps the context window clean no matter how many skills are installed.

Skills can be installed from GitHub repos, which gives you a package-manager-ish distribution story for bot capabilities.

## Installation

```bash
# macOS/Linux
curl -fsSL https://botctl.dev/install.sh | sh

# Windows
irm https://botctl.dev/install.ps1 | iex
```

## Basic usage

```bash
# Create a bot: directory + BOT.md scaffold
botctl create my-bot -d "Monitor APIs" -i 300 -m 20

# Start it in the background
botctl start my-bot --detach

# Tail its output
botctl logs my-bot -f

# Send a message into a running bot
botctl start my-bot --message "check errors"

# Launch the web dashboard
botctl --web-ui --port 8080
```

## Where this fits

botctl is the "production harness" counterpart to [[build-your-own-openclaw]], which is a tutorial for building the same kind of thing from scratch. If you've walked through OpenClaw and understood the pieces — chat loop, tools, skills, events, scheduling — botctl is roughly what you end up with if someone else already built all 18 steps and polished the result. [[pi-coding-agent]] is a minimal terminal coding agent in the same general space, but scoped to interactive coding rather than scheduled autonomous runs.

For persistent bot memory that outlives a single session, [[hippo-memory]] and [[mempalace]] are both more ambitious approaches than whatever botctl ships natively. A botctl skill could plausibly wrap either of them.

The skills system is structurally similar to Claude Code's — same SKILL.md format, same progressive-disclosure fetch-on-demand pattern. Skills written for one can probably be ported to the other with minor frontmatter changes.

**Repo:** https://github.com/montanaflynn/botctl — 68 stars, MIT, latest v0.3.5 (April 2026). Active development on main and dev branches.