https://github.com/choonkeat/hotroute
hotroute: laying tracks as the train arrives
https://github.com/choonkeat/hotroute
channel claude code
Last synced: 12 days ago
JSON representation
hotroute: laying tracks as the train arrives
- Host: GitHub
- URL: https://github.com/choonkeat/hotroute
- Owner: choonkeat
- Created: 2026-03-29T02:55:03.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-29T08:49:48.000Z (3 months ago)
- Last Synced: 2026-04-24T04:38:03.057Z (about 2 months ago)
- Topics: channel, claude, code
- Language: Erlang
- Homepage:
- Size: 1.31 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# hotroute
A self-building HTTP server powered by Claude Code. When a browser hits an unknown route, Claude is notified, asks you what it should do, writes a Gleam handler module, hot-loads it into the running BEAM VM, and serves the response — all without restarting.
> *Someone just hit GET / on your hotroute server. What should the homepage do?*
## How it works
```
Browser: GET /articles/42
|
v
hotroute: no handler for /articles/:id
|
v
Claude (in your terminal): "Unknown route: GET /articles/42. What should this do?"
|
v
You: "Show the article by ID, render as HTML"
|
v
Claude: writes src/handlers/articles_show.gleam
-> compiles and hot-loads into the running VM
-> registers GET /articles/:id
-> responds to the waiting browser request
|
v
Browser: sees the article page
Next request to GET /articles/99 is served directly — no Claude involved.
```
> *Homepage is live at GET / with links to /faq and /contact. The pending browser request has been served. Those two pages don't exist yet — I'll build them when someone hits them.*
## Getting started
### Build (once)
```bash
make build
```
Behind an enterprise proxy with SSL inspection:
```bash
cp /path/to/Corporate_CA.pem .
make build CUSTOM_CA_CERT=Corporate_CA.pem
```
### Run
```bash
make run
```
To use a different port:
```bash
make run PORT=8080
```
### First launch
1. Accept the MCP server and permissions prompts
2. If you see "Channels require claude.ai authentication", type `/login` and follow the auth URL
3. After login, exit (Ctrl+C) and re-run `make run` — the auth persists in your mounted `~/.claude/`
These prompts are one-time; subsequent launches skip them.
### Usage
Open `http://localhost:3000` in a browser. Any URL that doesn't have a handler shows a loading page while Claude asks you in the terminal what to build.
### Reset
To clear all routes and generated handlers:
```bash
make reset-routes
```
## Configuration
| Environment variable | Default | Description |
|---------------------|---------|-------------|
| `PORT` | `3000` | HTTP server port |
| `HOTROUTE_ROOT` | `.` | Project root directory |
| `HOTROUTE_INSTRUCTIONS` | — | Path to custom MCP instructions file |
### Docker volumes
| Mount point | Purpose |
|-------------|---------|
| `/home/hotroute/.claude` | Claude Code auth (mount your `~/.claude`) |
| `/home/hotroute/app/data` | Route persistence (`routes.json`) |
### Custom instructions
Edit `instructions.md` to change how Claude behaves when an unknown route is hit. Or point to a different file:
```bash
make run HOTROUTE_INSTRUCTIONS=./my-instructions.md
```
Use this to integrate with other communication channels (Telegram, Slack, etc.) or to change Claude's behavior (e.g. auto-build without asking).
## Architecture
hotroute is a single BEAM application running two concurrent services:
1. **MCP channel server** (stdin/stdout) — speaks JSON-RPC with Claude Code. Pure Gleam, no Node.js.
2. **HTTP server** (Mist/Cowboy) — serves web requests on the configured port.
Routes are stored in ETS (in-memory). On shutdown, routes are saved to `data/routes.json`. On boot, persisted routes are loaded and handler modules are recompiled.
## Stack
- [Gleam](https://gleam.run) on the BEAM
- [Mist](https://github.com/lpil/mist) HTTP server
- [MCP](https://modelcontextprotocol.io) channel protocol (pure Gleam implementation)
- Erlang/OTP 27 (ETS, hot code loading, process supervision)