AgentControlPlane

https://github.com/ya-karas/agentcontrolplane
Admin
AgentControlPlane is a local, model-agnostic control plane that lets web AI dispatch compact briefs...
Tokens:40,917
Snippets:385
Trust Score:4.3
License:AGPL-3.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run the live demo with npm.cmd

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/README.md

Clones the repository, installs dependencies, runs the doctor check, and starts the live demo. Requires Node.js 22 or newer and one configured executor; OpenCode is the default demo choice when ready.

```powershell
git clone https://github.com/Ya-KARAS/AgentControlPlane.git
cd AgentControlPlane
npm.cmd ci
npm.cmd run doctor
npm.cmd run demo
```

--------------------------------

### Verify local service with npm commands

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/docs/CHATGPT-CONNECTION.md

Run these commands from the repository to install dependencies, run tests, check the service, and start it. Keep the service on its default loopback address.

```powershell
npm.cmd install
npm.cmd test
npm.cmd run doctor
npm.cmd start
```

--------------------------------

### Dispatch brief for a connected web AI

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/README.md

Example brief for dispatching a task to a connected web AI. It instructs the agent to use the balanced profile and automatic executor selection, implement a tested GET /hello endpoint, verify it, and return changed files plus test evidence. If execution reports a blocker or misunderstanding, the brief should be corrected and the same project continued.

```text
Use the balanced profile and automatic executor selection. Inspect the project,
implement a tested GET /hello endpoint, verify it, and return changed files plus
test evidence. If execution reports a blocker or misunderstanding, correct the
brief and continue the same project.
```

--------------------------------

### Start AgentControlPlane with npm.cmd start

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/docs/BROWSER-COMPANION.md

Run this PowerShell command from the repository directory to start the local control plane before loading the browser companion extension.

```powershell
cd C:\Users\YOUR_USER\Documents\Github\AgentControlPlane
npm.cmd start
```

--------------------------------

### Install ACP from GitHub

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/docs/BETA-ONBOARDING.md

Commands to clone the AgentControlPlane repository and install dependencies. Requires Node.js 22 or newer.

```bash
git clone https://github.com/Ya-KARAS/AgentControlPlane.git
cd AgentControlPlane
npm install
```

--------------------------------

### Configuration: workspaceRoots and projectDiscoveryRoots

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/docs/PROJECT-REGISTRY.md

JSON configuration example showing the backward-compatible list of explicit execution workspaces and the optional list of parent directories for project discovery. Discovery roots are scan-only and never offered as execution workspaces.

```json
{
  "workspaceRoots": [
    "C:\\Users\\YOUR_USER\\Documents\\Github\\AgentControlPlane"
  ],
  "projectDiscoveryRoots": [
    "C:\\Users\\YOUR_USER\\Documents\\Github",
    "D:\\Development"
  ]
}
```

--------------------------------

### First verification prompt (read-only)

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/docs/CHATGPT-CONNECTION.md

Start with a read-only task to list available execution profiles and models without dispatching engineering work.

```text
Use AgentControlPlane to list the available execution profiles and models.
Do not dispatch engineering work yet.
```

--------------------------------

### Live demo success output

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/README.md

Example output from a successful demo run. Shows the executor, task ID, status, created file, verification flag, and the final pass message.

```text
AgentControlPlane live demo
executor: opencode
task: <task-id>
status: completed
file: <workspace>\hello.txt
verified: true
DEMO PASS: MCP dispatch, local execution, file verification, and result persistence completed.
```

--------------------------------

### Example command to describe engineering work

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/userscript/README.md

Use this command in a ChatGPT or DeepSeek conversation to initiate an ACP task. The web AI will discuss the request and prepare a structured task.

```text
@ACP describe the engineering work
```

--------------------------------

### Cost-aware model picker output

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/docs/ROADMAP.md

Example output of the cost-aware model picker interface, showing candidate models with estimated cost, tool verification, reasoning level, and recent p95 latency, along with selection buttons.

```text
Task: Refactor authentication
Recommended models:
  Model A — est. $0.02 · tools verified · reasoning high · recent p95 45s
  Model B — est. $0.01 · tools verified · reasoning low  · recent p95 30s
[Cheapest] [Balanced] [Best]
```

--------------------------------

### Engineering brief JSON example

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/docs/PROTOCOL.md

Example of an engineering brief used to dispatch a task. The 'executor' field can be 'auto', 'opencode', 'codex', 'claude', 'openai-compatible', or 'deepseek'. 'idempotency_key' is optional and accepts 8–200 letters, digits, dots, underscores, colons, or hyphens; reusing it with different content returns 'idempotency_conflict'.

```json
{
  "workspace": "D:\\Projects\\example",
  "idempotency_key": "web:conversation-123:task-4",
  "executor": "auto",
  "objective": "Add a tested GET /hello endpoint.",
  "constraints": ["Do not add a framework dependency."],
  "acceptance_criteria": [
    "GET /hello returns HTTP 200",
    "Response JSON equals {\"message\":\"hello\"}",
    "Automated tests pass"
  ],
  "context": ["The project already uses node:test."],
  "evidence_required": ["test command and result", "changed file list"],
  "profile": "balanced",
  "model": null,
  "reasoning_effort": null,
  "max_subagents": null,
  "token_budget": null
}
```

--------------------------------

### Clone and verify AgentControlPlane locally

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/CONTRIBUTING.md

Clones the repository, installs dependencies with npm.cmd ci, and runs the verify script. Requires Node.js 22 or newer and npm. The verify command runs the same test and syntax checks used by CI.

```powershell
git clone https://github.com/Ya-KARAS/AgentControlPlane.git
cd AgentControlPlane
npm.cmd ci
npm.cmd run verify
```

--------------------------------

### Build release assets

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/docs/RELEASE-CHECKLIST.md

Package the release, generate the demo video, and create the SHA256 checksums for the distribution files.

```powershell
npm.cmd run release:package
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts\create-demo-video.ps1
npm.cmd run release:sha256 -- `
  dist\agent-control-plane-v0.9.0-windows.zip `
  dist\agent-control-plane-browser-companion-v0.9.0.zip `
  dist\agent-control-plane-v0.9.0-demo.mp4 `
  --output dist\SHA256SUMS
```

--------------------------------

### ACP Task XML Example

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/tests/fixtures/companion-harness/index.html

Example of an ACP task payload wrapped in <ACP_TASK> tags, used to send a task to the adapter. The task specifies a workspace, objective, profile, and executor.

```xml
<ACP_TASK>
{"workspace":"DEFAULT","objective":"Create hello.txt","profile":"economy","executor":"auto"}
</ACP_TASK>
```

--------------------------------

### Compact result JSON example

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/docs/PROTOCOL.md

Example of a compact result returned by the web controller. The controller should poll until terminal status; when the result is 'blocked', 'partial', or 'failed', it should use the structured blocker and evidence to correct the brief or explain why user input is required.

```json
{
  "status": "completed",
  "summary": "Implemented and tested the endpoint.",
  "changed_files": ["server.js", "server.test.js"],
  "tests": [{"command": "npm test", "status": "passed"}],
  "blockers": [],
  "next_action": null,
  "usage": {
    "input_tokens": 0,
    "cached_input_tokens": 0,
    "output_tokens": 0,
    "reasoning_output_tokens": 0,
    "total_tokens": 0
  },
  "subagents": []
}
```

--------------------------------

### Release preparation command (PowerShell)

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/userscript/README.md

Run this command to prepare a release. It updates source metadata, rebuilds the stable script and metadata, creates a versioned release file, and writes release-manifest.json with stable URLs and SHA-256 hashes.

```powershell
npm.cmd run userscript:release -- --version 0.9.4
```

--------------------------------

### Build and check commands for userscript

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/userscript/README.md

Run these PowerShell commands after adding an adapter to build the userscript and run checks. The generated installable file is agent-control-plane-web-bridge.user.js.

```powershell
npm.cmd run userscript:build
npm.cmd run userscript:check
```

--------------------------------

### Chat completion with AsterRoute API

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/docs/BETA-ONBOARDING.md

Example curl command to call the AsterRoute chat completions endpoint. Uses the ASTERROUTE_API_KEY environment variable for authorization and sends a simple message requesting 'OK'.

```bash
curl https://asterroute.com/v1/chat/completions \
  -H "Authorization: Bearer $ASTERROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.6-sol-economy","messages":[{"role":"user","content":"Reply with OK"}]}'
```

--------------------------------

### Run mock reroute orchestrator tests

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/docs/DOGFOODING-ROUND-03.md

Runs the mock integration suite for the P1 native cross-executor continuation state machine. The output shows 5 tests, all passing with 0 failures.

```text
node --test tests/reroute-orchestrator.test.js
tests 5
pass 5
fail 0
```

--------------------------------

### Initialize tunnel-client profile

Source: https://github.com/ya-karas/agentcontrolplane/blob/main/docs/CHATGPT-CONNECTION.md

Initialize a named profile for the tunnel-client using the sample for an HTTP MCP server. Set the CONTROL_PLANE_API_KEY environment variable to the runtime key.

```powershell
$env:CONTROL_PLANE_API_KEY = "<runtime key>"
tunnel-client init `
  --sample sample_mcp_http_local `
  --profile agent-control-plane `
  --tunnel-id <tunnel_id> `
  --mcp-server-url http://127.0.0.1:4318/mcp
```
Tokens:
Raw