// bring your own AI harness

Agent Integrations

Give Claude Code, Codex, or OpenCode both halves of effective Hovel operation: typed access to the running framework through MCP, and the official Hovel skills that teach the agent how to use that access deliberately. One Hovel command installs the version-matched integration for a user or a project.

Quickstart

Install the Hovel CLI, initialize or enter a Hovel workspace, and install the integration for the harness you use. User scope is the default.

pipx install hovel

# choose one host
hovel agent install claude
hovel agent install codex
hovel agent install opencode

Restart or open a fresh agent session after installation so the host can discover its new plugin, skills, and MCP server. Then begin with a read-only request:

Use Hovel to inspect the current workspace and operation.
Summarize the active chain, targets, validation state, and anything
that requires operator attention. Do not modify state or start a throw.

Hovel installs all specialized skills as one product. You do not install chain-building, throwing, payload, or session skills separately; the host discovers the right skill on demand.

Install for one project

Use project scope when the integration should travel with a repository or when you do not want to change user-level agent configuration. Run the command from the project root:

hovel agent install claude --scope project
hovel agent install codex --scope project
hovel agent install opencode --scope project

Preview either scope before making filesystem changes or invoking a native host package manager:

hovel agent install codex --scope project --dry-run

What gets installed

The integration intentionally separates capability from operating knowledge. The running Hovel server remains the source of truth for schemas and current state; static skills contain durable strategy and safety guidance.

Skills do not duplicate MCP JSON schemas or hard-code module catalogs. They instruct the agent to inspect the live catalog and workspace before acting, which keeps the guidance useful as modules and provider capabilities evolve. See MCP and Agent Operation for the complete protocol, tool surface, and parity contract.

The skill suite

Host-specific installation

The command-line interface is stable across hosts, but Hovel uses each harness's native distribution mechanism where one is available. Configuration files are merged rather than replaced.

Claude Code

hovel agent install claude
# or
hovel agent install claude --scope project

Hovel asks the Claude CLI to add the version-pinned Hovel marketplace and install hovel@vibepwners-hovel. The plugin contains the complete skill suite and the command-based MCP definition. If you prefer to use the Claude package manager directly:

claude plugin marketplace add vibepwners/hovel@v0.4.3 --scope user
claude plugin install hovel@vibepwners-hovel --scope user

Codex

hovel agent install codex
# repository-local portable skills and MCP config
hovel agent install codex --scope project

User scope downloads the Codex archive, verifies it, caches its marketplace, and invokes the native Codex plugin manager. Project scope uses the portable Agent Skills layout because Codex plugin management is user-scoped. It adds only the Hovel MCP section to an existing .codex/config.toml and preserves unrelated settings and comments.

OpenCode

hovel agent install opencode
# repository-local skills and opencode.json entry
hovel agent install opencode --scope project

Hovel installs standard skills directly into OpenCode's discovery path and adds the Hovel MCP server to opencode.json. The merge accepts JSON-with-comments and trailing commas, retains existing plugins and MCP servers, and leaves an identical Hovel entry unchanged.

Your first agent workflow

Start with a workspace already usable from the Hovel CLI. The agent and human interfaces attach to the same daemon-owned operation, so you can inspect or continue the work from either interface.

1. Open the agent host in the directory containing your Hovel workspace.
2. Ask for a read-only workspace and catalog snapshot.
3. Name the intended operation, target, and outcome. Tell the agent whether it may modify chain state.
4. Ask it to validate and show the exact plan without starting execution.
5. Review targets, modules, configuration, risk flags, and required approvals yourself.
6. Authorize confirmation or execution explicitly only when the plan is correct.

A useful chain-building request is concrete about the stopping point:

Use Hovel to find the mock survey module and prepare a chain for
mock://target-1 in the current operation. Inspect the module before adding it,
fill only the required configuration, validate the chain, and show me the
result. Do not plan or start a throw.

For an existing session, make it equally clear that execution is not needed:

Use Hovel to list the existing sessions, inspect the most recent shell
session, and summarize its context and unread output. Do not create a throw
and do not write to the session.

Execution and safety

A valid chain is not an approved throw. Official skills teach the agent to preserve Hovel's multi-stage execution state machine:

validate
   ↓
create persisted plan
   ↓
review exact targets, modules, configuration, risk, and plan hash
   ↓
record confirmation for that plan
   ↓
satisfy launch-key and dangerous-module policy
   ↓
start
   ↓
observe status, logs, events, sessions, and artifacts

Keep human intent explicit in prompts. “Validate and show me the plan,” “stop before confirmation,” and “do not write to the session” establish useful boundaries, but enforcement remains in Hovel rather than relying on prompt compliance. Read Safety and Scope Guardrails for the complete trust model.

Versions, upgrades, and offline installation

By default, the installer selects the exact version of the running Hovel binary. Published Codex and OpenCode archives are fetched from the matching GitHub release and verified against its SHA256SUMS. The package manifest must also name the requested host and version.

# inspect what a different published version would do
hovel agent install codex --version 0.4.3 --dry-run

# install that published version
hovel agent install codex --version 0.4.3

Upgrade Hovel first, then rerun the same installation command. Identical content is idempotent. If an existing Hovel-managed skill or configuration differs, installation stops rather than silently overwriting local work. Inspect the difference before choosing --force.

Local and offline sources

--source accepts an unpacked host package or a previously downloaded .tar.gz. The package manifest supplies and validates its version, so --source and --version are mutually exclusive.

hovel agent install opencode \
  --source ./hovel-agent-opencode-v0.4.3.tar.gz

hovel agent install codex \
  --scope project \
  --source ./unpacked-hovel-codex

Archive extraction rejects path traversal and symbolic links. Network downloads are size-limited, checksum-verified, and cached under the user's Hovel agent cache for repeat installation.

Troubleshooting

The agent cannot see Hovel skills or tools

Restart the host, confirm you installed at the intended scope, and run the install command again with --dry-run. For project scope, launch the host from that project. Also verify that hovel is available to the host process.

The installer reports a conflicting skill or MCP entry

Hovel found non-identical existing content and refused to destroy it. Compare the existing path with the packaged version. If replacement is intentional, rerun with --force. Replaced files receive a neighboring .hovel-backup copy.

Claude or Codex reports that its native command is unavailable

Install that host's CLI and ensure it is available on PATH. Hovel deliberately delegates user-scoped plugin registration to the host instead of editing private package-manager state.

A published archive or checksum cannot be downloaded

Confirm that the Hovel version has a corresponding GitHub release. Use --source with a trusted local archive for disconnected environments.

The agent keeps using stale Hovel state

Ask it to reload the Hovel discovery or troubleshooting skill and take fresh catalog and workspace snapshots. Do not work around stale state with the generic command escape hatch.

A throw is waiting for approval

Inspect the pending throw and its missing approver identities. Launch-key policy intentionally waits for the live entities captured by the pending plan; it is not an installer failure.

Package and trust details

Every host artifact contains a hovel-agent.json manifest with the package name, exact Hovel version, and intended host. The release also publishes one SHA256SUMS file covering all three archives.

dist/agent/
├── hovel-agent-claude-v0.4.3.tar.gz
├── hovel-agent-codex-v0.4.3.tar.gz
├── hovel-agent-opencode-v0.4.3.tar.gz
└── SHA256SUMS

Canonical content exists once under agent/skills/. Packaging generates host-native layouts from that source, so fixes to safety or workflow guidance cannot drift independently between hosts.

Packaging and release development

Contributors should edit canonical skills, packaging code, or manifests—not generated archives. Run the agent scope while iterating and the full gate before considering a repository-wide change complete:

aspect hovel-check agent
aspect hovel-release agent

# full repository definition of done
aspect hovel-check

aspect hovel-release agent materializes deterministic packages under dist/agent/. The release updater synchronizes Hovel's version into the Claude manifest and skill compatibility metadata. CI validates the portable skill format, safety invariants, expected skill inventory, archive structure, absence of links and traversal entries, and reproducible bytes.

Release tags publish the three archives and checksum manifest together. This keeps the Hovel executable, its typed MCP behavior, and its official agent operating guidance on one release train.