# teabot

teabot is a Go daemon (shipped as a systemd **user** service) that watches Gitea
repositories and dispatches **one-shot Claude Code sessions in Docker containers**
to work issues and review pull requests.

On each poll it looks for new issues, new pull requests, and new comments across
the repos it watches. For each event it launches a throwaway container that
clones the repo fresh and runs `claude --print` with a task-specific prompt:

- **New issue** → an *implementer* personality reviews it and, if it warrants a
  change, opens a PR that closes the issue (following the house PR conventions).
- **New pull request** → a *reviewer* personality critiques the diff and posts an
  approving or change-requesting review.
- **New comment** on a thread teabot already engaged with → a follow-up session
  responds or makes the requested change.

Each personality is a distinct Gitea bot account backed by its own `tea` config
file, so an implementer bot can open PRs that a separate reviewer bot critiques.
teabot never reacts to events authored by its own personalities (loop
prevention) and persists processed state so restarts don't re-trigger work.

**Security:** sessions run `claude --dangerously-skip-permissions` with a prompt
built from event text, so teabot only acts on events from authors on a
configured `allowed_authors` allowlist (fail-closed — an empty list dispatches
nothing). See [Author allowlist](docs/configuration.md#author-allowlist-security).

## Quick start

```bash
# 1. Create the config and edit it.
teabot config init
$EDITOR ~/.config/teabot/config.yaml

# 2. Create a tea login file per personality (a normal tea config.yml).
tea logins add --name teabot-impl   --url https://git.unkin.net --token <impl-token>
tea logins add --name teabot-review --url https://git.unkin.net --token <review-token>
# point each personality's tea_config: at the resulting config.yml

# 3. Validate, then run a single cycle to test.
teabot config show
teabot run --once

# 4. Enable the daemon.
systemctl --user enable --now teabot
```

## Documentation

- [Architecture](docs/architecture.md) — how polling, dispatch, and the Docker
  execution model fit together.
- [Configuration](docs/configuration.md) — every config key, personalities, and
  Claude/tea credential handling.
- [`teabot run`](docs/run.md) — running the daemon, `--once`, logging, systemd.
- [`teabot config`](docs/config.md) — the `init` and `show` subcommands.

## Build

```bash
make build      # -> dist/teabot (static, CGO disabled)
make test       # go test -race ./...
make rpm        # build + package an RPM (needs nfpm)
```

Requires Go 1.25+. A `v*` tag triggers the release pipeline: a Gitea release
with cross-platform binaries plus an RPM published to the artifactapi
`rpm-internal` repo.

## License

MIT