ecc orchestration: Worktree and Control-Plane Commands

ECC’s orchestration layer spans the ecc control-pane local dashboard, the ecc platform-audit readiness audit, multi-agent worktree scripts, and the security IOC scanner. These tools are aimed at operators running ECC in production multi-agent environments — coordinating parallel workers across git worktrees, monitoring platform health, and enforcing supply-chain integrity.

`ecc control-pane`

Launches the ECC2 operator control pane — a loopback-only HTTP server that serves a real-time dashboard of active sessions, worktree status, skill run metrics, install health, and the JIT work-item board. The server is DNS-rebinding-safe: it validates the Host header against a loopback allowlist and rejects requests from external origins. The binary is also available directly as ecc-control-pane (a named bin alias in package.json).

Usage

ecc control-pane [--host <address>] [--port <port>] [--db <ecc2.db>] \
  [--state-db <state.db>] [--config <ecc2.toml>] [--query <text>] \
  [--read-only] [--no-open]

Flags

--host

string

The local address to bind to. Defaults to 127.0.0.1. Must be a loopback address — the server rejects requests from non-loopback hostnames.

--port

number

TCP port the server listens on. Defaults to 8765.

ecc control-pane --port 9000

--db

string

Path to the ECC2 primary database file. When omitted the default location under the user’s home directory is used.

--state-db

string

Path to the ECC state-store SQLite database (work items, sessions, skill runs). Defaults to the standard home-directory location.

--config

string

Path to an ecc2.toml operator configuration file.

--query

string

Pre-filter sessions displayed in the dashboard by a search query.

--read-only

flag

Disable all action-execution endpoints. The dashboard becomes read-only — useful in shared or CI environments. When not passed, actions are enabled for the local loopback allowlist.

--no-open

flag

Do not automatically open the browser after the server starts (macOS only).

Startup output

ECC Control Pane: http://127.0.0.1:8765
ECC2 database: /Users/you/.ecc/ecc2.db
ECC state database: /Users/you/.ecc/state.db
Actions: enabled for local allowlist

Press Ctrl-C to shut down gracefully.

What the dashboard shows

The control pane renders a live view of:

Active sessions — harness, adapter, state, repo root, worker count, and start time for all sessions currently in active state.
Worktree status — per-worker branch, worktree path, and agent state for multi-agent orchestration plans.
Skill run metrics — success/failure rates and recent run history across the state store window.
Install health — per-target install status, profile, module count, and source version.
JIT work-item board — linked Linear, GitHub, handoff, and manual work items with claim and move actions (when --read-only is not set).
Proximity visualization — an optional graph view of worker relationships (served at /proximity).

Example: start with a custom port

ecc control-pane --port 8765 --state-db ~/.ecc/state.db
# → ECC Control Pane: http://127.0.0.1:8765

The control pane is loopback-only by design. Do not expose it on a non-loopback interface or behind a reverse proxy without additional authentication, as it can execute actions against the local ECC state store.

`ecc platform-audit`

Performs an operator readiness audit across GitHub PR/issue queues, GitHub Discussions, roadmap evidence, release pipeline state, and security signals — surfacing whether the platform is ready to ship or needs attention before cutting a release. The underlying script (scripts/platform-audit.js) checks a configurable list of repositories (defaulting to affaan-m/ECC, affaan-m/agentshield, affaan-m/JARVIS, ECC-Tools/ECC-Tools, and ECC-Tools/ECC-website) and applies configurable pass/fail thresholds.

Usage

ecc platform-audit [--format text|json|markdown] [--write <path>] \
  [--root <dir>] [--repo <owner/repo>] [--skip-github] \
  [--max-open-prs <n>] [--max-open-issues <n>] [--max-dirty-files <n>] \
  [--allow-untracked <path>] [--exit-code]

Flags

--format

string

Output format: text (default), json, or markdown. Aliases --json and --markdown are also accepted.

--write

string

Write JSON or Markdown output to a file. Requires --json or --markdown.

--root

string

Repository root to inspect for local Git state (dirty files, etc.). Defaults to the current working directory.

--repo

string

GitHub repository to audit in owner/repo format. Repeatable. When omitted, the default repository list is used.

ecc platform-audit --repo affaan-m/ECC --repo ECC-Tools/ECC-Tools

--skip-github

flag

Skip live GitHub queue and discussion checks. Only local repository state is inspected.

--max-open-prs

number

Fail when open PR count is above this threshold. Default: 20.

--max-open-issues

number

Fail when open issue count is above this threshold. Default: 20.

--max-dirty-files

number

Fail when blocking dirty file count is above this threshold. Default: 0.

--allow-untracked

string

Ignore untracked files under the given path when evaluating dirty-file thresholds. Repeatable.

ecc platform-audit --allow-untracked docs/drafts/ --allow-untracked tmp/

--use-env-github-token

flag

Pass the GITHUB_TOKEN environment variable through to gh CLI invocations.

--exit-code

flag

Return exit code 2 when the audit is not ready.

Examples

ecc platform-audit

`ecc security-ioc-scan`

Scans dependency manifests (package.json, lockfiles), AI-tool configuration directories, and installed package payload paths for active supply-chain IOC (Indicators of Compromise) signatures. The embedded IOC database covers malicious package name/version combinations sourced from public security advisories.

Usage

ecc security-ioc-scan [--home] [--root <dir>] [--json]

Flags

--home

flag

Scan the user’s home directory AI-tool configuration paths (e.g. ~/.claude/, ~/.opencode/) in addition to the project root.

ecc security-ioc-scan --home

Examples

# Scan the current project
ecc security-ioc-scan

# Also scan home-directory AI-tool configs
ecc security-ioc-scan --home

The IOC database bundled with ecc-universal reflects the supply-chain incidents known at the time of the package release. Keep ecc-universal up-to-date to get the latest IOC signatures.

`ecc uninstall`

Removes all ECC-managed files recorded in install-state for the current context. Reads the install-state to know exactly which files to delete — only ECC-managed paths are touched.

Usage

ecc uninstall [--target <harness>] [--dry-run] [--json]

Flags

--target

string

Limit removal to a specific harness target. Repeatable. When omitted, all discoverable install-state files in the current context are processed.

ecc uninstall --target antigravity

--dry-run

flag

Preview which files would be removed without deleting anything. Always recommended before a full uninstall.

ecc uninstall --target antigravity --dry-run

--json

flag

Emit a machine-readable JSON uninstall result including planned or removed paths and summary counts.

Output format

Uninstall summary:

- claude-global
  Status: OK
  Install-state: /Users/you/.claude/install-state/ecc-install-state.json
  Removed paths: 38

Summary: checked=1, uninstalled=38, errors=0

ecc uninstall permanently removes ECC-managed files. Run with --dry-run first to review what will be deleted. This operation cannot be undone without re-running ecc install.

Orchestration Scripts

In addition to the ecc CLI commands, ecc-universal ships several npm scripts that can be invoked directly for advanced multi-agent orchestration workflows.

`orchestrate:status`

Inspect an orchestration session snapshot or plan file and emit a JSON status object via scripts/orchestration-status.js.

npm run orchestrate:status -- workflow-visual-proof
npm run orchestrate:status -- .claude/plan/workflow-visual-proof.json
npm run orchestrate:status -- .claude/plan/workflow-visual-proof.json --write /tmp/snapshot.json

yarn orchestrate:status workflow-visual-proof

Usage pattern:

node scripts/orchestration-status.js <session-name|plan.json> [--write <output.json>]

`orchestrate:tmux`

Plan and optionally execute a multi-agent tmux worktree orchestration from a plan JSON file (scripts/orchestrate-worktrees.js). Without flags, prints a dry-run plan only.

npm run orchestrate:tmux -- plan.json
npm run orchestrate:tmux -- plan.json --execute
npm run orchestrate:tmux -- plan.json --write-only

The plan JSON supports placeholders in the launcherCommand field:

Placeholder	Value
`{worker_name}`	Human-readable worker label
`{worker_slug}`	Slug-form worker identifier
`{session_name}`	tmux session name
`{repo_root}`	Absolute repository root path
`{worktree_path}`	Absolute worktree path for the worker
`{branch_name}`	Git branch name for the worker
`{task_file}`	Path to the worker task file
`{handoff_file}`	Path to the worker handoff file
`{status_file}`	Path to the worker status file

`dashboard`

Launch the Python-based ECC operator dashboard (ecc_dashboard.py).

npm run dashboard
# or
yarn dashboard

`dashboard:web`

Launch the Node.js web dashboard (scripts/dashboard-web.js).

npm run dashboard:web
# or
yarn dashboard:web

Operator Workflow Example

Start the control pane

Launch the ECC2 control pane server and open the dashboard in your browser.

ecc control-pane --port 8765
# → ECC Control Pane: http://127.0.0.1:8765

Run a platform audit

Before starting a release cycle, confirm the platform is ready across all tracked repositories.

ecc platform-audit --markdown --write reports/platform-audit.md

Inspect orchestration status

Check the current state of an active multi-agent session from the coordination plan.

npm run orchestrate:status -- .claude/plan/my-feature.json

Review loop health

Confirm no workers are stuck in a stale wakeup or pending Bash call.

ecc loop-status --json

Scan for supply-chain IOCs

Before merging or deploying, scan the dependency surface.

ecc security-ioc-scan --home

CLI Reference

Skills Library

Hooks Reference

Configuration

ecc orchestration: Worktree and Control-Plane Commands

`ecc control-pane`

Usage

Flags

Startup output

What the dashboard shows

Example: start with a custom port

`ecc platform-audit`

Usage

Flags

Examples

`ecc security-ioc-scan`

Usage

Flags

Examples

`ecc uninstall`

Usage

Flags

Output format

Orchestration Scripts

`orchestrate:status`

`orchestrate:tmux`

`dashboard`

`dashboard:web`

Operator Workflow Example

Build docs developers (and LLMs) love

CLI Reference

Skills Library

Hooks Reference

Configuration

Documentation Index

​ecc control-pane

​Usage

​Flags

​Startup output

​What the dashboard shows

​Example: start with a custom port

​ecc platform-audit

​Usage

​Flags

​Examples

​ecc security-ioc-scan

​Usage

​Flags

​Examples

​ecc uninstall

​Usage

​Flags

​Output format

​Orchestration Scripts

​orchestrate:status

​orchestrate:tmux

​dashboard

​dashboard:web

​Operator Workflow Example

Build docs developers (and LLMs) love

`ecc control-pane`

Usage

Flags

Startup output

What the dashboard shows

Example: start with a custom port

`ecc platform-audit`

Usage

Flags

Examples

`ecc security-ioc-scan`

Usage

Flags

Examples

`ecc uninstall`

Usage

Flags

Output format

Orchestration Scripts

`orchestrate:status`

`orchestrate:tmux`

`dashboard`

`dashboard:web`

Operator Workflow Example