forgebot/README.md

forgebot

K8s operator + API for AI agent dispatch from git forges.

Architecture

• API server (cmd/api) — REST API backed by PostgreSQL. Receives webhooks from Gitea, manages task lifecycle, and orchestrates the review workflow.
• Operator (cmd/operator) — Kubernetes controller that watches for pending tasks, creates Jobs via AgentPool/AgentTask CRDs, and reports completion back to the API.
• TUI (cmd/tui) — Terminal kanban board for viewing and managing tasks.

Task Lifecycle

Tasks follow a kanban workflow with automated review:

                    +-----------+
                    |   Todo    |
                    +-----+-----+
                          |
                   agent picks up
                          |
                    +-----v-------+
                    | In Progress |
                    +-----+-------+
                          |
                   agent completes
                          |
              +-----------+-----------+
              |                       |
        auto-create               error?
        review task            back to Todo
              |
        +-----v------+
        |  In Review  |<-----+
        +-----+------+      |
              |              |
       human decision    reviewer
              |          suggests
         +----+----+    changes
         |         |        |
    +----v--+  +---v----+   |
    | Done  |  | Wontdo |   |
    +-------+  +--------+   |
                             |
              (new fix task in Todo)

Only humans can move tasks from In Review to Done/Wontdo.

Quick Start

API Server

export DBHOST=localhost DBUSER=forgebot DBPASS=secret DBNAME=forgebot
export GITEA_URL=https://git.unkin.net GITEA_TOKEN=<token>
make build
./bin/forgebot-api

Operator

./bin/forgebot-operator --api-url http://forgebot-api:8000
# or
FORGEBOT_API_URL=http://forgebot-api:8000 ./bin/forgebot-operator

TUI

./bin/forgebot-tui -api http://localhost:8000
# or
FORGEBOT_API_URL=http://forgebot-api:8000 ./bin/forgebot-tui

TUI Key Bindings

Key	Action
h/l or arrows	Move between columns
j/k or arrows	Move within column
Enter	Task detail view
e	Edit task in $EDITOR
n	Create new task
d	Mark done (in review only)
w	Mark wontdo (in review only)
r	Refresh
/	Filter by repository
?	Toggle help
q	Quit

API

Method	Path	Description
GET	/health	Health check
GET	/api/v1/tasks	List tasks (?status=, ?repository=)
POST	/api/v1/tasks	Create task
GET	/api/v1/tasks/{id}	Get task
PATCH	/api/v1/tasks/{id}	Update task status
POST	/api/v1/tasks/{id}/complete	Agent completion callback (triggers review workflow)
POST	/api/v1/tasks/{id}/comment	Post comment to forge
POST	/api/v1/webhook/gitea	Gitea webhook receiver

CRDs

• AgentPool — Configuration for a pool of AI agents (model, concurrency, image, resources)
• AgentTask — A task dispatched to a pool for execution
• ProviderQueue — Polls the API for pending tasks and creates AgentTask CRs
• RepositoryBinding — Links a repository to a queue and pool with access controls

Building

make build          # all binaries to bin/
make test           # run tests
make lint           # go vet
make fmt            # gofmt
make generate       # regenerate CRDs and RBAC
make docker-api     # build API container image
make docker-operator # build operator container image