Labro — Autonomous Agent Harness

Labro runs AI coding agents on a schedule so you don't have to watch them.

See Why Labro for the design rationale: why supervision is the bottleneck, why scheduled complements event-driven, and why the harness stays simple. Live dashboard →

• Runs on a schedule — cron-driven via GitHub Actions or a dedicated server; no one needs to be at the keyboard
• Picks the right task from your GitHub Issues backlog — you define label and author rules that determine priority
• Safeguards — daily budget cap, model fallback on failure, and configurable tool-use restrictions
• Full audit trail — every run records outcome, cost, tokens, and actions to a local SQLite database

At a glance

A Labro project is configured in a single TOML file. Here's a minimal example that monitors issues labelled ai-dev, runs the agent hourly, and posts a comment or opens a PR:

[defaults]
model = "claude-code"            # which agent + model to use

[personas.senior-dev]
prompt = """
Act as a senior developer. If reasonably possible, raise a PR for this ticket.
If a PR is not reasonably possible (e.g. unclear or contradictory requirements),
post a comment asking questions. In your comment, namecheck an appropriate
person or people from the issue history.
"""

[[projects]]
name    = "my-project"
repo    = "my-org/my-repo"
cron    = "0 * * * *"            # run hourly

[[projects.task_sources]]
type = "gh-label"                # pick from GitHub issues with a matching label

[[projects.task_sources.label_rules]]
label             = "ai-dev"          # pick one open issue with this label
done_label        = "ai-dev-done"     # apply this label on success
persona           = "senior-dev"      # which persona prompt to use
permitted_actions = ["comment_on_issue", "open_pr"]  # what the agent may do

With more config, Labro can also comment on Dependabot PRs cross-referenced against open security alerts, raise a tracking issue for alerts Dependabot hasn't yet opened a PR for, and surface proactive improvement suggestions — all from the same TOML file.

For a full reference with personas, shared rules, dashboards, and multi-project setups, see labro.example.toml or a live production config.

Supported agents

Labro drives three agent CLIs. Each must be on PATH (the Docker image bundles them) and authenticated — see QUICKSTART.md for the credential env vars.

CLI id	Binary	Agent
claude-code	claude	Claude Code
codex	codex	OpenAI Codex CLI
opencode	opencode	OpenCode — any model on models.dev

Every model = field takes a model slug in the form <cli>[:<provider>/<model>][@<effort>]:

model = "claude-code"                                  # CLI default model
model = "claude-code:anthropic/claude-opus-4-7@high"   # pinned model + reasoning effort
model = "codex:openai/gpt-5-codex"
model = "opencode:openrouter/openai/gpt-oss-120b:free" # provider slugs may contain / and :

A list is a fallback chain — Labro tries each slug in order until one succeeds:

model = ["claude-code:anthropic/claude-opus-4-7", "codex:openai/gpt-5-codex"]

Slugs resolve in the order: label rule → task source → project → [defaults]. See the Model Selection Guide for choosing between them.

Getting Started

• Docker (recommended for production): QUICKSTART.md — clone, build, configure, and run.
• Local Python (recommended for development): QUICKSTART.md — same file, second section.
• Deployment: docs/DEPLOYMENT.md — GitHub Actions cron, dedicated server with crond, config-repo workflow.

---

Metrics Dashboard

Live example: labro.rossarnold.uk

A read-only static SPA (React + Vite + sql.js) served from an S3-compatible blob store (e.g. Cloudflare R2). It loads a published snapshot of labro.db client-side and renders a runs list, per-project stats, and charts — no runtime link to the harness.

⚠️ Data sensitivity: the published snapshot includes run metadata — issue titles, PR descriptions, and agent output — which may contain repo content. The dashboard ships no built-in access control. If your repo contents are sensitive, do not use this feature. See ADR-0007.

Full setup guide: Metrics Dashboard

---

Documentation

• QUICKSTART.md — Docker and local Python setup, step by step.
• Why Labro — design rationale: why cron not webhooks, the autonomy model, and the project philosophy.
• Deployment Guide — GitHub token setup, Docker deployment modes (GitHub Actions and a dedicated server), graceful restart procedure, and config-repo workflow.
• Operations Reference — live run loop internals, environment variables, label transitions, turn-limit handling, daily budget cap, signal collection, and CLI reference.
• Model Selection Guide — advice on choosing agents and models per task type, with cost-shaping strategies and caveats.
• Architecture — system context, component design, runtime flow, and architectural decisions.
• Metrics Dashboard — S3-compatible blob store setup, [dashboard] config, snapshot publishing, and SPA deployment.
• Product Requirements Document — problem statement, design principles, functional requirements, and success metrics.
• Roadmap — delivery milestones and per-file completion tracking.
• Architectural Decision Records — record of significant design decisions.
• Contributing — development setup, testing, code quality gates, and security reporting.
• Domain Glossary — canonical definitions for terms used across all Labro documents and code.

---

Contributing

See CONTRIBUTING.md for development setup, testing, code quality gates, and security reporting.

License

Apache-2.0 — see LICENSE.