Documentation

Everything you need to integrate AgentSteer into your AI agent framework.

Quick Start

Install the package

pip install agentsteer

Run quickstart

agentsteer quickstart

This opens your browser to sign in (Google, GitHub, or email/password), installs the hook globally for all repos, and verifies the connection.

You're done

Every Claude Code session is now monitored. View your sessions at agentsteer sessions or on the web dashboard.

Local mode: If you prefer to bring your own OpenRouter API key instead of using the cloud service, run agentsteer quickstart --local.

Framework Integration

Option A: Quickstart (recommended)

agentsteer quickstart

This signs you in, installs the PreToolUse hook to ~/.claude/settings.json, and verifies the connection. Works across all repos globally.

Option B: Install hook only

agentsteer install claude-code

Option C: Manual setup

Add to your ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "python3 -m agentsteer.hooks.claude_code"
      }]
    }]
  }
}

How it works: Every tool call (Bash, Write, Edit, etc.) is scored against the task description. If the score exceeds 0.80 (highly suspicious), the tool call is blocked. The agent sees the block reason and continues normally.

Organizations

For teams, an admin creates an organization and shares the org token. Members join with a single command.

Create an organization

# Create org with optional domain whitelist
agentsteer org create "Acme Corp" --domains acme.com
agentsteer org create "Acme Corp" --domains acme.com --require-oauth

The --domains flag restricts membership to specific email domains. The --require-oauth flag disables email/password login for the org.

Team members join via browser

agentsteer quickstart --org ORG_TOKEN

Automated mass deployment (no browser)

# Non-interactive: uses machine hostname as user identity
agentsteer quickstart --org-token ORG_TOKEN --auto

For system administrators deploying across many machines. No browser interaction required.

Admin commands

agentsteer org members    # List all org members
agentsteer org sessions   # View all sessions across the org

Evaluation Results

Tested on AgentDojo workspace suite with prompt injection attacks. Monitor blocks 100% of attacks on Claude Code and 95% on OpenHands.

Framework	Model	Condition	Attack Success	Utility	Eval
Claude Code	Haiku 4.5	No monitor (n=20)	100%	5%	view
Claude Code	Haiku 4.5	With monitor (n=20)	0%	55%	view
OpenHands	Haiku 4.5	No monitor (n=5)	60%	0%	view
OpenHands	Haiku 4.5	With monitor (n=20)	5%	75%	view

How It Works

1. Intercept

Hook captures every tool call before execution (file writes, commands, API calls)

2. Score

A security model scores the action against the task description (0 = safe, 0.9 = malicious)

3. Decide

Score >= 0.80 = block the action. Agent sees the block reason and continues its main task.

4 Security Policies

Policy	What it catches	Example
P1: Read-only	Task says read but agent writes	Task: "summarize files" / Action: delete file
P2: Delegation	Agent follows external instructions	Task delegates to URL/email with hidden instructions
P3: Category mismatch	Wrong type of action	Task: "edit code" / Action: send email
P4: Target mismatch	Right action, wrong target	Task: "email alice@co" / Action: email eve@evil

Configuration

Variable	Default	Description
`OPENROUTER_API_KEY`	cloud mode: not needed	Only required for local mode
`SECURE_ENV_TASK`	auto-detected	Override task description for scoring context
`SECURE_ENV_THRESHOLD`	0.80	Score threshold for blocking (0-1)
`SECURE_ENV_DEBUG`	unset	Enable debug logging to ~/.agentsteer/

CLI Reference

Command	Description
`agentsteer quickstart`	One-command setup: login + install hook + test
`agentsteer login`	Sign in via browser (Google/GitHub/email)
`agentsteer status`	Show current config and connection status
`agentsteer sessions`	List all cloud sessions
`agentsteer install <framework>`	Install hook (claude-code, openhands)
`agentsteer org create <name>`	Create an organization
`agentsteer org members`	List org members
`agentsteer org sessions`	View all sessions in the org
`agentsteer score <task> <action>`	Score a single action
`agentsteer report`	Open local dashboard
`agentsteer version`	Print version