instinctkit

The survival kit for self-learning Claude Code setups — a starter instincts library plus the production guardrails that keep long agent sessions from silently failing.

npx instinctkit install          # everything: guards + stall-shield + seeds
npx instinctkit install --only guards,stall-shield   # no Sinapsis? no problem
npx instinctkit doctor           # verify every piece is installed and wired

Why

Self-learning Claude Code setups (Sinapsis, fs-cortex) start empty: it takes weeks of real sessions before the first learned rules crystallize. And while you wait, long agentic sessions fail in silence — subagents stall with nobody watching, tool calls hang for 50+ minutes, files get edited on assumption instead of evidence.

instinctkit attacks both problems with parts that earned their place in months of daily production use:

• Seeds kill the cold-start: seven curated, stack-aware instincts (Supabase RLS, Stripe webhooks, Playwright selectors, security headers…) imported straight into your Sinapsis index, each one already leveled by confidence.
• Guards kill the silent failures. Every guard below exists because of a real incident, not a hypothesis.

Each guard ships with a kill-switch env var, fails open on its own errors (a broken guard must never block your session), and is a dependency-free Node script — no jq, no python, no Git Bash.

Who this is for (and who it isn't)

Harnesses that don't already do this for you. Agent runners differ wildly in what they enforce: Cursor, custom agent loops built on the SDK, older CLI versions, and self-built orchestrators generally have none of these protections. That's the target.

Recent Claude Code is the notable exception: it already enforces read-before-edit at the tool layer, so k1-anti-assumption is redundant there — install it only if you're on an older version or a different harness. Check what your harness already does before adding a guard: a guard that duplicates the runtime is pure overhead, and doctor cannot tell you that. The other three modules have no built-in equivalent I'm aware of in any harness.

The guards

foreground-guard — PreToolUse [Agent]

Blocks foreground delegation of non-trivial tasks (prompt ≥ 800 chars). Origin incident: a planner subagent delegated in foreground stalled for 8 minutes — foreground blocks the parent, so nobody was left watching. Also enforces a skills budget: when the skills injected by the target agent's frontmatter exceed 25KB, the spawn is blocked — oversized system prompts kill the stream at startup (observed at 90KB; 23 stalls in 24h dying at spawn). Background briefs over 5000 chars get a non-blocking "split this" warning.

Kill-switches: AGENT_FOREGROUND_GUARD_DISABLED=1, AGENT_SKILLS_BUDGET_DISABLED=1, budget override AGENT_SKILLS_BUDGET=<bytes>.

Assumptions it depends on (check these hold in your setup, or the guard silently does nothing):

• Agent tool calls carry prompt and run_in_background in tool_input.
• The skills-budget half additionally assumes agents are defined as <claude-dir>/agents/<subagent_type>.md with a skills: list in YAML frontmatter, and skills as <claude-dir>/skills/<name>/SKILL.md. If your harness doesn't inject skills through agent frontmatter, that half is inert by design — the length gate still works.
• Its value assumes foreground delegation is possible and sometimes chosen. If your setup already spawns every subagent in the background, this guard has nothing to catch.

k1-anti-assumption — PreToolUse [Edit|Write|MultiEdit]

Blocks edits to files that exist on disk but were never Read in the current session — editing on assumption produces wrong diffs (Karpathy's Think Before Coding, enforced in code). Creation of new files always passes; any partial Read counts; Reads by subagents count too (their JSONLs are scanned recursively, workflow agents included). Every uncertainty fails open.

Kill-switch: KARPATHY_K1_DISABLED=1. Metrics: <claude-dir>/.k1-blocks.log.

orchestrator-watch — PreToolUse (every tool)

Watches the JSONLs of your delegated subagents and injects a system-reminder when one is stalled, so the orchestrating model acts instead of waiting forever. Two detectors: mtime (no progress for 10 minutes) and orphan tool_use (a tool_use whose tool_result never arrived — a runtime bug observed 44 times in 14 days — caught after 90 seconds instead of 10 minutes). Three false-positive filters, each bought with a real incident: a clean end_turn tombstone never alerts, a subagent abandoned by its parent never alerts, and alerts dedup per task within 15 minutes.

stall-shield — settings.json env layer

Three documented timeout env vars added to your settings (existing values always win): CLAUDE_STREAM_IDLE_TIMEOUT_MS=300000, MCP_TIMEOUT=120000, BASH_DEFAULT_TIMEOUT_MS=120000. Against tool calls observed hanging 50+ minutes with no timeout at all.

The seeds

Seven starter instincts in seeds/instincts/*.yaml, imported into <claude-dir>/skills/_instincts-index.json when Sinapsis is present (and skipped with a friendly note when it is not — the guards work standalone):

| Seed | Domain (as imported) | Level | |---|---|---| | conventional-commits | operations | permanent | | supabase-rls-auth-uid | database | confirmed | | service-role-cross-user | security | confirmed | | stripe-webhook-verify | stripe | confirmed | | security-headers-vercel | security | confirmed | | e2e-playwright-selectors | quality | confirmed | | nextjs-suspense-boundary | frontend | confirmed |

The Domain column shows the value actually stored after import — Sinapsis's activator pre-filters by domain, so some raw seed domains are translated to the ones it evaluates (e.g. workflow-general → operations); the original is preserved in original_domain.

Import is idempotent (re-runs skip existing IDs), maps confidence to Sinapsis's discrete levels (≥0.90 permanent · ≥0.70 confirmed · else draft), and translates seed domains to the ones Sinapsis's activator evaluates. --skip and --force-draft flags available through the library API.

Install & verify

npx instinctkit install [--only guards,stall-shield,seeds] [--project] [--dry-run]
npx instinctkit doctor [--project]
npx instinctkit list

Machine-wide or per-project

By default the install targets your machine-wide config (~/.claude). Pass --project to target the repo you are standing in (./.claude) instead: guards land in .claude/instinctkit/guards/ and the hook commands are written as $CLAUDE_PROJECT_DIR-relative paths, so the resulting settings.json is safe to commit — it works on every clone, and on Windows and WSL alike (an absolute path would only be valid on the machine that ran the install).

Per-project is the right scope when a guard matters for one codebase, or when you want to try one without touching a global config you are keeping lean. Seeds are skipped in project scope: they live in the machine-wide index.

The installer never touches settings.json without writing a timestamped backup next to it first, never overwrites an existing env value, never duplicates a hook, and prints every change it makes. Restart your Claude Code session after installing so hooks load.

Using a settings guardian / integrity checker? Install writes to settings.json, so re-baseline it afterwards like you would for any intentional settings change.

What it costs (measured, not guessed)

A hook runs on every tool call, so "how much does this slow me down" is the first fair question. Measured on this machine (Node 24, WSL2, 5 runs averaged, one process spawn per measurement):

| | ms per tool call | |---|---| | Floor: any Node hook at all (spawn + read stdin, no logic) | 25 | | foreground-guard (non-Agent call → immediate exit) | 36 | | k1-anti-assumption (non-edit call → immediate exit) | 35 | | orchestrator-watch, active session (3–30 subagents, 0.1–16 MB of logs) | 33 | | orchestrator-watch, when a subagent is stalled (16 MB of logs) | ~150 |

Two things matter more than the absolute numbers:

The guards are O(1) in session size. orchestrator-watch costs the same whether the session has 3 subagents or 30, 100 KB of logs or 16 MB, because it decides from stat alone whether a read could possibly matter and skips otherwise. (It did not always: before this was measured, it slurped every subagent JSONL in full on every tool call. The benchmark is why the guard is fast, so it ships with the numbers.) Only a genuinely stalled subagent triggers a read, and even then only the last 512 KB.

Where you install matters more than the guard. The same guards cost 80–100 ms per call when installed on a Windows drive accessed through WSL (/mnt/d/...) versus 33–36 ms on a native filesystem — the penalty is module loading over 9p, not the guard's work. Install into a native-filesystem ~/.claude, not a mounted one.

Reproduce with your own numbers: the scenarios are synthetic JSONL trees; see docs/benchmark.md.

Honest limitations

• The guards read Claude Code's session JSONL layout (projects/<hash>/<session>.jsonl + subagents/). If the harness changes that layout, detection degrades to fail-open (never blocking) — doctor and the logs tell you if a guard went quiet.
• Thresholds (800 chars, 25KB, 10 min) are the values that survived months of tuning against false positives — but they are my workloads' values. All are overridable; start with defaults and adjust on evidence.
• orchestrator-watch informs the model; it cannot cancel a subagent itself.

Credits

Standing on three sets of shoulders, gladly:

• Sinapsis by Luis Salgado — the self-learning system these seeds feed. instinctkit was born from his suggestion to ship the seeds library as a companion project (I'm a Sinapsis contributor; the laws tier landed upstream separately).
• fs-cortex by Fernando Montero (MIT) — origin of the ship-with-install seed concept and several of the curated seeds.
• ruflo by ruvnet (MIT) — concepts behind the roadmap pieces (LLM-free lint fixes, ReasoningBank-style memory), coming in v0.2.
• Andrej Karpathy's Think Before Coding heuristics inspired k1.

Work with me

I design and operate multi-agent AI systems in production for real businesses — this kit is the operational layer I run my own agents with.

• Site: nestormartinez.dev
• Email: [email protected]
• LinkedIn: Néstor Martínez

License

MIT