Cyrus + Linear as AI Agent Orchestration Layer¶
- Date: 2026-03-12
- Status: Accepted
- Tags:
toolingworkflowai-agents
Context¶
Wanted an autonomous AI coding agent that could pick up tasks without manual prompting inside Claude Code. The goal: assign an issue somewhere, Claude does the work, creates a PR, done. Needed a task routing layer and a persistent tunnel for webhook delivery.
Decision¶
Use Linear as the task management + orchestration layer, Cyrus (cyrus-ai npm) as the self-hosted Claude Code agent, and a Cloudflare Tunnel for permanent webhook delivery to cyrus.phazeight.dev.
- Linear issue assigned to Cyrus → agent session webhook fires → Cyrus spawns Claude Code → PR created
- GitHub repos are linked to Linear teams for bidirectional issue sync
- Cyrus managed via
~/.cyrus/config.json(one entry per repo)
Alternatives Considered¶
| Option | Why Rejected |
|---|---|
| ngrok | Requires account, ephemeral URL — Linear webhook URL would break on every restart |
| GitHub Actions only | No conversational agent loop, no Linear integration |
| Hosted agent services | Sends code to third-party infra; wanted self-hosted |
Consequences¶
Positive:
- Permanent webhook URL via Cloudflare Tunnel — no reconfiguration after restarts
- Linear serves as a clean task queue visible across projects
- Claude Code does the actual coding work in isolated git worktrees
Negative / Trade-offs:
- Cyrus + cloudflared must both be running for end-to-end flow to work (not persistent services yet)
- Linear free tier: one default GitHub repo per team — limits multi-repo routing
- Cyrus must be started from a clean terminal (not inside Claude Code session) — see gotchas
Ongoing obligations:
- Keep
~/.cyrus/config.jsonupdated when adding new repos - Register Linear webhook manually if Cyrus doesn't auto-register on startup
- Monitor Anthropic API usage — each Cyrus session consumes tokens (separate from Claude Pro)
ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.