undercurrent-studio

Cortex

A Claude Code plugin that works like a living organism — 13 biological systems that learn, adapt, protect, and evolve across your coding sessions.

---

What Does It Actually Do?

Imagine a second brain sitting alongside Claude that:

• Remembers every file you edit, every commit you make, every tool call
• Blocks dangerous operations before they happen (like using now() in a Postgres migration)
• Injects context when you mention a topic — keyword-matched context files flow to where they're needed
• Nudges you to commit when edits pile up, and validates commit message format
• Guards session end so you don't walk away with uncommitted work or stale docs
• Watches the outside world — did CI fail? Did someone push to remote? Any open PRs?
• Heals itself — corrupted state files get repaired automatically on boot
• Adapts its behavior based on your recent session quality
• Proposes its own improvements and waits for your approval
• Tracks patterns across sessions — which files keep getting re-edited, what domains you focus on
• Audits your implementation plans before you start building (44 gates with Killer 7 universal core, risk-tiered depth, and domain-specific activation)

All of this happens through bash hooks that fire at specific moments in your Claude Code session.

---

Setup

Requirements

• Claude Code (CLI or VS Code extension)
• Git Bash on your PATH (Windows: comes with Git for Windows)
• Python 3 on your PATH (needed for bootstrap and JSON manipulation)
• GitHub CLI (gh) — optional, but needed for the Sensory system (CI/PR checks)

Installation

claude plugins marketplace add Undercurrent-Studio/undercurrent-cortex
claude plugins install cortex@undercurrent-studio

Restart Claude Code. On first session start, the plugin bootstraps all hook events into your global ~/.claude/settings.json automatically.

Hook Architecture

Cortex uses a two-tier hook dispatch system due to a known bug where plugin hooks.json command hooks are unreliable for most events:

Tier	Location	Events	Why
hooks.json	Plugin manifest	SessionStart only	Proven working; serves as the bootstrap's lifeline
Global settings.json	~/.claude/settings.json	PreToolUse, PostToolUse, PreCompact, Stop, SessionEnd, UserPromptSubmit	Bootstrapped on every session start; the only location proven to reliably fire hooks

The bootstrap-hooks.sh script runs on every SessionStart and:

1. Injects 6 hook events into ~/.claude/settings.json (idempotent — skips if already correct)
2. Replaces stale entries when the plugin version changes (path-aware)
3. Cleans up orphan entries from old plugin versions (matches by script name pattern)
4. Cleans up legacy entries from the old project-level settings.local.json

All bootstrapped entries are tagged with "_cortex_bootstrap": true for identification.

Profiles

Cortex supports three hook profiles that control which systems are active:

Profile	Events Injected	Use Case
standard (default)	All 6 events	Full organism — recommended for most projects
minimal	PreToolUse, PostToolUse, SessionEnd only	Lightweight — enforcement + state tracking only
strict	All 6 events + proposals auto-surfaced	Full organism with more aggressive adaptation

Set via CORTEX_PROFILE env var or .claude/cortex/profile.local file in your project.

---

The 13 Systems

Think of the plugin as a body. Each system has a specific job, and they work together.

Systems 1-4: The Core Loop

These fire every session and handle the basics.

1. Nervous System — State Tracking Every edit, commit, and tool call gets counted in a session-scoped state file. The nervous system is how the organism "feels" what's happening — it's the raw sensory data that other systems read.

Where: post-dispatch.sh (universal counter), post-edit-dispatch.sh, post-bash-dispatch.sh State: edits_since_last_commit, commits_count, tool_calls_count, [files_modified] section

2. Immune System — Dangerous Operation Blocking Before certain tools execute, the immune system checks if the operation is safe. If not, it blocks it with an explanation.

Examples of what gets blocked:

• now() or CURRENT_DATE in a migration file (PostgreSQL requires IMMUTABLE functions in partial indexes)
• Overwriting a plan file without reading it first (plan-file-guard prevents accidental destruction)
• Writing implementation code before tests exist (TDD guard, when test files are expected)

Where: pre-dispatch.sh routes to migration-linter.sh + plan-file-guard.sh + tdd-guard.sh