Scopey

Scopey is a lightweight Rust CLI tool built to keep AI coding-agent sessions on track. It monitors sessions from Claude Code, Codex, Grok, Pi, and OpenCode, turning user prompts into a live scope definition and checking agent activity against it. The project is pre-1.0 software released under the MIT license by ArchAstro.

What It Is

Scopey sits between you and your coding agent by hooking into the agent's event lifecycle — capturing user prompts, tool calls, and session stops. It extracts a "current scope" from your prompts, periodically judges whether the agent's trajectory matches that scope, and injects corrections or reminders when drift is detected. The core idea is that your latest prompt is the authoritative statement of intent, not an ever-growing union of everything you've ever said.

How the Scope Tracking Works

Scopey installs hooks into each supported agent harness and processes three key events:

• UserPromptSubmit — appends the prompt to the session and triggers a background summarize job to update the scope
• PostToolUse / PostToolBatch — increments tool counts, injects scope reminders every M tools, and schedules a background judge every N tools
• Stop — injects any pending correction before the session ends

Scope extraction is intentionally current-state: additions and modifications preserve unaffected requirements, while explicit removals, contradictions, and replacements win. Questions add a read-only obligation without becoming new implementation authorization. Machine-generated task notifications are treated as context, not new user goals.

Subagent Awareness

By default (ignore_subagents = true), Scopey tracks only the conversation between the user and the top-level agent, ignoring subagent and child-agent sessions entirely. Each supported harness has a specific detection mechanism — Claude Code uses the agent_id field in hook input, Codex uses the same two fields for multi-agent collaboration spawns, and Pi and OpenCode filter at the extension/plugin layer before invoking the binary. Generic markers like a truthy subagent field, a non-empty parent_session_id, or SCOPEY_SUBAGENT=1 in the environment are also honored.

Session Insights and Logs

The scopey insights command turns stored judgement history into a cross-session drift report, sorting off-track sessions first and including scope, evaluated tool windows, attention rate, and the judge's explanation. Filtering supports date ranges, harness, verdict, working directory, and session ID. Hooks and background jobs append structured JSONL logs under ~/.scopey/logs/<session_id>.jsonl, with a scopey logs command for pretty-printing, tailing, filtering by level or event type, and following live output.

Harness and Integration Support

Scopey installs hooks for five coding agents via scopey setup:

• Claude Code — ~/.claude/settings.json
• Codex — ~/.codex/hooks.json
• Grok — ~/.grok/hooks/scopey.json
• Pi — ~/.pi/agent/extensions/scopey.ts
• OpenCode — ~/.config/opencode/plugins/scopey.js

It also integrates with Herdr, an agent multiplexer, to route notifications through Herdr's toast system and report pane state (e.g., marking a pane as blocked when a session goes off-track).

Update: Scopey v0.1.3

The latest release is v0.1.3, published on 2026-08-03. The repository was created on 2026-07-31 and has already accumulated over 100 stars on GitHub. The project is explicitly pre-1.0, with config and session formats designed to remain compatible but potentially still evolving before the first stable release. Installation is available via Homebrew (brew install ArchAstro/tools/scopey) or from source using Cargo or the provided Makefile.