Documentation

Set up in 30 seconds

npx agentsteer

Framework Integration

npx agentsteer

npx agentsteer install claude-code

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{ "type": "command", "command": "npx -y agentsteer@latest install-binary" }]
    }],
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "node ~/.agentsteer/hook.js hook" }]
    }]
  },
  "env": {
    "AGENT_STEER_OPENROUTER_API_KEY": "sk-or-v1-your-key-here"
  }
}

Deploy to Your Team

Option 1: Managed deployment (Claude Code)

Deploy a managed-settings.json file system-wide. Developers need zero setup. Hooks auto-bootstrap on first Claude Code session. See the Claude Code settings reference and managed settings docs.

allowManagedHooksOnly: true prevents developers from adding their own hooks. Env vars in the env block are injected into every Claude Code session.

Local mode (data stays on device)

Each tool call is scored on the developer's machine. No data goes through AgentSteer servers. Replace the env key with any supported provider (e.g. AGENT_STEER_ANTHROPIC_API_KEY, AGENT_STEER_BEDROCK_BEARER_TOKEN).

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{ "type": "command", "command": "npx -y agentsteer@latest install-binary" }]
    }],
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "node ~/.agentsteer/hook.js hook" }]
    }]
  },
  "env": {
    "AGENT_STEER_OPENROUTER_API_KEY": "sk-or-v1-your-org-key",
    "AGENT_STEER_MODE": "local"
  },
  "allowManagedHooksOnly": true
}

Generate via CLI: npx agentsteer org-setup --mode local --key sk-or-v1-your-org-key

Cloud mode (centralized dashboard)

Scoring via AgentSteer API. View all sessions, blocked actions, and risk patterns on the dashboard. API key stays server-side.

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{ "type": "command", "command": "npx -y agentsteer@latest install-binary" }]
    }],
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "node ~/.agentsteer/hook.js hook" }]
    }]
  },
  "env": {
    "AGENT_STEER_TOKEN": "org-token-from-dashboard",
    "AGENT_STEER_API_URL": "https://api.agentsteer.ai",
    "AGENT_STEER_MODE": "cloud"
  },
  "allowManagedHooksOnly": true
}

Generate via CLI: npx agentsteer org-setup --mode cloud --token your-org-token

Deploy paths

# Linux
sudo mkdir -p /etc/claude-code
sudo cp managed-settings.json /etc/claude-code/managed-settings.json

# macOS
sudo mkdir -p "/Library/Application Support/ClaudeCode"
sudo cp managed-settings.json "/Library/Application Support/ClaudeCode/managed-settings.json"

Or use the dashboard org page to generate and download the config interactively.

Option 2: Team members join

npx agentsteer --org ORG_TOKEN

Connects the developer's machine to your org and installs hooks automatically for all detected frameworks.

Option 3: Individual setup

Each developer runs the interactive quickstart. Or copy a provider config from the Supported Providers section directly into ~/.claude/settings.json (for personal use) or into managed-settings.json (for org-wide deployment).

npx agentsteer

Supported Providers

AgentSteer works with 6 LLM providers for scoring. Pick any one — the hook auto-detects the provider from your API key prefix. No CLI needed: copy the config into ~/.claude/settings.json and you're done.

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{ "type": "command", "command": "npx -y agentsteer@latest install-binary" }]
    }],
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "node ~/.agentsteer/hook.js hook" }]
    }]
  },
  "env": {
    "AGENT_STEER_OPENROUTER_API_KEY": "sk-or-v1-your-key-here"
  }
}

Custom model

Add AGENT_STEER_MONITOR_MODEL to the env block to override the default scoring model:

"env": {
  "AGENT_STEER_OPENROUTER_API_KEY": "sk-or-v1-...",
  "AGENT_STEER_MONITOR_MODEL": "anthropic/claude-haiku-4-5-20251001"
}

Local vs Cloud Mode

Switch anytime with agentsteer mode local or agentsteer mode cloud. Hooks stay the same — only the scoring backend changes.

Cloud BYOK (Bring Your Own Key)

In cloud mode, you can use your own API key instead of AgentSteer credits. Go to Account Settings and paste any supported provider key. Scoring runs server-side using your key — you only pay your provider directly.

Supported BYOK keys: OpenRouter (sk-or-), Anthropic (sk-ant-), OpenAI (sk-), Google (AI), Groq (gsk_), AWS Bedrock (ABSK).

How It Works

Security Policy

The monitor evaluates each action on two dimensions: whether it aligns with the user's intent (P1-P4 policies), and whether it poses risk requiring explicit approval (R1-R8 risk categories including exfiltration, data destruction, credential access, and more).

View the full security policy on GitHub

Configuration

CLI Reference

Claude Code Setup Guide

Claude Code uses a PreToolUse hook system that lets external programs inspect and approve every tool call before execution.

How the hook works

When Claude Code is about to execute a tool (Bash, Write, Edit, Read, etc.), it calls the AgentSteer hook with the tool name and parameters. The hook scores the action and returns either "approve" or "block" with a reason.

Settings file location

~/.claude/settings.json

The hook is installed globally and applies to all Claude Code sessions across all repositories.

OpenHands Setup Guide

OpenHands supports the same PreToolUse hook format via a hooks.json configuration file.

Configuration file

~/.openhands/hooks.json

How task detection works

The monitor automatically detects the task from conversation context. For Claude Code, it reads the transcript. For OpenHands, it captures user messages via hook events. No manual configuration needed.

Where does my data go?

Your source code stays on your machine. AgentSteer only sends tool call metadata (tool name, parameters, task description) for scoring.

• Cloud mode (default): Metadata is sent to the AgentSteer API, which scores it via your OpenRouter key (BYOK). API keys and secrets are stripped before scoring.
• Local mode: Run npx agentsteer --local with your own OpenRouter key. Scoring happens on your machine via OpenRouter. No data goes through AgentSteer servers.

What happens if scoring is unavailable?

If the AI scorer is unavailable (missing credentials, server down, API error, or unparseable response), AgentSteer switches to degraded-mode fallback rules: pattern-based safety checks that block known dangerous operations (curl, rm -rf, writing to .env, sudo, etc.) while allowing safe ones (reads, greps, task management). Every action in degraded mode shows a warning with instructions to restore full AI scoring.

Custom Monitor Model

By default, AgentSteer uses a specialized security model for scoring. You can override it with any OpenRouter model — for example, to use a cheaper/faster model like Claude Haiku.

Option 1: Environment variable

export AGENT_STEER_MONITOR_MODEL=anthropic/claude-haiku-4-5-20251001

Set this in your shell profile (~/.bashrc, ~/.zshrc) to persist across sessions.

Option 2: Config file (persistent)

echo '{"monitorModel": "anthropic/claude-haiku-4-5-20251001"}' > ~/.agentsteer/config.json

Option 3: Org deployment

Add AGENT_STEER_MONITOR_MODEL to the env block in your managed-settings.json:

"env": {
  "AGENT_STEER_MODE": "local",
  "AGENT_STEER_OPENROUTER_API_KEY": "sk-or-v1-...",
  "AGENT_STEER_MONITOR_MODEL": "anthropic/claude-haiku-4-5-20251001"
}

Resolution order

First non-empty value wins:

1. AGENT_STEER_MONITOR_MODEL environment variable
2. monitorModel in ~/.agentsteer/config.json
3. Default: openai/gpt-oss-safeguard-20b

Troubleshooting

Hook not firing

Check that the hook is installed correctly:

agentsteer status

This shows your current configuration, whether the hook is installed, and tests the connection to the scoring service.

False positives (legitimate actions blocked)

If the monitor is blocking actions that should be allowed, you can:

• Make sure your project has a CLAUDE.md with clear task context
• Adjust the threshold: export AGENT_STEER_THRESHOLD=0.90
• Enable debug logging: export AGENT_STEER_DEBUG=1

Debug logging

export AGENT_STEER_DEBUG=1
# Logs are written to ~/.agentsteer/debug.log

Connection issues

If you see connection errors:

• Check your internet connection
• Verify your token is valid: agentsteer status
• For local mode, verify your key: agentsteer key status openrouter

Reinstalling

npx agentsteer@latest