Metacog — Development skill for Claude Code

metacog

[](https://www.npmjs.com/package/@houtini/metacog)

So, here's the problem with AI coding agents: they can't feel when they're stuck. They'll retry the same broken fix five times because they can see each individual error but not the *pattern* of repeated failure. They'll read the same file three times in a session because context compaction wiped their memory of reading it. They'll chase a dependency chain four levels deep and forget what they were originally trying to fix. They have no sense of time, no peripheral vision of how their changes affect other files, and no awareness of whether they're actually validating their work or just admiring it.

Metacog is a pair of Claude Code hooks that gives the agent something like a nervous system. I say "something like" because the signals arrive as text in the agent's context, not as actual sensations. It's closer to a colleague leaving a post-it note than biological proprioception. But that turns out to be enough. One hook fires after every tool call and watches for these patterns. The other fires when you send a message and injects learned rules from past sessions. When everything is fine, both hooks are completely silent, zero tokens, zero cost. When something is off, a short signal appears in the agent's context. At first it's just awareness, and the agent's own reasoning decides what to do about it. But if the agent keeps failing, the signals escalate from gentle nudges to structured interventions that force the agent to stop and rethink. That escalation matters, because if the agent's reasoning was working properly it wouldn't be stuck in the first place.

And when problems do resolve, the system extracts what changed and persists it as a behavioural rule that gets injected into future sessions. This is probably the most interesting part. Most