agent-steer

agent-steer

Real-time behavioral steering for Claude Code agents. Detects drift, thrashing, and regression using free deterministic signals — then injects corrective context to get the agent back on track. Zero additional LLM cost.

What it does

When an AI coding agent starts repeating failed approaches, editing the same file without testing, or forgetting earlier discoveries, agent-steer detects it and steers the agent back:

• PostToolUse — Collects behavioral signals from every tool execution (exit codes, edit patterns, test gaps, recovery rates) and surfaces structured context (test counts, error details, repetition alerts)
• Scoring — Dual EWMA (fast/slow) with self-tuning thresholds based on measured injection effectiveness
• PreToolUse — Injects concise corrective context when scoring detects problems; Thompson Sampling selects the best injection type
• PreCompact — Preserves high-value context during compression, removes noise
• SessionStart — Injects learned patterns from past sessions
• Web Dashboard — Real-time monitoring at localhost:7433 with score timeline, signal heatmap, and file graph
• Statusline — Compact score display in the Claude Code UI via bridge file

All signals are deterministic and free. No external API calls. No model training. The "policy update" happens through context manipulation — the model reads different information and makes different decisions.

Install

# Clone and build
git clone https://github.com/sust4in/agentsteer.git
cd agentsteer
npm install
cd ui && npm install && cd ..
npm run build:all    # Builds daemon + hooks + skills + dashboard

Load for development/testing

# Run Claude Code with the plugin loaded from disk
claude --plugin-dir /path/to/agentsteer

Install permanently

From inside a Claude Code session:

/plugin install /path/to/agentsteer

To scope to a specific project:

/plugin install /path/to/agentsteer --scope project

Web Dashboard

When the daemon is running, a real-time dashboard is available at http://localhost:7433.

Pages:

• Overview — Reactivity (fast EWMA) and Trend (slow EWMA) gauges, momentum, streak status, recent activity feed
• Timeline — Score chart over time with threshold lines at 0.4 (warning) and 0.7 (good)
• Signals — Per-signal breakdown cards with sparkline history: repetition, untested edits, test gap, session length, recovery rate, adaptation
• Injections — Log of all behavioral nudges fired (warnings, recoveries, criticals)
• Graph — Force-directed file dependency graph colored by score

The dashboard auto-refreshes via polling and receives live events via Server-Sent Events (SSE). No additional dependencies — served by the daemon using node:http.

Multi-session support: All data pages support ?session=<id> for viewing past sessions. A session picker appears in the header when 2+ sessions exist.

To build the dashboard:

cd ui && npm install && npm run build && cd ..

For development with hot reload:

npm run ui:dev    # SvelteKit dev server on :5173, proxies API to :7433

Statusline Integration

Agent-steer writes a bridge file (/tmp/agent-steer-<session>.json) on each PostToolUse with current score, step count, and health. A statusline script reads this to display a compact status in the Claude Code UI:

steer [impl] ████░░░░ 0.65 s12 ↯2

Phase indicator (e.g. [impl]) shown when scoring.phaseAware is enabled and confidence > 0.5.

Add to Claude Code settings.json:

{
  "statusLine": {
    "type": "command",
    "command": "node \"/path/to/agentsteer/scripts/statusline.js\""
  }
}

Plugin Skills

Interactive commands available inside Claude Code sessions:

Command	Description
/agent-steer:status	Daemon health, EWMA scores, session progress
/agent-steer:signals	Recent step signals in tabular format
/agent-steer:patterns	Learned behavioral patterns with confidence
/agent-steer:summary	Session overview with scoring trajectory
/agent-steer:config	View/modify scoring and injection config
/agent-steer:reset	Clear session data and restart daemon

How it works

Tool call -> PostToolUse hook -> Signal extraction -> Phase detection -> Behavioral scoring -> SQLite persist
                              -> PostToolUse context (test counts, errors, repetition alerts)
                                                         |
Next tool call -> PreToolUse hook <- Injection decision <- EWMA drift detection
                                 <- Thompson Sampling   <- Effectiveness tracking (ITS)
                                 <- PPR file context    <- Dependency graph
                                 <- Learned patterns    <- Cross-session learning