Documentation
Shield docsGet started

Your first Shield project

Set up a project policy, connect Claude Code or Codex, and inspect an agent request. For an overview of the concepts, read What is Shield?.

Before you begin

You need the shield command on your path and an interactive terminal. If you are building from the Canonic checkout, the local installer is:

make -C packages/shield install-local

The installer puts shield in ~/.local/bin; add that directory to your PATH. See development for build details. Native setup uses Unix command hooks and refuses Windows setup. macOS is the verified native platform.

Open a terminal in your project. Default setup downloads a signed baseline pack from Shield’s main registry, so you need network access.

1. Initialize the project

From the project directory, run:

shield init

Shield asks you to choose a profile for the baseline, its default pack of permission rules. Recommended is preselected. A profile selects the pack’s decisions; it does not change your agent’s sandbox.

At the agent selection, use Space to mark the agents to configure, then Enter to continue. Agents whose commands are on your path are preselected. Enter with none marked skips agent setup; you can add it later.

Review the packs, agent settings, and Shield binary path, then confirm. Shield saves the active policy and creates .shield/ for policy files and private review state. Cancel leaves the project unchanged; a failed baseline download or verification leaves a new project unenrolled.

For a first setup with a different baseline profile, use shield init --profile strict. To start without adding the default baseline, use shield init --no-baseline. An empty policy returns Ask for unmatched requests.

2. Load the agent integration

If you selected an agent during initialization, its registrations are already installed. To add one later, choose the command for your agent:

shield mcp setup --agent claude
shield mcp setup --agent codex

Each command installs hooks and MCP tools for that agent after review, keeping any other selected agent registered.

Restart the agent after setup. Trust the project, enable hooks, and approve the MCP connection as the host requires. In Codex, also review the hook definitions through /hooks.

Codex: new setups let valid Ask requests proceed by default, even with the Strict profile. Saved choices are preserved; Deny and protection failures still block. Check this fallback in the review. See Ask handling.

Hooks check supported tool requests. MCP lets the agent inspect policy, read guides, and propose changes. Check that both load in the restarted agent.

3. Inspect the result

Run these from the same project:

shield status
shield doctor

Check that status names the right project and lists your packs and agents. doctor adds diagnostic checks and recovery commands. Resolve any reported repair before continuing. Both report installation state; live interception remains unverified.

To inspect the rules themselves, use:

shield rule list --json

JSON output includes full identifiers and structured details.

4. Inspect an agent request

Continue your ordinary work in the restarted agent. When Shield records a request, you can inspect it in the terminal:

shield history list

Copy an entry ID from the list and use it in place of ENTRY:

shield history show ENTRY

Find a command the agent submitted. The detail view shows its decision, matching rules, and any reported completion. A decision alone does not show that execution finished. If history is empty, follow integration troubleshooting.

Where to go next

Read policy decisions to understand the result of a request. Then find a permission pack or write a custom rule for your project’s needs. Agents can use Shield’s MCP tools to inspect policy and prepare changes for your review.