Charon


Your AI agents are powerful. But they sit there waiting for you to tell them what to do.

Charon makes them proactive.

---

The Problem

You've got Claude, GPT, or your own agent that can fix bugs, write code, handle tasks. But it only works when you're there to prompt it. Meanwhile:

- Issues pile up in GitHub
- Scheduled reports don't write themselves
- Webhooks from Stripe, Linear, Slack go unprocessed

Your agent could handle these. It just doesn't know they happened.

Vibe PM tools help - they give structure, improve feedback loops, make iteration faster. But they're still reactive. You're still the one kicking things off.

Some tools are adding their own automation (Claude's Chrome extension has CRON, others will follow). But then you're locked in. Your triggers live in one tool, your agent in another, and switching means rewiring everything.

The Solution

Charon sits between the world and your agents. It receives events (webhooks, cron schedules), decides if they need attention, and kicks off your agent with the right context.

``
GitHub Issue → Charon → "Fix login bug #142" → Claude starts working
`

No polling. No manual triage. Events flow in, tasks flow out.

Because Charon is just a trigger layer, it's completely agnostic:

- One place for all your triggers - GitHub, Stripe, cron, whatever. One dashboard, one config.
- Swap agents anytime - Today it's Claude, tomorrow it's GPT or your own thing. Change one line, keep all your triggers.
- Mix and match - Route different events to different agents. Bug reports to Claude, billing issues to a custom script.

Installation

Via npx:
`bash
npx charon-hooks
`

Via Claude Code Plugin:
See charon-plugin

Advanced options: See Installation Guide

---

How It Works

`
Event → Sanitize → Compose → Agent
│
└─► null = ignore, no action
`

1. Event arrives - webhook from GitHub, Stripe, etc. or a cron schedule fires
2. Sanitizer filters it - your script decides: is this worth acting on? Extract what matters, or return null to skip
3. Template composes the task - turn structured data into a prompt your agent understands
4. Egress handler dispatches - spawn Claude CLI, hit an API, or write your own handler

The sanitizer is optional, but still key. It's just TypeScript - no AI, no magic. You decide exactly what triggers action.

`typescript
// sanitizers/github-issue.ts
export default function(payload: any) {
// Only act on new issues with the "agent" label
if (payload.action !== 'opened') return null;
if (!payload.issue.labels.some(l => l.name === 'agent')) return null;

return {
issue_number: payload.issue.number,
title: payload.issue.title,
body: payload.issue.body,
repo: payload.repository.full_name,
};
}
`

---

Quick Start

`bash
npx charon-hooks
`

Open http://localhost:3000 - create your first trigger from the dashboard, or edit ~/.charon/config/triggers.yaml directly.

- Webhook triggers - receive events from GitHub, Stripe, Linear, anything that sends HTTP
- Cron triggers - scheduled tasks on any cron expression
- Sanitizers - filter and transform payloads with TypeScript scripts
- Egress handlers - console for testing, cli for any CLI tool, auto-claude` for Auto-Claude integration
- ngrok tunneling - expose local webhooks to the internet with one config line
- Dashboard - see all triggers, runs, and logs in one place

---

Tech Stack

- Runtime: Bun + TypeScript
- Backend: Hono (fast, lightweight HTTP framework)
- Frontend: React SPA (built with Vite)
- Database: SQLite (zero config)
- Scheduler: node-cron
- UI: shadcn/ui + Tailwind CSS

No external services required. Single process, single database file, runs anywhere.

---

Documentation

| Document | Description |
|----------|-------------|
| Installation Guide | Setup and service installation |
| Trigger Configuration | Configure triggers via UI |
| CLI Egress | CLI egress handler details |
| Tunnel Setup | ngrok tunnel configuration |
| Architecture | System design and data flow |
| API Contracts | API contracts and data formats |

---

License

MIT