Getting started

Prerequisites

• Python 3.11 or later
• uv (install with curl -LsSf https://astral.sh/uv/install.sh | sh)
• A GitHub account with permission to create a GitHub App
• Any toolchains required by the repos you configure. Quality tools run locally, so you need every binary they reference installed on the machine. Some tools come bundled with a language (e.g. gofmt ships with Go) but others are standalone (e.g. golangci-lint must be installed separately via brew install golangci-lint). Check your developer.yaml quality tool commands and make sure each binary is on PATH.

Install

Clone the repo and install dependencies:

git clone https://github.com/gregology/developer.git
cd developer
uv sync

Create a GitHub App

Developer authenticates as a GitHub App, not as your personal account. This keeps permissions scoped and lets it act as a bot identity.

1. Go to Settings -> Developer settings -> GitHub Apps -> New GitHub App
2. Give it a name (e.g. "Developer")
3. Set the homepage URL to anything (your repo works fine)
4. Under Permissions, grant:
   • Issues: Read & Write
   • Pull requests: Read & Write
   • Contents: Read & Write
5. Click Create GitHub App
6. On the app's settings page, note the App ID
7. Scroll down and click Generate a private key -- save the .pem file
8. Install the app on your account or org, note the Installation ID from the URL

Configure credentials

cp example.env .env

Fill in your .env:

GITHUB_APP_ID=123456
GITHUB_INSTALLATION_ID=789012

# Paste the PEM contents directly, or use a file path
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----"

The .env file is gitignored. Don't commit it.

Add a repo

Copy the example config and customize it:

cp example.developer.yaml developer.yaml

The developer.yaml file is gitignored -- it's your personal config, same pattern as example.env -> .env. Each repo needs GitHub coordinates, setup commands, and quality tools:

repos:
  my-project:
    github:
      owner: myorg
      repo: my-project
    setup:
      - uv sync
    quality_tools:
      - name: ruff
        cmd: [uv, run, ruff, check, src/]

See Configuration for the full format.

First run

Try a dry run to make sure everything is wired up:

developer review my-project 1 --dry-run

This will clone the repo, pull the PR diff, run the review pipeline, and print the review comment without actually posting it. If credentials or config are wrong, you'll get a clear error here.

Once that works, drop the --dry-run:

developer review my-project 1

Developer clones repos into a local repos/ directory on first run and pulls latest on subsequent runs. The directory is gitignored. Deleting it is safe -- it'll re-clone next time.

Running the API server

If you prefer HTTP over CLI, start the API server:

developer serve

This starts a FastAPI server on localhost:6768. Use --host and --port to customize. All the same pipelines are available — see API reference for endpoints.

If your venv isn't activated

Prefix commands with uv run:

uv run developer resolve my-project 25