# claude-hook

Listens for Gitea webhooks and runs Claude Code against an issue or pull
request whenever the configured owner mentions `@claude` in a comment or
issue body. On success it commits any changes Claude made, pushes a branch,
opens (or reuses) a pull request, and replies on the issue with a summary.
Failures are reported the same way, as a comment, so nothing is silent.

## Layout

```
src/
  config.js    env parsing + validation, fails fast on startup
  logger.js    structured JSON logging to stdout/stderr
  exec.js      process spawning with timeout + output capture
  gitea.js     Gitea API client (issues, pulls, comments)
  git.js       git clone/checkout/commit/push for one job's working dir
  claude.js    invokes the `claude` CLI non-interactively
  prompt.js    builds the prompt sent to Claude
  events.js    pure webhook-payload -> trigger classification logic
  jobQueue.js  prevents overlapping runs for the same issue/PR
  job.js       orchestrates one end-to-end run
  server.js    HTTP server: signature check, parse, classify, dispatch
  app.js       wires the above together
  index.js     process entrypoint, signal handling
test/          node:test unit + integration tests, no external services
```

Every module that touches the outside world (HTTP, git, subprocess) is
constructed with its dependencies passed in, so `test/` exercises the real
logic against fakes rather than a real Gitea instance or a real `claude`
binary.

## Running the tests

```
npm test
```

No dependencies to install — everything uses Node's built-in `node:test`,
`fetch` and `child_process`. Requires Node 20+.

## Configuration

All via environment variables, validated on startup (a bad or missing
value exits immediately with a clear error rather than failing later):

| Variable | Required | Default | Notes |
|---|---|---|---|
| `GITEA_URL` | yes | — | e.g. `http://gitea:3000` internally, or `https://git.example.com` |
| `GITEA_TOKEN` | yes | — | access token for the bot user, needs write access to target repos |
| `CLAUDE_CODE_OAUTH_TOKEN` | yes | — | from `claude setup-token` |
| `OWNER_LOGIN` | yes | — | only comments/issues from this Gitea username trigger a run |
| `WEBHOOK_SECRET` | no | unset | if set, requires a valid `X-Gitea-Signature` header |
| `TRIGGER_PHRASE` | no | `@claude` | |
| `CLAUDE_MODEL` | no | `sonnet` | |
| `CLAUDE_MAX_TURNS` | no | `25` | |
| `JOB_TIMEOUT_MS` | no | `1200000` (20 min) | |
| `PORT` | no | `3000` | |
| `LOG_LEVEL` | no | `info` | `debug` \| `info` \| `warn` \| `error` |

See `.env.example`.

## Deploying (Coolify, Docker Compose build pack)

1. Push this project to a Gitea repo (e.g. `selimaj-dev/claude-hook`).
2. In Coolify: **+ New Resource -> Public Repository**, build pack
   **Docker Compose**, pointing at that repo.
3. Edit `docker-compose.yml`'s `networks.gitea-network.name` to the actual
   Docker network your Gitea container is on
   (`docker inspect <gitea-container> --format '{{json .NetworkSettings.Networks}}'`).
4. Set the environment variables listed above in Coolify's UI. Leave
   **Domains** empty — this service has no public route by design.
5. Deploy, then confirm from Gitea's container:
   ```
   docker exec <gitea-container> wget -qO- http://claude-hook:3000/healthz
   ```
6. In Gitea: Site Administration -> Integrations -> Webhooks -> **System
   Webhooks** -> Add, URL `http://claude-hook:3000/`, trigger on **Issue
   Comment** (and **Issues**, if you want `@claude` in a fresh issue body
   to work too). To also support pull requests, enable **Pull Request**
   (for `@claude` in a fresh PR description), **Pull Request Comment**
   (general PR comments — routed the same as issue comments), **Pull
   Request Review**, and **Pull Request Review Comment** (inline diff
   comments). If you set `WEBHOOK_SECRET`, put the same value here.
7. Add `GITEA__webhook__ALLOWED_HOST_LIST=private` to Gitea's own
   environment and restart it — Gitea refuses to call private addresses
   otherwise.

## Logs

Every log line is one JSON object on stdout (or stderr for `warn`/`error`),
so `docker logs claude-hook` / Coolify's log viewer is directly greppable
or pipeable into `jq`. Key events to look for:

- `webhook received` — Gitea reached the service at all
- `ignored` with a `reason` field — why an event didn't trigger a run
- `trigger matched` / `job started` / `job finished` — a run went through
- `job errored` — something failed; the same message was also posted as a
  Gitea comment on the issue

## Known limitations

- Runs execute inside this one long-lived container, not a fresh sandbox
  per job — don't point `OWNER_LOGIN` checks loosely, and don't run this
  against repos where you don't trust every collaborator who can comment.
- Uses your Claude subscription (via `claude setup-token`), so runs share
  the same usage limits as interactive Claude Code / claude.ai use.