Agent integration

SCAR treats AI agents as first-class users: they trigger scars, they read scars, and they author scars (into candidates/, behind the human promotion gate).

Claude Code (reference integration)

Recommended: install the plugin from the marketplace — hooks and the scar-authoring skill arrive together.

Manual fallback:

scar hook install     # PreToolUse injection + PostToolUse violation tripwire
scar hook status
scar skill install    # authoring skill into ~/.claude/skills/

How the hook behaves:

• PreToolUse on Edit|Write|MultiEdit|NotebookEdit: resolves the target path, runs scar inject --path <target> --top-k 3, and emits ranked scars as additionalContext. Advisory — never blocks the tool call.
• PreToolUse on Bash: fires command-anchored scars against the shell command about to execute (scar inject --command "<cmd>" is the same surface for other runtimes) — the injection path for run-a-command mistakes that edit anchors cannot cover.
• PostToolUse: runs any armed violation: regex against the edit just made and logs fired→violated events.
• Everything is installed only by explicit command; scar hook uninstall removes it cleanly.

After upgrading scar-cli, re-run scar skill install — the installed skill is a static copy and does not update itself.

Windsurf / Cascade (block-once injection)

Cascade runs shell commands on lifecycle events, configured per workspace in a committable .windsurf/hooks.json:

scar hook install --runtime windsurf     # run inside the repo
scar hook status --runtime windsurf

This wires pre_write_code and pre_run_command (injection) plus post_write_code (the violation: tripwire) to scar cascade-hook. An existing hooks.json is merged, never overwritten — your team's own hooks keep their place and run first.

Why blocking. Cascade has no additionalContext equivalent: on exit 0 stdout reaches the Cascade UI only, never the model. The one channel into the agent's context is a blocking exit, which surfaces stderr and cancels the pending action. So a firing scar bounces the action once:

1. The agent is about to write code (or run a command) that an armed scar anchors. The action is cancelled and the scar arrives on stderr, compact — label line plus the one rule that matters.
2. The agent retries the identical action. This time it goes straight through, informed.

Exactly one bounced action per firing, scoped to the Cascade conversation. Retries are never blocked twice; the state expires on its own, since Cascade gives no session-end signal to clean up on.

Precision bar is deliberately higher here than in Claude Code. A false firing there spends tokens; here it cancels something the user can see. So only content-signal matches block — the pattern hit the pending edit, the symbol resolved, or the command is the recorded mistake. Path-proximity matches print a one-liner to the UI for the human and never block anything.

Firings and violations land in the same log scar stats reads, tagged with the runtime that produced them.

Known no-op: Cascade does not load hooks while a workspace is open in Restricted Mode. Install still succeeds; the hooks simply never run there.

For pull access as well, Windsurf speaks MCP — see below.

MCP server (any MCP-capable agent)

scar mcp

A dependency-free stdio server speaking newline-delimited JSON per the MCP spec. It exposes:

Tool	What it does
scar_query	Ranked scars for paths, content, or a unified diff
scar_why	Full scar history anchored to a path
scar_draft	Write a candidate scar — only ever to .scars/candidates/

Config snippets for supported hosts:

scar agent doctor
scar agent config codex      # or: cursor, windsurf, opencode

Every other runtime: git-native

No hook API? scar draft-check runs from a plain git hook and nudges any agent (or human) toward authoring, driven entirely by git evidence — revert language in commit messages, actual git revert/reset --hard history, churn:

scar hook install --git      # writes .git/hooks/post-commit

Throttled to one nudge per hour per repo, advisory only, always exits 0. And scar agent skill prints the full authoring contract as text for pasting into any runtime's instructions.

Orchestrators and sub-agents

Sub-agents launch in fresh contexts: edit-anchored scars reach them (the hook fires inside their session), but process-level knowledge — command traps, workflow rules — only arrives if the launch prompt carries it. scar brief --compact makes that mechanical:

scar brief --compact --paths src/payments/ --max-chars 1500

One tight line per scar, severity-ordered, byte-capped, plain text with omissions reported (never silent). Command-anchored scars are always included — they are precisely the ones the edit hook cannot deliver. Orchestrator pattern: run it with the files the sub-agent will touch, prepend the block to the launch prompt.

CI

scar check src/ --exit-code                   # gate on firing scars
scar check --diff changes.patch --exit-code   # gate on violation: tripwires against a diff
scar lint                                     # format, dead tripwires, overdue reviews, rot

Advisory by default everywhere; CI opts into strictness explicitly.

Machine-readable docs

Agents reading these docs programmatically: fetch /llms.txt for a plain-text index of every page with stable URLs, plus the changelog.