Local-first orchestrator for headless coding agents across your GitHub repos. Watches for assigned issues, runs a dev pipeline in an isolated git worktree, opens a PR, and asks you on Telegram when it gets stuck.
Headless coding agents are great interactively. Running them across half a dozen repos without staring at a terminal is a different problem: who schedules the runs, who watches for new work, who hands you the "I'm blocked, what do you want?" question, who tracks the PR until it merges.
ctrlrelay is a small daemon that does all of that on your laptop. It
is local-first on purpose: no server, no queue, no multi-tenant anything.
Your agent credentials, your GitHub credentials, your repos, your
machine.
Today ctrlrelay ships with a Claude Code (claude -p) backend. The
orchestrator layer — worktrees, state DB, scheduler, Telegram bridge —
is agent-agnostic, and plug-in backends for other headless coding agents
are on the roadmap (see Roadmap).
- Issue poller. Detects issues across every configured repo
(either assigned to you, or carrying a configurable opt-in label like
ctrlrelay:auto), spawns a dev session in a dedicated git worktree, and opens a PR. Label triggers let a teammate without rights on your account flag an issue as safe for the bot to pick up — seeinclude_labels. - Telegram bridge. When a session hits a blocking question, the bridge relays it to you as a DM and resumes the session once you reply.
- PR watcher. Tracks the opened PR to merge and closes the loop with a Telegram notification.
- In-process scheduler (APScheduler). Runs periodic jobs inside
the poller daemon. Ships with a
secopsjob that reviews Dependabot alerts and PRs daily at 6am; cron expressions follow standard Vixie 5-field semantics (Sun=0, DOM-OR-DOW). - Checkpoint protocol. The agent writes a structured state file at the end of every session so the orchestrator knows whether it succeeded, failed, or is blocked on input. Agent backends implement this protocol to integrate.
- Cross-platform supervision. launchd (macOS) and systemd (Linux)
examples in
docs/operations.md. One codebase, identical behavior.
┌───────────────┐
│ GitHub API │
└───────┬───────┘
│ (poll: issues assigned to me)
┌───────▼───────┐ ┌──────────────┐
│ poller daemon │◄────────┤ APScheduler│
│ (launchd / │ │ (secops cron)│
│ systemd) │ └──────────────┘
└───┬───────┬───┘
new issue │ │ blocked session
│ │
┌──────────▼──┐ ┌─▼───────────────────┐
│ dev pipeline│ │ Telegram bridge │
│ in worktree │ │ (socket ↔ bot API) │
│ agent CLI │ └──────────┬──────────┘
└──────┬──────┘ │
│ PR opened │ DM you
▼ ▼
┌────────────┐ ┌─────────┐
│ PR watcher │ │ You │
└────────────┘ └─────────┘
Under the hood it's Python + asyncio + sqlite for state. The agent
is invoked as a subprocess (today: claude -p), and GitHub is accessed
via the gh CLI. No web server, no queue, no database dependency — just
a launchd/systemd-supervised daemon.
- Python 3.12+
- git 2.20+
- The
ghCLI, authenticated (gh auth login) — used for all GitHub API calls. - A headless coding agent backend. Today that means the
claudeCLI, authenticated (claude auth login). Future backends will document their own setup. - (Optional, for the
secopspipeline) thecodexCLI, authenticated. The secops pipeline invokescodex reviewas an independent reviewer for the agent's output; you can disable it by settingcode_review.method: "none"in your config if you prefer to skip the review step. - (Optional) a Telegram bot token if you want the bridge — see Telegram bridge docs.
From PyPI (once published):
pip install ctrlrelay
# or: uv pip install ctrlrelayFrom source (current path while in alpha):
git clone https://github.com/AInvirion/ctrlrelay.git
cd ctrlrelay
uv pip install -e . # or: pip install -e .# Copy and edit the example config:
cp config/orchestrator.yaml.example config/orchestrator.yaml
# Validate it:
ctrlrelay config validate
# Run the dev pipeline against an issue you're assigned:
ctrlrelay run dev --issue 42 --repo your-org/your-repo
# Or start the poller to auto-process newly assigned issues + run the
# scheduled secops sweep daily at 6am:
ctrlrelay poller start # daemonizes; returns the terminal
ctrlrelay poller status # verify it's runningRun as a supervised daemon (launchd on macOS / systemd on Linux) — see Operations.
- Getting started
- Configuration
- Telegram bridge
- Feedback loop
- CLI reference
- Operations (launchd / systemd / scheduled jobs)
- Architecture
- Development
- Multi-agent backend support. The agent dispatcher is the seam we
intend to widen so
ctrlrelaycan drive alternative headless coding agents (e.g. OpenAI Codex CLI, OpenCode, Hermes) alongside Claude Code. Each backend will implement the same checkpoint protocol and be selectable per repo via config. - Additional scheduled jobs. The in-process scheduler already has
secops; follow-ups include a weekly activity summary and a stale- session reaper. - Dashboard mode. An optional, opt-in heartbeat push to a hosted dashboard for operators running the daemon across many machines.
We welcome contributions from the community! Please read our Contributing Guidelines before submitting a pull request, and abide by our Code of Conduct.
First-time contributors will be prompted by the CLA Assistant bot to sign the Contributor Assignment Agreement in-PR — it's a one-time, one-comment step.
If you discover a security vulnerability, please follow our Security Policy. Please do not file public GitHub issues for security reports — open a private advisory instead.
This project is licensed under the Apache License 2.0 — see the LICENSE file for details.
Copyright (c) 2026 AInvirion LLC. All Rights Reserved.