What It Does
Not a runtime—a declaration shell. Four lifecycle hooks, six delegated skills, zero dependencies.
Four lifecycle hooks handle codebase pre-indexing, structured handoff on session end, context preservation before compaction, and rate-limit recovery. Six auto-installed skills teach the host to delegate entire tasks—semantic search, structural analysis, spec generation, code review, auditing, and benchmarking—to SubQ's 12M-token context engine.
Install in one command:
subq CLI) in your PATH. If SubQ isn't installed, SessionStart returns a remediation message; other hooks silently no-op.
Lifecycle Hooks
Each hook invokes subq hooks --provider claude --event <event>. The SubQ CLI forwards the event payload to the local server, which normalizes it and routes to the appropriate handler.
SessionStart
Pre-indexes the codebase, injects a structural overview into the session. Bash wrapper detects SubQ availability.
45s timeout
Stop
Records session-end observation, generates structured handoff. 3-minute cooldown per session.
30s timeout
PreCompact
Builds a structured handoff before Claude Code's lossy compaction so critical context survives.
120s timeout
StopFailure
Detects rate limits (429) and API outages (503/529), advises switching to SubQ's backend.
10s timeout
Delegated Skills
Skills teach the host to delegate entire tasks. Claude Code's Read/Grep/Glob remain available for simple lookups—skills handle the conceptual, cross-file queries where SubQ's context window advantage is clearest.
AUTO / USER
/subq-search
LLM-powered codebase search—find code by meaning, not just text.
AUTO / USER
/subq-context-pack
Structural analysis—directory trees, function signatures, context packs.
USER
/subq-spec
Implementation specification generation with interactive interview.
USER
/subq-review
Code review for uncommitted changes across the full codebase.
USER
/subq-audit
Codebase quality audit—complexity, testing gaps, security.
USER
/subq-bench
A/B token and cost comparison between SubQ and Claude Code.
Cross-Provider Support
The --provider flag is the key abstraction. Claude Code, Codex CLI, and Gemini CLI all converge on the same four capability surfaces.
Quick Start
Three steps from zero to integrated.
claude plugin add subquadratic-ai/subq-utility-plugin
subq doctor — confirms hooks firing, skills discovered, provider wired
/subq-* commands.
Glossary
- DECLARATION SHELL
- A plugin that declares which lifecycle events trigger which commands, but contains no executable logic. All hook handlers live in the SubQ CLI monorepo.
- HOOK ENVELOPE
- The stable JSON wrapper the CLI adds around provider-native stdin payloads before forwarding to the server. Seven fields:
schemaVersion,provider,event,providerRef,projectPath,receivedAt, andpayload. - OBSERVE / REPLACE
- The two hook decisions. Observe records the event silently (non-blocking). Replace injects content into the provider's context (blocking).
- DEGRADATION
- Graceful fallback when SubQ CLI is absent. SessionStart surfaces an install message; other hooks return
{}silently. Exit code is always 0. - DELEGATION
- Skills teach the host AI to hand off entire tasks to SubQ's context engine. Cross-file conceptual queries go to SubQ; single-file lookups stay in the host.
- PROVIDER ADAPTER
- A thin layer in the SubQ CLI that translates between a specific AI coding agent (Claude, Codex, Gemini) and the unified hook/skill interface. Same handlers, different wiring.