Autonomous AI coding agent triggered by Linear tickets. Assign a ticket, get a PR — with a full dev environment, live preview URLs, and real-time progress streamed back to Linear.
Getting started? Fork this repo, open it in Claude Code, and run
/setup. It walks you through everything.
hermes-demo.mov
Hermes turns Linear tickets into pull requests. You assign a ticket to the agent, and it:
- Spins up a full dev environment — EC2 with Docker, PostgreSQL, Redis, OpenSearch, your entire app stack
- Reads the codebase, plans an approach, writes code, runs tests
- Streams progress back to the Linear ticket as activity updates
- Creates a preview URL — a live, accessible deployment of the changes
- Opens a PR when done, terminates the instance, and notifies Slack
You can send messages mid-flight via Linear comments — Hermes reads and responds in real-time.
This is not a copilot. Hermes is an autonomous agent that works independently on tickets. You review the PR, not the keystrokes.
Built and used in production to handle engineering tickets end-to-end.
hermes-prompts.mov
hermes-pr-show.mov
| Feature | Description |
|---|---|
| Automated workflows | Classifies tickets and applies the right skill — full-development (plan → TDD → PR), debugging (investigate → fix → PR), or simple-question (research → answer) |
| Full dev environment | Each session gets its own EC2 with Docker, databases, and the complete app stack |
| Bi-directional Linear | Progress streamed to tickets, user comments forwarded to the agent mid-flight |
| Preview URLs | Named Cloudflare tunnels with stable subdomains for live preview environments |
| Session resume | Follow-up comment on a completed ticket resumes where it left off |
| Pre-baked AMIs | Agent EC2 instances boot in ~2 minutes with everything pre-installed |
| Outbound firewall | iptables allowlist restricts agent internet access to approved domains only |
| Network isolation | Agents only accept inbound traffic from the orchestrator security group |
| Queued sessions | Configurable concurrency cap with automatic queue draining |
| Crash recovery | On restart, in-flight sessions are reconciled and the queue is drained |
| MCP integrations | Plug in any MCP servers (e.g. error tracking, analytics) for richer agent context |
| Slack notifications | Threaded session updates posted to a Slack channel |
| GitHub App auth | Short-lived installation tokens with automatic refresh |
| Multi-org Linear | Per-organization OAuth tokens with automatic refresh |
You assign a Linear ticket
│
▼
┌──────────────────┐
│ Orchestrator │ Receives webhook, launches EC2 from pre-baked AMI
│ (t4g.nano) │
└────────┬─────────┘
│
┌────────▼─────────┐
│ Agent EC2 │ Boots in ~2min, starts Docker stack + agent-service
│ (m6i.xlarge) │
└────────┬─────────┘
│
┌────┼────┐
▼ ▼ ▼
Linear PR Slack
updates .git notification
The full flow:
- Linear ticket assigned to agent → webhook fires
- Orchestrator receives webhook via Cloudflare Tunnel
- Orchestrator launches agent EC2 from pre-baked AMI
- Agent EC2 boots: pulls code, starts Docker stack, starts agent-service
- Claude Code reads the codebase, plans, codes, tests
- Progress streamed to Linear as activity updates
- Preview URL created via Cloudflare named tunnel
- PR opened, EC2 terminated, Slack notified
Linear webhook ──HTTPS──▶ Cloudflare Tunnel ──▶ Orchestrator (t4g.nano)
│
VPC private IP
│
┌─────────────▼─────────────┐
│ Agent EC2 (m6i.xlarge) │
│ ┌──────────────────────┐ │
│ │ agent-service :3000 │ │
│ │ Claude Code CLI │ │
│ │ Docker (app stack) │ │
│ └──────────────────────┘ │
└───────────────────────────┘
hermes-swe/
├── orchestrator/ # Webhook receiver, EC2 lifecycle, session queue
├── agent-service/ # Runs on agent EC2 — Claude Code session management
├── skills/ # Workflow skills copied to each agent at boot
│ ├── full-development/ # Features, enhancements, refactors
│ ├── debugging/ # Bug reports, error investigations
│ └── simple-question/ # Questions, clarifications
├── ami/ # EC2 provisioning, AMI baking, firewall
│ ├── setup.sh # Base AMI: Docker, Node, pnpm, Claude Code
│ ├── prepare-ami.sh # Pre-bake: clone repos, build, pull images
│ ├── init-instance.sh # Boot-time: pull latest, start services
│ ├── firewall.sh # Outbound domain allowlist
│ └── app/ # Example app-specific scripts
├── scripts/ # AWS setup, deployment, AMI baking
├── repos.json # Maps org/repo → AMI, instance type, secrets
└── package.json # pnpm workspace
# 1. Clone and install
git clone https://github.com/Deepank308/hermes-swe.git
cd hermes-swe && pnpm install
# 2. Configure
cp .env.example .env.local
# Fill in: CLOUDFLARE_HOSTNAME, LINEAR_*, CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY, GITHUB_TOKEN
# Edit repos.json to add your repositories (see repos.example.json)
# 3. Run setup (creates AWS resources, launches EC2, sets up tunnel)
bash scripts/setup.sh
# You'll click one URL to authorize Cloudflare — that's the only interactive step
# 4. Connect Linear — visit the URL printed at the end of setup
# 5. Assign a ticket — Hermes takes it from hereHave Claude Code installed? Run
/setupin this repo for an interactive guided setup.
See SETUP.md for the full setup guide.
| Service | Role |
|---|---|
| Linear | Ticket management, webhook triggers, bi-directional activity streaming |
| Claude Code | AI coding agent (runs on agent EC2) |
| GitHub | Code hosting, PR creation, App-based authentication |
| AWS EC2 | Agent compute (m6i.xlarge per session) |
| AWS S3 | Session state persistence |
| AWS Secrets Manager | Centralized secrets |
| Cloudflare Tunnel | HTTPS ingress + preview URLs |
| Slack | Session notifications (optional) |
- Orchestrator: TypeScript + Fastify, runs on t4g.nano (~$3/mo)
- Agent service: TypeScript, manages Claude Code sessions via cyrus
- Agent compute: EC2 m6i.xlarge (16GB RAM) with Docker, full app stack
- Networking: Cloudflare Tunnel (webhooks) + named tunnels (preview URLs)
- State: S3 (sessions) + Secrets Manager (credentials)
Hermes uses Cyrus for Claude Code session management — starting, stopping, resuming, and streaming Claude CLI sessions programmatically. Cyrus handles the low-level session lifecycle so Hermes can focus on orchestration, workflow routing, and infrastructure.
pnpm install # Install all workspace dependencies
pnpm build # Build all packages
pnpm -r lint # Lint all packagesSet DRY_RUN=true in orchestrator/.env to run locally without AWS resources.
| Guide | Description |
|---|---|
| Setup Guide | End-to-end setup from scratch |
| Self-Hosting Guide | Detailed deployment walkthrough |
| Repository Configuration | Adding repos, AMI strategy, previews |
| Linear Integration | OAuth app setup, webhooks, activity reporting |
| GitHub Authentication | GitHub App or Personal Access Token |
| Cloudflare Setup | Orchestrator tunnel + preview tunnels |
| Slack Notifications | Bot setup for threaded notifications |
Hermes uses Claude Code CLI to run autonomous coding sessions. Per Anthropic's Agent SDK guidelines, third-party products should authenticate with an Anthropic API key — configure ANTHROPIC_API_KEY in your .env.local.
Hermes is an independent open-source project, not affiliated with or endorsed by Anthropic. Please review Anthropic's usage policy and commercial terms to ensure your usage is compliant.
MIT