Help us improve
Share bugs, ideas, or general feedback.
From aming-claw
Launches and verifies Aming Claw locally: preview dashboard, start governance, check health, and run one-shot installs.
npx claudepluginhub amingclawdev/aming-claw --plugin aming-clawHow this skill is triggered — by the user, by Claude, or both
Slash command
/aming-claw:aming-claw-launcherThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Help the user start and verify Aming Claw locally. Default mode is show-the-command-and-wait — never spawn governance silently. Switch to one-shot mode only when the user explicitly invokes it (see [One-Shot Install Mode](#one-shot-install-mode) below).
Governs Aming Claw projects with graph-first discovery, backlog tracking, and MCP operations. Enforces commit trailers and post-commit checks for governance.
Exposes the DashClaw platform's routes, schema, and env vars via snapshot and live queries. Use for integration, troubleshooting, and governance — prefers `python -m livingcode query` or REST fallback.
Answers OpenClaw questions on configuration, troubleshooting, setup, architecture, features, channels, gateway, automation, models, and design decisions using clawdocs and openclaw CLIs.
Share bugs, ideas, or general feedback.
Help the user start and verify Aming Claw locally. Default mode is show-the-command-and-wait — never spawn governance silently. Switch to one-shot mode only when the user explicitly invokes it (see One-Shot Install Mode below).
Write the local launcher artifact:
aming-claw launcher
Writes .aming-claw/aming-claw-launcher.html with the dashboard link and start commands. Add --open-browser to open it in the default browser, or --governance-url <url> to target a non-default host. The launcher never starts services on its own.
Start governance in the foreground from a separate terminal/window (host-owned, no plugin-spawned workers):
aming-claw start
This checks GOVERNANCE_PORT from --port (default 40000) first. If
Aming Claw governance is already healthy, it prints the dashboard URL and
exits. If another process owns the port, it reports a conflict. Otherwise it
runs start_governance.main as a long-running foreground service; do not run
that path as a normal one-shot Codex tool call and wait for it to exit.
ServiceManager/executor are advanced chain/ops surfaces and are not part of
the V1 first-run path.
Confirm health (CLI):
aming-claw status
aming-claw plugin doctor --python <path-to-python-3.9-or-newer>
Or, when MCP is available, prefer structured probes for a richer snapshot:
runtime_status(project_id="<project_id>") - core governance/version state, with optional chain/ops readiness reported separately.version_check — HEAD vs CHAIN_VERSION + dirty files.graph_status — active graph snapshot + stale check + semantic drift summary.health — bare governance ping.Check local AI runtime readiness for the selected project before promising AI Enrich work:
GET /api/projects/{project_id}/ai-config.tool_health.openai, tool_health.anthropic,
project_config.ai.routing, semantic.use_ai_default, and
model_catalog.openai maps to the local Codex CLI command codex; CODEX_BIN may
override the path.anthropic maps to the local Claude Code CLI command claude;
CLAUDE_BIN may override the path.Suggested status copy:
Codex CLI: detected at <path>, version <version>, auth unknown.
Claude CLI: detected at <path>, version <version>, auth unknown.
Semantic route: <provider/model or unset>.
AI Enrich: ready / blocked because <reason>.
Open the dashboard:
aming-claw open
Default URL: http://localhost:40000/dashboard. The root path / is not
the dashboard and may return 404 without meaning governance failed.
Governance serves the dashboard from packaged static assets. No build is
needed when agent/governance/dashboard_dist/index.html or
frontend/dashboard/dist/index.html already exists. In a raw checkout with
missing assets, run:
cd frontend/dashboard
npm install
npm run build
If /api/health is OK but /dashboard returns 503, report dashboard
static assets as missing instead of reporting governance as down.
Plugin aftercare:
aming-claw start only starts the governance service. It does not prove that
the current Codex thread loaded the plugin. After installing or updating the
plugin, tell the user to reload Codex or open a new Codex session, then
verify that the Aming Claw skill and mcp__aming_claw tools are visible.
A reload only addresses current-session hot loading. If codex exec reports
failed to load plugin, plugin is not installed, or invalid marketplace
paths, run aming-claw plugin install and aming-claw plugin doctor first;
do not present reload as the primary fix.
Treat ServiceManager/executor as advanced chain/ops readiness, not as
dashboard or governance health.
Starting governance or opening the dashboard does not register the current
workspace. If GET /api/projects is empty or does not include the active
workspace, ask before bootstrap unless the user explicitly requested
initialize/register/bootstrap.
HN demo is the safe exception. If the user asks to try, preview, or run the HN
demo and there is no registered target project, do not ask them for a
project_id and do not bootstrap their current app. From the Aming Claw plugin
checkout, run:
node frontend/dashboard/scripts/e2e-hn-demo.mjs --ensure-fixture --no-browser
That command creates an isolated fixture project under the OS temp directory,
bootstraps it through governance as aming-claw-hn-demo, and verifies that the
fixture starts with an active graph plus empty backlog/timeline. It does not
seed demo backlog rows, timeline evidence, or fabricated graph trace ids. The
runner is included in the plugin payload, so the first-run --no-browser path
does not require a dashboard npm install.
For a full launch rehearsal, run the repeatable sandbox audit:
node frontend/dashboard/scripts/e2e-hn-demo.mjs --sandbox-audit --no-browser
That mode adds install/package smoke checks, creates a run-specific fixture
project, drives the before/during/after demo through real governance calls, and
writes docs/hn-demo/audits/latest.md plus latest.json. Use --browser only
when dashboard screenshots are needed; the default no-browser path is the
fastest onboarding gate.
For true Codex and Claude Code one-click install E2E, use Docker so the host's already-installed plugin state cannot create a false pass:
docker/hn-install-audit/run-install-audit.sh --host both
The Docker lanes mount host auth read-only at runtime and label the result
AUTH_REUSED_FROM_HOST. They do not bake tokens into images or count local
package smoke as an install pass.
Use governance on port 40000, not the ServiceManager sidecar on 40101:
POST http://127.0.0.1:40000/api/project/bootstrap
For explicit bootstrap, infer the project id from the folder name and use common
excludes such as node_modules, dist, build, .expo, .next, and
coverage. Before calling bootstrap, inspect the target root or ask the user
to confirm the dashboard exclude-path field: project-specific generated,
vendored, nested, or tool-owned directories such as node, vendor,
generated clients, fixture clones, scratch worktrees, or downloaded assets
should be added before graph build. Source-controlled projects can keep the
same rule in graph.exclude_paths, graph.ignore_globs, or
graph.nested_projects. When bootstrapping from an AI session instead of the
dashboard form, surface this as an explicit visible reminder before calling the
bootstrap API/CLI, and include the reviewed exclude list in the bootstrap
request. Bootstrap builds a commit-bound graph; if the workspace is a dirty git
repo, ask the user to commit/stash first.
The Aming Claw repo itself can use aming-claw://seed-graph-summary as packaged
MVP navigation when no active aming-claw graph exists. That is not an install
failure. Target/user projects need a registered active graph before graph-backed
claims are available.
agent/cli.py)| Command | Purpose |
|---|---|
aming-claw init | Write .aming-claw.yaml in the current directory. |
aming-claw bootstrap --path <dir> --name <id> | Register an external project under governance. |
aming-claw scan --path <dir> --project-id <id> | Scan an external project into a .aming-claw candidate workspace. |
aming-claw start --port 40000 [--workspace <runtime-root>] | Start governance in the foreground from a separate terminal/window. By default the runtime root is the plugin checkout/package root, not the current target project. |
aming-claw status | GET /api/health against the running governance service. |
aming-claw plugin doctor [--plugin-root <dir>] [--python <python3.9+>] | Run read-only V1 aftercare checks for plugin assets, generated marketplace, versioned Codex plugin cache, MCP config, Codex config hints, Python runtime, dashboard assets, AI CLI probes, and governance health. Add --check-service-manager only for advanced chain/ops checks. |
aming-claw open --governance-url <url> | Open the dashboard in the default browser. |
aming-claw launcher [--open-browser] [--output path] | Write the launcher HTML artifact. |
aming-claw plugin install <git-url> | Clone/update a user-local plugin checkout, validate Codex/Claude manifests, optionally pip-install the runtime, install Codex cache/config, and print next steps. |
aming-claw plugin update --check|--apply [<git-url>] | Check a Git-backed plugin checkout for updates, apply fast-forward updates, refresh install surfaces, and write local restart/reload obligations. |
aming-claw backlog export|import --project-id <id> | Move local backlog rows between machines with portable JSON, dry-run, and explicit conflict handling. Plugin updates do not sync backlog DB state. |
aming-claw mf precommit-check [--plugin-state <json>] | Run local manual-fix pre-commit guards, including plugin update/restart state blockers. |
aming-claw run-executor | Start an executor worker directly for advanced chain debugging only. Not used by the V1 dashboard/graph/backlog/Review Queue path. |
.mcp.json at the Aming Claw plugin/repo root, stdio entrypoint python -m agent.mcp.server --project aming-claw --workers 0 --governance-url http://localhost:40000. Do not copy that file into an external target project; a target-local .mcp.json with --project aming-claw is install/startup pollution. Plugin sessions keep --workers 0; V1 semantic jobs are drained by the governance in-process semantic worker..claude-plugin/plugin.json. It is namespaced as /aming-claw:aming-claw-launcher. (Note: CLAUDE.md at repo root is workspace project rules — loaded by Claude Code when the repo is opened as a workspace, not part of plugin context; plugin-time guidance lives in this skill.)If governance is offline or this is a fresh install:
If the user asks only to install from a Git URL, prefer the host-native plugin flow first. This is install-only; do not start governance or open the dashboard unless the prompt also contains an explicit one-shot trigger:
Install the Aming Claw plugin from https://github.com/amingclawdev/aming-claw
If the host cannot install Git plugins directly yet, ask the user to clone once and run:
git clone https://github.com/amingclawdev/aming-claw.git
cd aming-claw
pip install -e .
Then ask the user to start governance in a separate terminal/window:
cd aming-claw
python -m agent.cli start
Then run:
python -m agent.cli plugin doctor --plugin-root . --python python
If the CLI is already available, use:
aming-claw plugin install https://github.com/amingclawdev/aming-claw
aming-claw plugin doctor
Read aming-claw://seed-graph-summary (packaged MVP structure) when the MCP resource is available — do not invent module locations.
Show the explicit startup flow rather than auto-running it inline:
aming-claw launcher
aming-claw start
Make clear that aming-claw start only exits immediately when governance is
already healthy or the port is conflicting. When it starts governance, it is
long-running and should stay open in its own terminal; the assistant should
return to status checks instead of waiting for the command to exit.
After plugin install, tell the user to reload Codex/open a new session. The
current thread may not hot-load newly installed skills or MCP tools.
For Claude Code, plugin install loads skills only; it does not install the
Python runtime, start governance, prove MCP visibility in the current
session, or validate CLI auth. If the sandbox blocks a remote installer
script, prefer an explicit git clone plus local marketplace install.
After the user starts services, re-run runtime_status and confirm version_check.ok == true before recommending any mutation.
Use the main aming-claw skill (skills/aming-claw/SKILL.md) for:
Default behavior is "show the command and wait." Switch to one-shot mode only when the user's prompt contains an explicit completion trigger:
When triggered, run the bootstrap with tool calls instead of showing commands to the user:
Install plugin (marketplace + cache). Try Claude Code slash commands first:
/plugin marketplace add <git-url>/plugin install <plugin-name>@<marketplace-id> (typically
aming-claw@aming-claw-local)/plugin is a CLI-harness slash command, not a tool. If the assistant gets
"tool not available", "slash commands cannot be invoked from a tool", or
similar errors, do NOT ask the user to type the slash commands. Fall
back to manual replication — /plugin only does file-level work that the
assistant can do too:
a. git clone --depth=1 <git-url> ~/.claude/plugins/marketplaces/<marketplace-id>/
(Windows path: %USERPROFILE%\.claude\plugins\marketplaces\<marketplace-id>\).
b. Read .claude-plugin/marketplace.json from the clone to get the plugin
name and version (currently aming-claw / 0.1.1).
c. Copy the marketplace clone into the plugin cache and drop .git:
mkdir -p ~/.claude/plugins/cache/<marketplace-id>/<plugin>/ &&
cp -R ~/.claude/plugins/marketplaces/<marketplace-id> ~/.claude/plugins/cache/<marketplace-id>/<plugin>/<version> &&
rm -rf ~/.claude/plugins/cache/<marketplace-id>/<plugin>/<version>/.git.
On Windows use New-Item -ItemType Directory -Force + Copy-Item -Recurse +
Remove-Item -Recurse -Force.
d. Merge (do not overwrite) an entry into
~/.claude/plugins/installed_plugins.json for
"<plugin>@<marketplace-id>":
{"scope": "user", "installPath": "<abs path to cache .../<version>/>",
"version": "<version>", "installedAt": "<ISO-8601 UTC now>",
"lastUpdated": "<ISO-8601 UTC now>",
"gitCommitSha": "<marketplace HEAD sha>"}.
e. Merge an entry into ~/.claude/plugins/known_marketplaces.json for
<marketplace-id>:
{"source": {"source": "github", "repo": "<owner>/<repo>"},
"installLocation": "<abs path to marketplaces/<marketplace-id>>",
"lastUpdated": "<ISO-8601 UTC now>"}.
Install Python runtime. Run pip install -e <abs path to marketplace clone>. If aming-claw is already on PATH, prefer aming-claw plugin install <git-url> — that wraps pip install + marketplace refresh +
versioned Codex cache in one call.
Start governance in the background — aming-claw start is long-running
and will block the foreground tool call:
Start-Process powershell -ArgumentList "-NoExit","-Command","aming-claw start".nohup aming-claw start > ~/.aming-claw/start.log 2>&1 &.Poll aming-claw status (or GET http://localhost:40000/api/health) for
up to ~30 seconds until governance reports healthy on port 40000.
Open the dashboard. Run aming-claw open.
Announce the new-session requirement. Do not phrase this as "reload and then it works" — the dashboard works now in the current session, but skills and MCP tools require a new session. Say something close to:
"Plugin is installed. The dashboard works now. To use Aming Claw skills and MCP tools inside Claude Code conversations, open a new Claude Code session."
Do not enter one-shot mode when:
aming-claw open.aming-claw start as a separate-terminal command and wait for the user.aming-claw start as plugin verification. Use
aming-claw plugin doctor and a new Codex session visibility check.aming-claw start with docker compose up or raw python -m agent.governance.server unless the user is explicitly debugging.governance.db, the version chain, or graph state from launcher flows — those go through the main aming-claw skill.