hatchery

# hatchery

agent deployed to cloud, running mostly unattended. reachable from slack,
github, and its own ui.

hatchery monitors repos, can respond to issues, pings on slack, or cron
schedule. the output artifacts include reports, notifications, issues, and prs.

1. deployed to vercel as one fastapi service (see vercel.json)
2. vite + tanstack router frontend, statically served by fastapi (stock shadcn on base-ui primitives)
3. dogfoods ai sdk for python, rotor, sandbox, connect

## answer style

be brief, use simple terse language, do not use jargon. this helps with efficiency of communication.
do not overcomplicate. this is a test application, it should prioritize clarity.

## code guidelines

1. in python, import by module (unless it's `typing`) to improve namespacing and make it read to navigate code.
2. minimize the number of helper functions, prioritize locality of behavior.
3. keep apis as small as possible. keep public apis even smaller, try to shrink them to one function / object.
4. test file structure should mirror app's file structure, e.g. `agent/turn.py` -> `tests/agent/test_turn.py`. this helps project navigation a lot.
5. do not write tests that test mocks, codify broken behavior, repeat third-party library tests, or do typechecker's job.

## project setup

1. use uv to manage python (run inside `backend/`)
2. use pnpm to manage typescript (run inside `backend/frontend/`)

slack/github webhooks only reach deployments (vercel connect); point them at
the current branch with `scripts/triggers.sh`.

## how to verify and debug

1. use `docs/use-agent-browser.md` to access live deployments and run real agent sessions.
2. for completed runs, inspect telemetry traces in `docs/use-braintrust.md` to understand exactly what happened during the run.

More agent context in vercel-labs/hatchery

13 other files this repository gives its agents.