Skip to main content
Experimental version.This is the latest in-development version of AI-Implement. Features may change without notice and behavior is not guaranteed. Switch to the latest stable version here.
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, Node.js 24.x, and model access for your selected agent. Codex uses a managed OpenAI profile; legacy Claude projects use their existing provider credentials. 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.
For the Codex path, also set these orchestrator values:A GitHub-hosted job cannot call back to localhost. Expose your local orchestrator through a reachable HTTPS URL, or deploy a persistent orchestrator. Planning refuses dispatch without the callback URL and secret.These settings 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:These GitHub App secrets are shared by both agent paths.For a legacy Claude project, also add ANTHROPIC_API_KEY, or use CLAUDE_CODE_OAUTH_TOKEN (which takes precedence). Bedrock has its own setup.For an all-Codex configured project, skip the Anthropic secrets. You will add the managed OpenAI credential after creating the project mapping.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 ordinary jobs 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.For a configured Codex smoke, follow the local Codex procedure. Local Docker does not provide the managed GitHub Actions review-fix path.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. Fill in the ticketing and source fields first.
  • 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.
Choose GitHub Actions as the runner for this Codex path. Complete the remaining project fields, then click Create project. Stage settings are added after the project exists.
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.Check that the runner image supports Codex. For an existing project, use Sync workflows and merge the update before continuing.The workflows open pull requests using the GitHub App credentials. The Allow GitHub Actions to create and approve pull requests setting is not required.
8

Add your OpenAI account

To use Codex, open Models & providers as an administrator. Create a Codex account profile, permit it for the new project, then set an OpenAI API key or connect your own ChatGPT plan. Follow that guide’s readiness checks before continuing.Skip this step and the next if you are keeping the project on legacy Claude behavior.
9

Choose the agents and opt the project in

Follow Agent settings per stage to fill Orchestrator stage defaults, then set Settings → Orchestrator Agent Defaults → Defaults mode to configured.For an all-Codex setup, select codex, openai, an available model, the permitted OpenAI profile, and an elapsed timeout for all three stages. Setting defaults does not enroll a project.On Projects, open Edit → Agents for the saved project. Check the effective values, select Opt in to stage agent configuration, and click Save agent settings. If readiness refuses the save, use the troubleshooting guide.
10

Create the trigger in your ticketing system

Follow Prepare the Linear labels before your first run. Create the pickup label (AI-Implement by default) and the workspace-level Ready for Review label. AI-Implement creates the other lifecycle labels automatically.
11

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.
On the next eligible poll, the orchestrator picks it up, marks it in progress, and dispatches the GitHub Actions workflow. Planning runs first if enabled. The selected implementation agent reads WORKFLOW.md and changes the code; the pipeline pushes the branch 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.
12

Verify the agent and result

Check the run evidence, including Reports → Agent attribution, the PR’s harness/model/provider footer, and the review outcome. Saved defaults alone do not prove which agent ran.The attribution card shows the latest invocation per job, not whole-job token or cost totals. An unavailable cost does not mean the run was free.

​
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 the selected agent repo-specific instructions. Choose configured models in stage settings.

Enable planning

Have the planning agent post its implementation map, acceptance bar, and risks before implementation.

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.