agent-governance-toolkit

What you will run into

When multiple AI sessions (or several collaborators in a team) work in the same environment, who constrains them? Nobody checks before running commands, nobody reviews compliance before opening a PR, and accountability only happens after something goes wrong. agent-governance-toolkit (CLI name agt) is that "gate": policy enforcement, compliance verification (OWASP ASI), zero-trust identity and execution sandboxing, so agent actions go through a check before they happen. It is a pip meta package — installing one main package brings a set of governance subpackages; after install use agt doctor for a health check, agt lint-policy for policy file format, agt verify for compliance. When to use it:

• Multi-session / multi-agent collaboration where you want unified rules for "what is allowed, what is not";
• Adding a compliance check before actions like opening PRs or running commands;
• A health check of your agent environment (agt doctor) and policy files (agt lint-policy).

When not to use it: single machine, single session, quick scripts — the governance layer is itself overhead; without multi-agent collaboration you do not need the gate.

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

agt is a pip meta package — installing the main package brings a set of governance subpackages (agent-os-kernel / agentmesh-platform / agent-runtime / agent-sre etc.). The core is a CLI (agt) with subcommands: verify (compliance), doctor (health diagnostics), lint-policy (policy file checks), test, integrity, red-team, cred (zero-trust identity). Three install forms (capabilities low to high):

• Method A: pip install the main package, CLI surface only (verified here);
• Method B: pip install the [full] extras bundle, all capabilities (not tested);
• Method C: Claude Code plugin marketplace install, IDE plugin surface (not tested, needs Claude Code login).

Where it writes: the CLI form writes no user config (verified no ~/.claude.json write); only method C plugin form writes the plugin registration surface in ~/.claude.json.

Step by step

Step 1: Install the main package

Why: agent-governance-toolkit on PyPI is a meta package; pip installs the CLI with base dependencies, touches no system config and starts no background process — the lowest-effort, cleanest-to-uninstall path. Verified on mainland networks: PyPI official ~12.7s vs Tsinghua mirror ~16s, comparable; if you switch between campus network and proxy, try both branches and use whichever works.

pip install agent-governance-toolkit
agt --version

Expected output: agt, version 4.1.0 Domestic acceleration branch (pick either one, commands are equivalent):

pip install agent-governance-toolkit --index-url https://pypi.tuna.tsinghua.edu.cn/simple
agt --version

Expected output: agt, version 4.1.0 After install, confirm:

• agt --version prints agt, version 4.1.0;
• agt --help shows the subcommand list (verify/doctor/lint-policy/test/integrity/red-team/cred).

Stuck? How to recover:

• agt command not found → check Python >= 3.10 and that pip and python share the same environment (activate the venv before installing and using);
• pip timeout → use the domestic branch command above (--index-url https://pypi.tuna.tsinghua.edu.cn/simple);
• missing deps after install → reinstall the main package first rather than adding deps one by one (the meta package declares the full dependency set).

Step 2: Health check + run the first governance action

Why: two things right after install — agt doctor checks that the install is complete; then create a policy directory (a policies/ folder at the project root for your policy files) and use agt lint-policy to check policy file format. This is the first step of the governance loop: get the "check policies" capability in place first, then hook it into CI or a pre-PR gate later.

agt doctor

Expected output: AGT Doctor starts, lists installed packages and config paths

agt lint-policy ./policies

Expected output: No issues found. (reports errors line by line if there are format issues) After install, confirm:

• doctor lists installed packages with no red missing items;
• lint-policy prints No issues found. for an empty policy dir / valid policy files.

Stuck? How to recover:

• ./policies does not exist → run mkdir -p policies first (lint-policy checks policy files in the directory);
• verify says policies not configured → normal: agt verify gives guidance prompts when policies are not configured; add policy files first, then verify.

How to confirm it works

Three steps confirm the CLI path end to end:

agt --version

Expected output: agt, version 4.1.0

agt doctor

Expected output: AGT Doctor starts, lists installed packages and config paths (no red missing items)

agt lint-policy ./policies

Expected output: No issues found. (reports errors line by line if there are format issues)

• version OK + doctor without missing items + lint-policy runs = installed and the governance path works;
• after policies are configured, agt verify produces compliance results = the gate can be hooked into CI.

Other environments

• [full] extras bundle (method B): all capabilities but many packages; uninstall must remove subpackages one by one (see uninstall section), not tested.
• Claude Code plugin form (method C): registration surface in ~/.claude.json, needs a logged-in environment, not tested.
• With oh-my-claudecode: CLI forms verified coexisting (local repro log); plugin-form registration surfaces not tested → possible-conflict.
• venv scenarios: pip and python must be the same environment; activate the venv before installing and using.

Daily usage

Startup and entry

agt has no resident process; call the CLI when needed. Entry is agt --help, subcommands are the feature list.

Common operations

Operation 1: View the command list

agt --help

Expected output: starts with Usage: agt [OPTIONS] COMMAND [ARGS]..., includes verify/doctor/lint-policy/test/integrity/red-team/cred Operation 2: Install health diagnostics (run first after environment changes/upgrades)

agt doctor

Expected output: AGT Doctor starts, lists installed packages and config paths Operation 3: Policy file check (governance core, verified here)

agt lint-policy ./policies

Expected output: No issues found. (reports errors line by line if there are format issues) Operation 4: Compliance verification (OWASP ASI, run after policies are configured)

agt verify

Expected output: compliance check results (gives guidance prompts when policies are not configured)

Data and directories

• CLI form: no dedicated data directory; config follows the pip environment (inside the venv in venv scenarios);
• Method C plugin form: registration surface in ~/.claude.json.

Uninstall & cleanup

note: Match install exactly: methods A/B uninstall via pip (method B also removes each subpackage); method C runs /plugin remove inside Claude Code; the last line verifies zero residue

pip uninstall -y agent-governance-toolkit || true
command -v agt >/dev/null 2>&1 && echo "agt 仍存在（方式 C 安装请执行 /plugin remove agent-governance-toolkit）" || echo "agt removed: OK"

Expected output: agt removed: OK Method B residue cleanup (subpackages from [full] extras):

pip uninstall -y agent-os-kernel agentmesh-platform agent-runtime agent-sre agentmesh-marketplace agentmesh-lightning agent-hypervisor

Dependency warnings

• Version: [4.1.0, 4.1.0] locked to a single version (meta package form; upgrades need re-verification of the subpackage set).
• Environment: Python >= 3.10; pip and python must share the same environment (activate the venv first in venv scenarios).
• Network: PyPI official / Tsinghua mirror both work (verified, comparable speed); overseas direct environments can use the default command.
• Co-install: with oh-my-claudecode CLI form verified coexisting (local repro log); plugin-form registration surface (~/.claude.json) not tested → possible-conflict.
• Write surface: CLI form zero write surface; plugin form writes ~/.claude.json.

FAQ

• Q: agt command not found after install? A: check Python >= 3.10 and the pip install path (activate the venv first in venv scenarios); on mainland networks use the method A domestic branch command from the install section.
• Q: [full] installed a pile of packages, how to uninstall? A: pip uninstall the main package, then continue removing subpackages (agent-os-kernel / agentmesh-platform / agent-runtime / agent-sre / agentmesh-marketplace / agentmesh-lightning / agent-hypervisor), or follow the upstream docs.
• Q: Can it be installed alongside oh-my-claudecode? A: CLI mode verified coexisting (no interference, see local repro log); both Claude Code plugin-form registration surfaces (~/.claude.json) not tested, currently judged possible-conflict.
• Q: Where to report problems? A: install/uninstall issues on this marketplace go through the entry feedback channel (usage-report template); project issues go to the author's repository.