Self-hosting external AI Teams Control

English | 日本語

This repository distributes the AI Teams Codex Plugin. It starts no scheduler, poller, orchestration service, Discord/webhook runtime, GUI or service manager. Explicit Control Lite commands provide bounded local coordination, including the specialist task route below.

Operators who need persistent discovery, queued execution, recovery, or a control UI can separately install Qoo257/ai-teams-control. That project owns its runtime requirements, supported deployment shapes, persistence, credentials, installation, updates, backup, monitoring, and release lifecycle. Follow its current documentation rather than copying an old service procedure from a Plugin release.

Plugin and Control boundary

The Plugin owns product-development and Issue-delivery semantics, focused Skills, diagnostics and quality tooling, and a bounded Control MCP client. GitHub Issues, pull requests, Git refs, and hosted checks remain authoritative for GitHub delivery.

External Control may discover Issues, schedule work, persist its queue and recovery state, manage worker lifecycle, and expose optional GUI, Discord, or webhook integrations. It cannot weaken repository acceptance, effect authority, or the Plugin's bounded Issue-execution contract.

Installing or updating the Plugin starts no service and changes no Control file, configuration, credential, database, or process. Installing or updating Control is a separate operator-authorized effect and changes no Plugin release.

Integration safety

  • allowlist exact repositories and trusted operators;
  • keep Control credentials outside repositories and candidate workspaces;
  • grant only the provider permissions required by enabled effects;
  • treat queue, retry, recovery, and worker ownership as Control state, not as a second GitHub source of truth;
  • require exact candidate and hosted-check evidence before accepted delivery; and
  • stop on incompatible or unavailable Control capability instead of silently substituting a local execution route.

Machine-facing contracts remain in the bounded Issue execution, trusted delivery, and Control integration boundary.

Run a bounded specialist investigation

The optional skills/ai-teams/scripts/specialist_tasks.py entry point queues one research task in a selected Control Lite database outside the repository. It requires Linux, GNU timeout, an explicitly selected Codex CLI executable and a clean repository at the task's exact commit. Existing Codex authentication, model selection and host restrictions remain in effect. Installation starts no worker; run is one deliberate invocation.

Create a task JSON using the specialist input contract. Supply the question, bounded input, exact repository/work-item/commit, coordinator, result contract, wall-second budget and stop condition. Then use:

python3 <skill-dir>/scripts/specialist_tasks.py --database <local-store> --repo OWNER/REPO \
  enqueue --input <task.json> --coordinator <coordinator>
python3 <skill-dir>/scripts/specialist_tasks.py --database <local-store> --repo OWNER/REPO \
  run --task <task-id> --coordinator <coordinator> --revision <commit> \
  --cwd <clean-checkout> --codex <absolute-codex-executable>

Budget is 1–900 elapsed seconds for the local process group. The host deadline survives coordinator death. Unknown termination keeps the workstream reserved; use reconcile --task <task-id> --coordinator <coordinator> to inspect and stop only its exact recorded host. An ambiguous identity remains held. The adapter cannot cap remote billing or stop detached/escaped processes. Elapsed time is reported; monetary cost is unavailable. Do not infer a currency or token budget.

read --task <task-id> shows the bounded result and its decision_question. Create a provider-owned scoped Decision with that exact question, options accept/reject and the task's single work-item scope through normal Work Item creation. Use the existing Decision Inbox to record the coordinator's answer and rationale. Then decide --task <task-id> --coordinator <coordinator> --decision-issue <number> --decision-revision <provider-revision> confirms it against fresh provider evidence. status shows Project State and the actual decision impact; changed or unavailable Decision evidence is not acceptance. Neither read command changes tasks or starts processes.