Getting started¶

Prerequisites¶

Python 3.11 or later
uv (install with curl -LsSf https://astral.sh/uv/install.sh | sh)
git
A Claude Code login (claude auth login) or an ANTHROPIC_API_KEY. Developer runs the Claude Code CLI bundled with the Claude Agent SDK, so you don't need to install Claude Code separately.
On Linux, bubblewrap and socat, for the sandbox the agent's commands run in. Ubuntu 24.04 and later also need an AppArmor profile for bwrap; see Claude Code's sandbox docs. developer doctor checks all of this.
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.

Go to Settings -> Developer settings -> GitHub Apps -> New GitHub App
Give it a name (e.g. "Developer")
Set the homepage URL to anything (your repo works fine)
Under Permissions, grant:
- Issues: Read & Write
- Pull requests: Read & Write
- Contents: Read & Write
- Checks: Read (address reads a PR's CI results)
Don't grant Workflows. Developer never commits changes to .github/workflows, and without that permission GitHub refuses them anyway. 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 each account or org that owns a repo you'll add. Developer finds the installation for each repo itself.

A new app is private, and a private app can only be installed on the account that owns it. To install it on other accounts too, make it public first: on the app's settings page, under Advanced, click Make public. Anyone can then install it, but an installation only gives your app access to the installer's repos, never the other way round.

Configure credentials¶

cp example.env .env

Fill in your .env:

GITHUB_APP_ID=123456

# 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, and keep it readable only by you (chmod 600 .env). A path to a key file kept outside the repo works too.

Variables exported in your shell take precedence over .env. Developer reads these values directly and never exports them, and it blanks them in the agent's environment, so the agent can't see the key.

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¶

Check that this machine has everything Developer needs:

developer doctor
developer doctor --online   # also checks the GitHub App can reach every repo

Then 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 repos/ directory beside developer.yaml (or in DEVELOPER_HOME) on first run and fetches into those clones on later runs. Each run works in a temporary worktree rather than in the clone. The directory is gitignored. Deleting it is safe -- it'll re-clone next time.

Running the API server¶

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

uv sync --extra api
developer serve

This starts a FastAPI server on localhost:6768. To serve beyond this machine, set DEVELOPER_API_TOKEN first; clients then send it as a bearer token. 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