Admin UI reference for AI-Implement

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.

The admin UI at /admin is the control panel for your AI-Implement orchestrator. It is protected by the ADMIN_ACCESS_CODE environment variable — if that variable is not set, the UI is disabled and all /admin and /api/* routes return 404. Every panel below is also reachable programmatically through the JSON API at the bottom of this page.

The sidebar organizes panels into four groups:

Work — Overview, Issues, Pipelines, Pull requests, Blockers
Configure — Projects, Pipelines & steps, Models & providers
Platform — Runners, Sessions, Reaper, Secrets, Settings
Developer — Audit log, Customizations

The headings below follow the same order.

Work

Overview

The main dashboard. Shows real-time orchestrator health:

Running jobs (with duration)
Failed jobs in the last 24 hours
Capacity utilization across all projects
Projects at concurrency cap
Stale workflow templates in target repos
A 24-hour dispatch trend chart

Environment-status checks (ticketing connection, runner callback, gap-fill trigger) appear here too — this is the first place to look if a run hasn’t dispatched as expected.

Issues

The AI-Implement inbox. Shows every issue matched by the configured project mappings, its current state (started / completed / cancelled), and whether each is ready for implementation or still has planning pending. A second table breaks down in-progress counts by project mapping for real-time visibility into which scopes are currently working.

Pipelines (jobs)

The dispatch log under its real internal name (jobs in the sidebar). Shows the last ~500 dispatch entries (timestamped) across all teams with full execution history:

Issue ID
Repo
Team (the teamKey shown in the row)
Runner mode (GitHub Actions or Fly Machines)
Session image
Combined planning-and-implementation statuses
Pull-request links
Dispatch number (for re-dispatches)

Planning and implementation dispatches for the same issue are grouped visually as a single job.

Use this log to audit activity or diagnose why an issue was or was not picked up.

Pull requests

Lists every bot-opened pull request the orchestrator is tracking, with the following information:

Issue link
Repo
Current job status (running / completed / failed / review_failed)
Iteration count (the dispatch number)
Time since last dispatch
Direct links to GitHub

Useful for spotting PRs that are stalled or failing review without scanning each repo individually.

Blockers

Surfaces issues that are currently not being picked up despite being eligible. KPI cards show:

Total blocked issues
Teams affected (distinct teams with at least one blocked issue)
Count blocked by concurrency cap
Count blocked by dedup window

Per-issue rows include:

Issue identifier
Project mapping
Blocking reason
Direct link back to the ticket

Configure

Projects (team/repo mappings)

The Projects panel is where you connect ticketing scopes (Linear teams or Jira JQL clauses) to GitHub repositories and control exactly how AI-Implement dispatches runs for each scope.

See Configure project mappings for the full field reference and defaults.

New in latest:

The Projects stepper exposes three optional run-cap fields — maxTurns, maxIterations, and maxJobMinutes — in the Capacity step. Tune these per project to control cost and reliability.
The Default Branch field is now required. Use the repository’s actual primary branch (commonly main, master, or development).

Create a new project mapping

Open the stepper

Click Configure → Projects → + New project. The stepper walks through 8 configuration steps.

Fill in Ticketing System and Source

Pick Linear or Jira as the ticketing system, fill in the provider-specific config (Linear team key, or Jira JQL + repo-field value), then enter the target repo’s GitHub Owner, Repository Name, and Default Branch.

Default Branch is required and must match the repo’s actual primary branch (commonly main, master, or development).

Step through the remaining configuration

Runner, Provider, Capacity, Secrets, and Review steps follow. For a first run, defaults are reasonable.The Capacity step exposes three optional run-cap fields:

Field	Default if blank	Purpose
`maxTurns`	50	Maximum Claude conversation turns per run
`maxIterations`	Bedrock: 2, Anthropic: 3	Maximum feedback-loop iterations per run
`maxJobMinutes`	90	Wall-clock timeout before forced termination (minutes)

Leave any field blank to use the default. Setting these tighter than the defaults is the recommended way to control cost and reliability per project.

Setting provider to bedrock requires awsRegion and is not compatible with executionMode: fly-machines.You must also add AWS_BEDROCK_ROLE_ARN as a secret in the target repo and set the AI_IMPLEMENT_PROVIDER and AI_IMPLEMENT_AWS_REGION repo variables so comment-triggered gap-fill runs use the same auth path.

Create the project

Click Create project. The new mapping appears in the Projects table automatically — if it does not, reload the page.

Each row in the Projects table also exposes a Sync workflows action, which opens or updates a pull request in the target repo containing the workflow files and starter prompts. This is the normal way to push workflow updates from the orchestrator into target repos.

Pipelines & steps

Shows the pipeline YAML definitions (the built-in src/pipeline/*.yml plus any custom/pipelines/*.yml overrides) as collapsible details, each listing the steps that run and their module IDs. A second table lists every step module with:

Built-in path
Custom override path (if present)
Status (built-in / override / additive)

Useful for visualizing the extension hierarchy when you’ve added custom steps. See Add custom pipeline steps for the override mechanism.

Models & providers

Read-only summary of model provider and region per project mapping.

Model IDs themselves live in each target repo’s WORKFLOW.md and PLANNING.md front matter — this page doesn’t edit them.

KPI cards show:

Projects (total)
Anthropic (count of projects using the Anthropic provider)
Bedrock (count of projects using the Bedrock provider)
Bedrock regions (count of distinct regions in use)

The table lists each project’s:

Team (the teamKey)
Repo
Provider badge (anthropic or bedrock)
Bedrock region (or a “missing” badge if required and unset)
Planning status
Runner mode

Platform

Runners

High-level runner-infrastructure dashboard. KPI cards show:

Current runner-mode override (default / gha / fly / shadow)
Live Fly session count
Capacity utilization (in-progress runs vs. total cap across mappings)
24-hour reaper destructions

A live-sessions table (top 8) links into the Sessions panel for the full list. A per-project table shows each mapping’s:

Configured execution mode
Effective mode (after applying any global override)
Capacity-utilization meter

Sessions

Lists every Fly Machine session currently in started, starting, or created state. Each row shows:

Machine ID and name
Current state
Uptime duration
Associated issue identifier (linked to the ticketing system), where available
Target repo, where available

You can destroy a stuck session directly from this panel. Destroying a session also:

Removes the in-progress marker from the associated issue (the AI-Working label on Linear, or Implementing status on Jira)
Clears it from the deduplication window, so the orchestrator can pick it up again on the next poll

If a Fly Machine appears stuck and is not progressing, destroying it from the sessions panel is the cleanest recovery path.

Reaper

The reconciliation-sweep dashboard. The top of the page hosts the runner mode toggle (default / gha / fly / shadow).

If the RUNNER_MODE environment variable is set on the orchestrator process, it takes precedence over this database value and the UI flags that an env-var lock is active.

A summary card shows the 24-hour total of machines and jobs the reaper destroyed, broken down by rule:

orphan
stale-terminal-job
max-age-exceeded
issue-terminal

Plus the last sweep timestamp. A recent-actions table lists the latest destructions with:

Timestamp
Rule matched
Machine ID
Tenant
Associated issue
Age at destruction (in seconds)
dry-run or destroyed badge (indicating whether the action was a no-op or executed)

If you change runner mode via the UI or API while RUNNER_MODE is set in the environment, the new value is persisted to the database but has no effect until the env var is removed and the orchestrator is restarted.

Secrets

Per-team secrets

Each project mapping has its own per-team secrets at /api/mappings/:teamKey/secrets. Secrets are stored as Fly app secrets with the team key as a prefix (e.g. a secret named MY_TOKEN for project ENG is stored as ENG_MY_TOKEN).

Secret names must contain only letters, digits, and underscores.

Global secrets

Global secrets are Fly app secrets that do not belong to any specific project mapping. They are listed, created, and deleted from /api/global-secrets.

Global secret names must not start with any project key prefix (to keep the per-team scoping unambiguous).

Settings

The settings panel manages orchestrator-level configuration:

flySessionsApp — the Fly.io app name used for Fly Machine sessions.
flySessionsRegion — the default region for new Fly Machine sessions.

Both values can be overridden at the environment level via FLY_SESSIONS_APP and FLY_SESSIONS_REGION. When an env override is active, the UI shows the runtime value alongside the database value and flags that the env var is winning.

Changes to settings that differ from the running process take effect after a restart.

Developer

Audit log

Shows the dispatch-deduplication ledger for the last 24 hours. Each row includes:

Issue identifier and title
When the issue was dispatched
A delete button to remove it from the dedup window

Issues are deduplicated for 24 hours after dispatch to prevent the orchestrator from picking up the same issue repeatedly. The dedup panel shows every issue currently in the dedup window. You can manually remove an issue from the dedup window if you want the orchestrator to re-dispatch it before the 24-hour window expires.

The roadmap calls for richer audit-log content here over time; the current implementation is focused on the dedup window.

Customizations

Lists every file under the custom/ directory in the orchestrator’s working tree that overrides a built-in. The table shows each file’s:

Path
Category (pipeline / step / provider / other)
Status (override / additive / — for the other category)
Upstream counterpart path it shadows
File size
Last-modified time

A CI workflow (protect-custom.yml) flags upstream PRs that modify files under custom/ outside the allowed paths (custom/README.md and .gitkeep files). The check is currently advisory — it won’t hard-block a merge but will surface a warning in CI. The team has it tracked to restore as a hard fail.See Add custom pipeline steps for the resolution rules.

Admin API reference

All /api/* endpoints except /api/auth require a Bearer token obtained from /api/auth. Tokens expire after 24 hours.

Authentication

Obtain a bearer token

POST your access code to /api/auth:

curl -s -X POST https://your-orchestrator/api/auth \
  -H "Content-Type: application/json" \
  -d '{"code": "your-access-code"}' \
  | jq -r '.token'

The response contains a token field. Store it for subsequent requests.

Pass the token on subsequent requests

Include the token as a Bearer header:

TOKEN="<token from previous step>"
curl -s https://your-orchestrator/api/mappings \
  -H "Authorization: Bearer $TOKEN"

Endpoint reference

Method	Path	Description
`POST`	`/api/auth`	Authenticate with access code; returns bearer token
`GET`	`/api/mappings`	List all project mappings
`POST`	`/api/mappings`	Create or update a project mapping
`PATCH`	`/api/mappings/:teamKey`	Update a mapping’s concurrency cap (`maxInProgressAiIssues`) or paused state (`paused`)
`DELETE`	`/api/mappings/:teamKey`	Delete a mapping
`POST`	`/api/mappings/:teamKey/sync-workflows`	Re-sync workflow templates from the orchestrator into the target repo.
`POST`	`/api/jira/validate-jql`	Validate a JQL clause against a Jira instance before saving
`GET`	`/api/jira/fields`	List available Jira custom fields
`GET`	`/api/jira/field-options`	List options for a Jira select field
`GET`	`/api/log`	Dispatch audit log (last 500 entries)
`GET`	`/api/jobs/:jobId/steps`	Get step-by-step execution status for a specific job
`GET`	`/api/issues`	List AI-Implement issues across all configured project mappings
`GET`	`/api/pulls`	List bot-opened pull requests tracked by the orchestrator
`GET`	`/api/blockers`	List issues currently blocked from dispatch, with reason
`GET`	`/api/sessions`	List active Fly Machine sessions
`DELETE`	`/api/sessions/:machineId`	Destroy a session and reset the associated issue
`GET`	`/api/reaper/summary`	24-hour reaper destruction summary, broken down by rule
`GET`	`/api/reaper/recent`	List recent reaper destruction actions
`GET`	`/api/dedup`	List issues in the 24-hour dedup window
`DELETE`	`/api/dedup/:issueId`	Remove an issue from the dedup window
`GET`	`/api/runner-mode`	Get current runner mode
`POST`	`/api/runner-mode`	Set runner mode
`GET`	`/api/settings`	Get orchestrator settings
`POST`	`/api/settings`	Update orchestrator settings
`GET`	`/api/global-secrets`	List global Fly secrets
`POST`	`/api/global-secrets`	Set a global Fly secret
`DELETE`	`/api/global-secrets/:name`	Delete a global Fly secret
`GET`	`/api/mappings/:teamKey/secrets`	List per-team Fly secrets
`POST`	`/api/mappings/:teamKey/secrets`	Set a per-team Fly secret
`DELETE`	`/api/mappings/:teamKey/secrets/:name`	Delete a per-team Fly secret
`GET`	`/api/customizations`	List files under `custom/` that override built-ins
`GET`	`/api/pipelines-steps`	List pipeline definitions and step modules with override status
`GET`	`/api/admin/config-status`	Get environment-status checks (ticketing connection, runner callback, gap-fill trigger)
`GET`	`/api/admin/template-status`	Get workflow-template staleness status per target repo

/api/auth is the only endpoint that does not require a bearer token. All other /api/* routes return 401 Unauthorized if the token is missing or expired.

Runner callback endpoints

Two endpoints sit outside the /api/* namespace and are called by runners (GitHub Actions workflow jobs, Fly Machine sessions, or local Docker containers running an issue), not by operators. They use a separate authentication scheme from the bearer tokens above.

Method	Path	Purpose
`POST`	`/runner/result`	Reports the final outcome of a dispatch — success or failure, PR URL when one was opened, error context when not. The token is single-use: once consumed, the dispatch result is locked in and the endpoint rejects further calls for that dispatch.
`POST`	`/runner/progress`	Streams step-by-step progress updates throughout a run (each pipeline step’s status, elapsed time, and any structured output). The token is multi-use so the runner can post many updates during a single dispatch; consumed independently of the result token.

Both endpoints respond 501 Not Implemented when the orchestrator has no RUNNER_TOKEN_SECRET configured, since neither can validate tokens without it.

Operators do not normally call these directly. They’re documented here so that monitoring tools, ingress configurations, and debugging sessions can account for runner-side traffic correctly.

Webhook and trigger endpoints

Two endpoints sit outside the operator API but are operator-configurable: you set their URLs and secrets in your target repos (or at the organization level), and the orchestrator validates incoming requests against those secrets. Documented here so monitoring tools, ingress rules, and integration testing can account for the routes.

Method	Path	Purpose
`POST`	`/api/github/webhook`	Receives GitHub webhook events from your target repos — pull request reviews, review comments, issue comments, and pull request merges. Validates the HMAC signature against `GITHUB_WEBHOOK_SECRET`. Returns `503` when the secret is unset (endpoint disabled).
`POST`	`/trigger/gap-fill`	Called by `comment-trigger.yml` in your target repo when a user comments `/ai-implement` on a PR. Validates a bearer token equal to `GAP_FILL_TRIGGER_SECRET`. Dispatches a gap-fill run for the PR. Returns `503` when the secret is unset (trigger disabled).

Both endpoints require their corresponding secret to be configured on the orchestrator.See GITHUB_WEBHOOK_SECRET and GAP_FILL_TRIGGER_SECRET

​Work

​Overview

​Issues

​Pipelines (jobs)

​Pull requests

​Blockers

​Configure

​Projects (team/repo mappings)

​Create a new project mapping

​Pipelines & steps

​Models & providers

​Platform

​Runners

​Sessions

​Reaper

​Secrets

​Per-team secrets

​Global secrets

​Settings

​Developer

​Audit log

​Customizations

​Admin API reference

​Authentication

​Endpoint reference

​Runner callback endpoints

​Webhook and trigger endpoints

Work

Overview

Issues

Pipelines (jobs)

Pull requests

Blockers

Configure

Projects (team/repo mappings)

Create a new project mapping

Pipelines & steps

Models & providers

Platform

Runners

Sessions

Reaper

Secrets

Per-team secrets

Global secrets

Settings

Developer

Audit log

Customizations

Admin API reference

Authentication

Endpoint reference

Runner callback endpoints

Webhook and trigger endpoints