Projects

A project is one GitHub repository checked out on one runner machine. Every other screen (fleet, queue, approvals, history, skills, schedules, usage) is scoped to a project, so connecting one is the first thing you do after pairing a runner.

Only an admin can connect or remove a project. The control plane never reads the disk itself: the runner inspects the path and reports what it found, and the API stores that report.

Before you start

• A runner is paired and online. See Install and pair.
• The repository is cloned on that machine, with origin pointing at GitHub.
• For the orchestrator screens (Fleet, Queue, Approvals) to do anything, the repository needs a .code-analyzer-config.json with an orchestrator block. You can connect without it and add it later. See Code Sentinel config.

Connect a repository

1. 1

   Open the Connect dialog

   Go to Projects → Connect project. If no runner is online, a banner above the form says whether none is paired or which one is offline, and how to start it. The dialog re-reads the runner list every 10 seconds while it is open.

2. 2

   Pick a runner and enter the path

   Choose an online runner and type the absolute path of the repository's main checkout on that machine, for example /home/you/dev/my-repo.

   The path must be the main checkout, not a linked worktree and not a subdirectory. If you point at a worktree such as .wt-my-repo-i42, the runner reports the main checkout's path instead and the dialog offers Use this path.

3. 3

   Inspect

   Click Inspect. The runner runs project.inspect against the path and returns a preview. Nothing is stored yet.

4. 4

   Connect

   Review the preview and click Connect. The API re-inspects, stores the project and its docs source, and pushes the new watch list to the runner, which starts its collectors for the project.

Connect stays disabled when the preview shows a non-main checkout or a non-GitHub remote, because the API would refuse both.

What Inspect detects

Fact	Where it comes from
Repository	owner/name parsed from origin ([email protected]:owner/name.git or https://github.com/owner/name)
Checkout	The absolute main checkout, from git rev-parse --git-common-dir
Base branch	orchestrator.base in .code-analyzer-config.json, else origin/HEAD, else gh repo view, else main. The preview shows which source won
Code Sentinel config	The orchestrator block of .code-analyzer-config.json, stored as a snapshot. Invalid JSON is reported, not fatal
CLAUDE.md, AGENTS.md	Whether each file exists at the root
Docs source	Where the project's specs and decisions live (next section)
Warnings	Sentences for anything that needs your attention

AgentDock reads .code-analyzer-config.json but never writes it. To change the orchestrator's behaviour, edit and commit that file yourself.

Docs source detection

Code Sentinel's cs-spec writes specifications somewhere, and some teams keep docs in a separate repository. The runner looks in this order and stops at the first hit:

1. orchestrator.specDir in the config: a path inside the repository, a path outside it (../my-repo-documentation/prs), or a GitHub URL.
2. A sibling folder <parent>/<name>-documentation, then <parent>/<name>-docs.
3. A same-owner GitHub repository owner/<name>-documentation or owner/<name>-docs (found with gh repo view, no local copy).
4. A link to a docs folder or repository in AGENTS.md, CLAUDE.md or README.md, accepted only if it resolves to a sibling folder or a same-owner repository.
5. A back-link: a sibling *-documentation or *-docs folder whose README.md names this repository.
6. An in-repo docs/ folder.

The result has a kind (in_repo, sibling_repo, remote_repo or none), the evidence (file and line, or URL) and the full candidate checklist with hit or miss. Inside the found folder the runner classifies one level deep into specs, ADRs, roadmap and reports.

Detection reads only the project root, the direct children of its parent folder (and their README.md), and the docs root it found. Nothing else on disk is touched.

A project with no docs source can still be connected; it gets kind: none and a warning.

Project settings

Open Project → Settings. It has five tabs. Everyone with access can read them; who can change what is noted per tab.

Tab	What you set	Who can change it
General	Display name, base branch override, ready label override, default runtime profile, merge approval	Admin
Docs source	The detected source with evidence; Refresh re-runs detection; Override sets it by hand	Refresh: operator. Override: admin
Orchestrator	Runtime profile, model and permission mode used by Start… on the Fleet page	Profile: admin. Model and mode: operator (bypassPermissions needs an admin)
Members	Who can see the project and with which role	Admin
Budget	Spending limits for this project	Admin (operators can view)

Notes on the General tab:

• Base branch override: empty uses the detected base.
• Ready label override: empty uses orchestrator.readyLabel from the config, else cs:ready. See Task queue.
• Default runtime profile: one of the profiles the project's runner reports. The orchestrator, skill runs and schedules fall back to it. See Runtime profiles.
• Merge approval: your intent that a person approves every pull request before it merges. The orchestrator itself obeys the project's config file. See Merge approvals.

A manual docs source override cannot be checked on disk, so the runner keeps it across refreshes until you reset it, which re-runs detection.

Members

Admins see every project without a membership row. Operators and viewers see only projects where they are members.

In Members → Add member you pick an active user and, optionally, a Role override. The override can only lower the member's global role: an operator with a viewer override is a viewer on this project, while a viewer with an operator override stays a viewer. The table shows the global role, the override and the effective role. See Users and roles.

Removing a project

General → Remove project (admin) deletes the project, its members and its docs source, and tells the runner to stop watching it.

Errors you may see

Code	Meaning	Fix
not_main_checkout	The path is a linked worktree or a subdirectory	Use the main checkout path the preview suggests
unsupported_forge	origin is not on GitHub, or there is no origin	Only GitHub repositories are supported today
already_connected	This runner already has a project at that path	Open the existing project
path_not_found, not_a_repository	The path does not exist on the runner, or is not a git repository	Check the path on that machine
runner_offline	The chosen runner has no live connection	Start the runner (agentdock-runner run or its service)
profile_not_on_runner	The default profile belongs to another runner	Pick a profile of the project's runner

The same owner/repo on two machines is two separate projects.

Next steps