integrate

ward integrate installs, refreshes, or removes the hooks that run Ward from a coding agent.

ward integrate <agent> [-C <dir>] [--remove | --[no-]guard-approved-specs]

Options

Option	What it does
<agent>	opencode, claude-code, codex, cursor, copilot, gemini, windsurf, cline, factory-droid, or amp. Without it, Ward prompts for a choice.
-C, --directory <dir>	Install for the project in <dir> instead of the current directory.
--remove	Remove the Ward-owned integration files.
--guard-approved-specs	Also install the approved-artifact guard.
--no-guard-approved-specs	Remove only the guard.
--verbose	Print diagnostics to stderr. See Verbose diagnostics.

--remove cannot be combined with either guard option; that is a usage error (exit 2).

How installation works

• Installation is project-local and idempotent. Make sure ward is on PATH.
• Generated files are ownership-marked. Conflicting user-owned files are never overwritten, and removal deletes only Ward-owned files.
• Re-running the command refreshes changed Ward-owned files.
• Claude Code uses ward hook claude-code, OpenCode uses V2 plugins, and the other harnesses use ward hook native --agent <agent>.
• For OpenCode, removal also removes Ward’s OpenCode command.

On success the command prints the status, the integration’s lifecycle capabilities, and each changed file:

CHANGED: Created Ward codex native hook integration.
Capabilities: [APPROVED_ARTIFACT_GUARD, FEEDBACK, POST_EDIT, PRE_TOOL]
.codex/hooks.json
.codex/hooks/ward.sh

The status is one of CHANGED, ALREADY_PRESENT, REMOVED, NOT_FOUND, or CONFLICT.

Capabilities

Capability	Without it
PRE_TOOL	Advisory only: the harness reports failures but cannot block a tool call.
POST_EDIT	No check after each edit.
TURN_END	No check when the agent finishes (Windsurf, Cline).
FEEDBACK	Findings are shown to you but cannot be passed to the agent (Windsurf).
APPROVED_ARTIFACT_GUARD	No guard for approved specs.

Capabilities describe what the generated files are built to do. A successful install does not prove the harness has loaded them. See what each integration delivers.

Claude Code and OpenCode

After each edit, they run the quality check with --exclude-spec and validate edited spec files with spec validate. When the agent finishes a turn, they run the configured spec checks and hand any findings to the agent once per turn. See the Claude Code, OpenCode, and native harness pages for details.

After upgrading Ward

Re-run ward integrate <agent> to refresh Ward-owned files; they are reported as changed.

Caution

For OpenCode, this refresh is V2-only and breaking. Upgrade OpenCode before refreshing, then reload the project or plugin instance and check the active plugin IDs. File presence is not proof that a plugin is active.

Nested projects

For a project below the Git top-level, such as apps/api:

• claude-code and opencode install at the repository root with files named after the project, exactly as ward init does; see monorepos.
• Other agents install one shared hook at the repository root. Running ward integrate from a second project finds it already present, and --remove removes it for every project.

Approved-artifact guard (opt-in)

--guard-approved-specs also installs a pre-tool guard. It runs before the agent edits, patches, deletes, or moves files, runs a shell command, or invokes a skill. The guard calls spec guard and refuses calls that would modify:

• approved OpenSpec specs (openspec/specs/**);
• archived changes (openspec/changes/archive/**).

Active changes under openspec/changes/<change>/ stay editable. Archiving and syncing into approved specs are left to a human.

Command	Guard afterwards
ward integrate <agent> --guard-approved-specs	Installed (or refreshed)
ward integrate <agent>	Unchanged: kept if installed, absent if not
ward integrate <agent> --no-guard-approved-specs	Removed; the rest of the integration stays installed
ward integrate <agent> --remove	Removed together with the rest of the integration

• The guard lives in its own Ward-owned file, so you can see whether it is installed, and it survives refreshes.
• A user-owned file at the guard’s path is reported as a conflict when you pass --guard-approved-specs, and is otherwise left alone.
• Without the option, nothing runs before tool calls. The guard never changes the quality check or spec validation hooks.

See the Claude Code and OpenCode pages for what each agent covers.

Caution

Shell-command filtering is a heuristic, not a security boundary: scripts and other indirect writes are not prevented. See security.

Verbose diagnostics

Use ward --verbose integrate ... or place --verbose after the command. Logs go only to stderr and describe integration decisions and outcomes. Generated files and their contents are not logged.

Exit codes

Code	Meaning
0	Success.
2	A conflict or invalid usage: Ward could not complete the operation.