codeflash-agent/packages/github-app/CLAUDE.md

GitHub App Service Guide

Thin webhook dispatcher for CI mode. Receives GitHub webhooks, clones the repo, writes .codeflash/ci-context.json, and invokes the codeflash-ci plugin agent.

Working Directory

When you run service-specific commands, use packages/github-app/ as the working directory.

Verification

Run the service checks from the repo root:

uv run pytest packages/github-app -v
uv run ruff check packages/github-app
uv run ruff format packages/github-app
uv run mypy packages/github-app/github_app

Structure

• github_app/app.py owns FastAPI lifecycle, webhook routing, CI context writing, and agent invocation.
• github_app/agents.py runs the CLI backend (Claude/Codex) with GITHUB_TOKEN for gh CLI auth.
• github_app/auth.py handles GitHub App JWT and installation token authentication.
• github_app/github.py contains GitHub API helpers (used by other services, not by dispatch handlers).
• github_app/backends.py defines CLI backend specs (Claude, Codex) and command building.
• github_app/config.py loads environment-based configuration.
• github_app/git.py handles repo cloning and workspace management.
• github_app/retry.py provides retry logic with exponential backoff.
• tests/ uses async pytest patterns and validates webhook behavior and agent invocation.

Conventions

• Dispatch handlers are thin: extract metadata, write JSON context, call run_agent().
• The agent handles all GitHub interactions via gh CLI (not the service).
• Keep handlers non-blocking and register them through EVENT_HANDLERS.