Harness plugins

Auwai ships one generated plugin architecture for Claude Code, Codex, Hermes, and OpenCode. The capability contract is extensions/plugin_common/capabilities.json; the bundles are generated by make plugins from the shared skill, commands, agent, hook policy, and MCP server. Host adapters only translate file names and lifecycle payloads.

The knowledge service is the default workflow for every plugin: pull shared facts before planning and sync findings and coverage after reading.

Architecture

The host bundles differ in file layout and lifecycle hooks. They share the skill, command text, agent text, MCP tools, hook decisions, and capability contract.

Contract version: 1.0.0. MCP tools: 17. Required features: 10.

What "identical" means

All four bundles contain:

• the same canonical Auwai skill and scripts;
• the same five commands: auwai-status, auwai-plan, auwai-read, auwai-sync, and auwai-coverage;
• the same auwai-reader agent text;
• the same 17 MCP tools and schemas;
• the same session nudge, raw-read guard, and stop-sync decisions;
• the same knowledge-service pull/sync contract and session environment (AUWAI_SESSION_ID, AUWAI_AGENT_ID, AUWAI_KNOWLEDGE_TOKEN);
• the same version and capability manifest.

Host-specific install layout and UI may differ. Behavior may not.

Install

The unified installer supports --scope user|project, --check, --remove, and --dry-run:

python3 scripts/install_plugin.py --harness claude --scope user --dry-run
python3 scripts/install_plugin.py --harness codex --scope user
python3 scripts/install_plugin.py --harness hermes --scope user
python3 scripts/install_plugin.py --harness opencode --scope project

Claude Code and Codex delegate to their plugin CLIs and use the local marketplace in this repository. Their plugin managers install at user scope, so pass --scope user; the installer rejects project scope for those two hosts. Hermes copies the native plugin and registers the MCP server. OpenCode copies the plugin directory, skill, commands, and agent into .opencode, then registers the MCP server.

Hook trust and enforcement

Claude Code loads the plugin hook automatically.

Codex requires plugin hooks to be reviewed and trusted. Open /hooks, review the Auwai hook source, and trust it. Until then Codex skips the hook; this is a host trust policy, not an advisory-only guard. The hook path is hooks/hooks.json, which Codex 0.166 discovers for enabled plugins.

Hermes uses the native plugin in interactive and gateway sessions and the shell hook bridge in one-shot mode. The bridge installs pre_tool_call, pre_llm_call, and post_llm_call hooks.

OpenCode loads auwai-guard.js through its V2 plugin API. It translates tool.execute.before, prompt admission, and session idle events into the same shared Python hook used by the other hosts.

Knowledge service default

Set the service in the project or user config:

[knowledge]
mode = "team"
url = "http://127.0.0.1:8765"
repo_id = "github.com/acme/telemetry"
token_env = "AUWAI_KNOWLEDGE_TOKEN"

The skill instructs the agent to run:

auwai sync --pull
# route, plan, begin, read
auwai sync

Claude Code

claude plugin validate extensions/claude-code/plugins/auwai --strict
claude plugin marketplace add "$PWD/extensions/claude-code"
claude plugin install auwai@auwai-native

Codex

codex plugin marketplace add "$PWD/extensions/codex"
codex plugin add auwai@auwai-native
codex plugin list
codex mcp list

Hermes

The native plugin and the shell-hook bridge are documented in extensions/hermes/auwai-hermes/README.md. In one-shot mode, install the shell hooks; in interactive and gateway sessions, the native plugin is loaded.

OpenCode

The plugin, MCP installer, and guard are documented in extensions/opencode/README.md. The same shared bundle includes the skill, commands, and reader agent.

Model endpoints

The plugin surfaces are independent of the model endpoint. Claude Code needs an Anthropic-compatible endpoint; Codex needs the Responses API; OpenCode supports OpenAI-compatible and Anthropic-compatible endpoints; Hermes supports its configured providers. A local model server is enough for development. See local benchmark replication.

Related pages

• Install
• Security
• Knowledge service
• Release readiness