leo

README

Leo

A process supervisor and task scheduler for Claude Code

Install · Quick Start · Features · Documentation

---

Leo manages persistent Claude Code sessions, schedules autonomous tasks, and lets you spawn on-demand coding agents. Telegram gives you mobile access. A built-in web dashboard lets you manage everything from a browser.

Install

curl -fsSL https://raw.githubusercontent.com/blackpaw-studio/leo/refs/heads/main/install.sh | sh

Or with Go: go install github.com/blackpaw-studio/leo@latest

Prerequisites: Claude Code CLI (authenticated), tmux, a Telegram bot token

Quick Start

leo setup          # interactive wizard — Telegram, profile, workspace
leo service start  # start supervised processes

The wizard walks you through connecting Telegram, creating a user profile, and configuring your first process. Once started, message your bot on Telegram to chat with your assistant.

Run leo service start --daemon to install as a system service that persists across reboots.

Features

Processes

Long-running Claude sessions supervised with auto-restart and exponential backoff. Each process gets its own workspace, model, channels, and permissions. Connect Telegram for mobile access, enable remote control for claude.ai/code.

processes:
  assistant:
    channels: [plugin:telegram@claude-plugins-official]
    remote_control: true
    enabled: true

Agent Templates

Define reusable blueprints for spawning ephemeral coding agents. Dispatch them from Telegram (/agent coding owner/repo) or the web UI. Agents clone the repo, run in their own tmux session, and show up in claude.ai with a named session.

templates:
  coding:
    model: sonnet
    remote_control: true
    permission_mode: bypassPermissions
    workspace: ~/agents

Remote CLI

The leo binary is dual-purpose. On a server it supervises processes and runs tasks. On a laptop, with a client.hosts section in leo.yaml, it becomes a thin remote client that manages and attaches to agents on a leo host over SSH.

client:
  default_host: prod
  hosts:
    prod:
      ssh: evan@leo.example.com

leo agent spawn coding --repo blackpaw-studio/leo --name demo
leo agent attach demo     # full tmux attach to the remote Claude TUI
leo agent list

See the Remote CLI guide.

Scheduled Tasks

Cron-driven tasks that invoke Claude in non-interactive mode. Write a prompt file, set a schedule, and Leo handles the rest. Tasks can send Telegram messages, run silently, retry on failure, and route to forum topics.

tasks:
  daily-briefing:
    schedule: "0 7 * * *"
    timezone: America/New_York
    prompt_file: prompts/daily-briefing.md
    model: opus
    enabled: true

Web Dashboard

Monitor processes, manage tasks, edit config, spawn agents, and preview cron schedules from a browser on your LAN.

web:
  enabled: true
  port: 8370

Telegram Commands

Command	Description
/agent [template] [repo]	Spawn a coding agent
/agents	List running agents with stop buttons
/tasks	List tasks with run/toggle buttons
/stop	Interrupt the current process
/clear	Clear conversation context
/compact	Compact conversation context

The Telegram plugin also gives Claude tools for replies, reactions, message editing, scheduled messages, persistent memory, and more. See the Telegram guide.

CLI

Command	Description
leo setup	Interactive setup wizard
leo service start / stop / restart / logs	Manage the supervisor
leo process list / add / remove / enable / disable	Manage supervised processes
leo task list / add / remove / enable / disable	Manage scheduled tasks
leo task history / logs	Inspect task runs and log output
leo template list / show / remove	Inspect and remove agent templates
leo agent list / spawn / attach / stop / logs	Spawn and control ephemeral agents (local or over SSH)
leo run <task>	Run a task once
leo status	Overall status (service, processes, tasks, templates, web UI)
leo validate	Check config, prerequisites, and workspace health
leo config show	Display effective config (supports --raw, --json)
leo config edit	Edit config interactively
leo update	Self-update binary

See the CLI reference for full details.

Documentation

• Getting Started — installation, prerequisites, first run
• Configuration — full config reference and workspace structure
• CLI Reference — every command and flag
• Guides — Telegram setup, writing tasks, agents, scheduling, background mode
• Development — contributing, architecture, releasing

Development

make build      # Build to bin/leo
make test       # Run tests with race detector
make lint       # go vet + staticcheck

License

MIT