Skip to main content
This guide walks you through running AI-Implement for the first time. By the end, you’ll have the orchestrator running locally, a target repo connected, and a Linear issue on its way to becoming a pull request.
Before you start, make sure you have: a Linear or Jira workspace with API access, a GitHub App you control, a Fly.io account (for the runner), and an Anthropic API key or AWS Bedrock access. See Prerequisites for details on setting each one up.
1

Clone the repository

Clone AI-Implement and move into the project directory:
2

Configure your environment

Copy the example environment file and fill in your credentials:
Open .env and set at minimum:
See Create a Linear app if you haven’t created one yet.
The other variables in .env.example are optional for a first run:
Set ADMIN_ACCESS_CODE to a non-empty value so you can reach the admin UI at the project mapping step. It’s the quickest option for a first run; admin sign-in is the better fit once you deploy.
3

Add required secrets to the target repo

In the target repo’s Settings → Secrets and variables → Actions, add these org or repo secrets:If you prefer Claude Code OAuth authentication over an API key, add CLAUDE_CODE_OAUTH_TOKEN instead of (or in addition to) ANTHROPIC_API_KEY. OAuth takes precedence.See Environment variables for AI-Implement for more detailed information on each variable.
4

Install the GitHub App on the target repo

In your GitHub App settings, install the app on the target repository. This gives the orchestrator permission to dispatch workflows and the workflow permission to push branches and open PRs.
5

Install dependencies and start the orchestrator

Install packages and start the development server:
The orchestrator starts polling for new issues and serving HTTP on port 8080. You should see log output confirming both.
Want to run the entire loop on your own machine? npm run dev:local executes each job locally instead of on GitHub Actions — the orchestrator still polls your ticketing system and opens pull requests. See Local development for what it needs and when to use it.npm run dev:run is the smaller one: a single task read from a file, with no ticketing system and no orchestrator involved. See the local harness.
6

Create a project mapping in the admin UI

Open the admin UI at http://localhost:8080/admin and enter your ADMIN_ACCESS_CODE.Click Configure → Projects → + New project to open the stepper. For a first run, fill ticketing config and source, then accept defaults for the rest.
  • Ticketing System — Linear
  • Ticketing Config → Linear Team Key — your Linear team’s identifier (e.g. ENG)
  • Source → GitHub Owner — the GitHub org or user (e.g. your-org)
  • Source → Repository Name — the repository name (e.g. your-repo)
  • Source → Default Branch — the repo’s primary branch (e.g. main). Must match the repo exactly.
Nothing checks the default branch name against the repository when you save. A default branch name that does not exist saves cleanly and fails the run at its first step, when the runner tries to clone it.
Click through the remaining steps (Runner, Provider, Capacity, Secrets, Review) accepting defaults, then Create project.
7

Review and merge the workflow pull request

Creating the project mapping opens a pull request in your target repo containing claude-implement.yml, claude-plan.yml, and starter WORKFLOW.md and PLANNING.md files.Merge it before continuing — the workflows have to be on the default branch for AI-Implement to dispatch them.
8

Create the trigger in your ticketing system

In your Linear workspace, create a label named exactly AI-Implement. The orchestrator polls for issues with this label — the name must match.You’ll also want to create an AI-Working label. AI-Implement adds this to an issue while a run is in progress and removes it when the run finishes.
9

Mark an issue and watch the PR appear

In your Linear workspace, open any issue in the team you mapped and add the AI-Implement label.
Within 60 seconds (one poll cycle), the orchestrator picks it up, marks it in progress, and dispatches the GitHub Actions workflow. Claude checks out the repo, reads WORKFLOW.md, implements the issue, and opens a PR.When the run finishes, the issue is marked ready for review (Linear: Ready for Review label; Jira: AI-Implement Status = PR Ready), and the PR has an automated review comment on its merge readiness.
If nothing happens after 60–90 seconds, check the orchestrator logs in your terminal. The most common causes are a missing project mapping, incorrect ticketing credentials (LINEAR_CLIENT_ID and LINEAR_CLIENT_SECRET, or JIRA_TOKEN), or a GitHub App that isn’t installed on the target repo.

​
Next steps

Now that you have a working end-to-end flow, here is where you can go next.

Deploy the orchestrator

Move off your machine to a persistent Fly.io app.

Customize WORKFLOW.md

Give Claude repo-specific instructions, and set the model it runs.

Enable planning

Have Claude post an implementation map, an acceptance bar, and the risks it found to your ticketing system before it implements.

Project mappings

Connect additional projects to repos, and tune how each one dispatches.

Admin sign-in

Per-person sign-in in place of a shared access code.

Self-deployment

Let the orchestrator build and release its own updates.

Knowledge graph

Project memory the BuildDown skills search before they plan.