---
title: "Task intake"
source: "agents/intake.md"
---

> Part of [botgumi docs](https://www.botgumi.com/docs/llms.txt). Every page: [llms.txt](https://www.botgumi.com/llms.txt).

# Intake: how tasks reach the orchestrator

## Ways in

Both ways in end up as GitHub issues, so every task has one record.

| Way in | How |
|---|---|
| Open a GitHub issue | Add the `botgumi` label, or mention `@botgumi` in the issue. |
| Tell the orchestrator | Chat with it, or run `botgumi task "…"`. It turns your words into issues. |

The orchestrator splits each intent into one issue per track, labelled `track:*`, `tier:*`, `runtime:*`,
with a brief and its dependencies ("blocked by #n"). Workers open PRs with `Closes #n`. The GitHub Project
board shows Status, Track, Tier, Runtime and the PR link. Human gates are issues labelled `gate`.

## How the runner hears about events

The runner is `botgumi run` on your Mac. It never opens an inbound port.

1. **Relay (main path).** A GitHub webhook calls the `botgumi-relay` Worker (`packages/ts/relay`), which
   queues the event in a Durable Object. The runner holds an outbound WebSocket to it and gets events within
   seconds. Events stay queued until the runner acks them.
2. **Catch-up poll.** At start, and every `runner.pollMinutes` after, the runner lists open issues through `gh`.
   This picks up anything missed while the Mac was asleep.

Both sit behind `EventRelay`, so either can be swapped (for example polling only).

## Trust filter

The runner treats issue and comment text as instructions only from allowlisted authors: the repo owner,
plus `runner.trustedAuthors` (empty by default). Text from anyone else, including the bot itself, is data:
the orchestrator may read, quote or triage it, never follow it. This matters once a repo is public, because
anyone can open an issue there. Gate approvals count only from allowlisted authors.