agentic-os v2: The Tool You Installed Isn't the One Running Now

Less library, more guardrail. The version on your disk is several releases behind the one I'm running.

If you installed agentic-os and walked away, the thing sitting in your .claude/ directory is not the thing I am running now. Since the last release I actually wrote up here, it shed about 47% of itself, grew a layer of hooks that fight its own forgetting, flipped that layer on by default, and learned to run on Cursor instead of only Claude Code. That is one major version and a handful of minor ones, and you got a changelog for none of it.

So here is the through-line before the details: the agentic-os you installed is a different tool now. Roughly half the size, fighting its own context drift — the agent context drift that creeps into any long session — with deterministic hooks, active by default, and dual-runtime across Claude Code and Cursor. If your mental model of this project is "a big library of skills and agents I cloned once," that model is two grades stale.

A quick accounting of the gap, because I owe you one. The last release I published a post about was v1.1.0, the review ratchet. Then v1.4.0 shipped /v2-collab and I drafted the writeup and never hit publish. Then the whole v2 line landed. So this catches you up from v1.4 through v2.4 in one pass, organized by what changed rather than by version number, because the version numbers are not the story. The story is that the project stopped growing by addition.

The headline of v2.0.0 is subtraction. I cut the library from 132 artifacts to 62. That is a 47% reduction in the always-on context every session pays for before it does any work.

Here is the misconception that prune is aimed at, and I held it as hard as anyone: more skills means a more capable library. It does not. Most of what I had accumulated was not capability. It was a skill, agent, command, or rule that restated default good practice the model already follows, duplicated something another artifact already covered, or existed only to add a routing hop. Every one of those is loaded into context whether or not the session needs it. They are a tax, charged on every run, paid in the tokens that could have held the actual task.

So the razor was simple. Cut anything that merely restates what a competent model already does, duplicates another artifact, or only adds routing noise. Keep the genuine project conventions, the real automation, the disciplines that are reproducible and worth pinning down. What survived is the half that earns its place in context. README, installers, and the ship manifest were synced to match, and the validators stayed green through the cut.

That is the part you can measure. The more interesting half of v2.0.0 is what I added back, and it weighs almost nothing.

Run an agent long enough and it starts to forget itself. Not crash, not error out, forget. The context window is finite, so a long session compresses as it goes, and compression is lossy. Facts that were settled an hour ago get quietly re-derived from scratch. Infrastructure that already exists gets rebuilt because the agent no longer remembers building it. The session is still confident, still productive-looking, and steadily drifting away from things it already knew.

I started calling this awareness drift, and it is the dominant failure mode of any session that runs past a single compaction. It is not a model-quality problem. A smarter model drifts too; it just drifts more articulately. The fix is not a better prompt. It is a mechanism that holds onto the settled facts across the compressions, deterministically, so the agent cannot lose them.

That mechanism is the awareness harness, and it is a set of Claude Code hooks rather than anything the model has to choose to do.

Walk one long session through it. At SessionStart, the harness injects a SESSION-STATE.md file into context, so the agent opens already knowing where things stand. Each turn, it writes a compact digest of what was settled, so the record stays current instead of going stale the moment it was written. Right before the context window compacts, a PreCompact checkpoint fires and pins the state down, so the lossy compression happens around a record that survives it. And the file itself is never hand-edited; a deterministic /state writer is the only thing that touches it, so the record is reproducible rather than another thing the agent has to remember to maintain.

Sitting off to the side is the survey-before-act guard. It hooks PreToolUse and warns when the agent is about to build something it should check for first. Right now it only warns and logs; it does not block. That is deliberate. I want real evidence about false positives before I let a guard veto an action, so for now it measures and stays out of the way.

Contrast that with the same session before v2. The agent settles a fact, works for an hour, hits a compaction, and the fact is gone. It re-derives it, often slightly differently, and now there are two versions of a thing that should have been one. Nobody flagged it. The session looked fine the whole time. That silent re-derivation is exactly what the harness exists to stop.

Two things are worth saying plainly here. First, this is not CI, and the second misconception I want to break is that these hooks are just automation or linting wearing a different hat. A linter checks the code. The awareness harness checks the agent's grip on what it already knows. It is an awareness layer, not a build step, and it runs in a part of the session a linter never sees.

Second, every piece of this got built and dogfooded under review before it shipped. The metrics module, session-metrics, establishes a deterministic baseline of tokens and an awareness signal, and a review of it caught a token-counting bug that was inflating the count by 2.85 times. A compare harness re-aims the evaluation at tokens-per-outcome with the hooks on versus off. And the whole thing sits behind a security spine: a threat model in SECURITY.md and a Tier-0 hook-safety invariant baked into the validator, which enforces that any shipped hook is a plain shell script with no exfiltration, no arbitrary exec, no obfuscation, no credential access, and no persistence tricks. Hooks run with your shell's reach. That invariant is the price of admission for any of them shipping at all.

One caveat on v2.0.0 specifically: the harness shipped dormant. The scripts were in the release, but nothing registered them, because wiring deterministic hooks into a consumer's global config is a supply-chain decision and I was not going to flip that switch in the same release that built the thing. The switch came later, and it is its own section below.

For its entire life, agentic-os was a Claude Code project. That is the third misconception worth retiring: it is not Claude-Code-only anymore. The v2.1 through v2.3 line made it dual-runtime, and a Cursor shop can install and run it natively.

The Cursor port is more than a symlink. There is an AGENTS.md that gives Cursor a real orchestrator entry point, with the same parallel fan-out model the Claude Code side uses, so dispatching subagents works the way the doctrine assumes. The always-on rules live in .cursor/rules/*.mdc, in Cursor's own format, so the doctrine is enforced the native way rather than bolted on. There are dedicated installers, install-cursor.sh and install-cursor.ps1, including a PowerShell path for Windows.

The piece I am happiest with is dual-path skill resolution. A skill is looked up in the repo's .claude/skills/ first, then falls back to ~/.cursor/skills/, then to ~/.claude/skills/. That means a single checkout can serve a Claude Code user and a Cursor user without either one reorganizing their machine. And every one of the 35 skills now carries a compatibility field in its frontmatter, so the resolver knows what runs where instead of guessing.

If you live in Cursor and had written this project off as not for you, that is no longer true.

The v2.0.0 harness shipped dormant. The v2.3 line is where I flipped it on.

As of v2.3.0, the installers merge the awareness harness and a block-bad-bash guard directly into your global config, the settings.json on the Claude Code side and hooks.json on the Cursor side. Install agentic-os and the harness is live, not sitting in a folder waiting for you to wire it up. That is the supply-chain step I deliberately held back in v2.0.0, taken on purpose once the security spine was in place.

Two honest notes on that line, because it did not land cleanly on the first try. Use v2.3.1 or later, not v2.3.0. The v2.3.0 install.sh called a function by the wrong name and silently failed to register the hooks, so the headline feature of the release did not actually turn on. v2.3.1 fixed exactly that. Then v2.3.2 is the canonical version from main: same feature set, plus Tier-0 ship gates and hardening of the install destination paths for both bash and PowerShell. If you are pinning a version from this line, pin v2.3.2.

And because on-by-default is a strong move for something that touches your global config, it is one line to opt out. Remove the hooks block from ~/.claude/settings.json, or from ~/.cursor/hooks.json on Cursor, and you are back to a plain install with nothing registered. The harness is the default, not a lock-in.

# Turn the harness off: delete the "hooks" block from your global config
#   Claude Code -> ~/.claude/settings.json
#   Cursor      -> ~/.cursor/hooks.json

v2.4.0, the current release, is about making the project's own shipping discipline reproducible.

There is a plain-language Features section in the README now, which sounds small and is not, because "what does this thing actually do" was a question the README had stopped answering as the library grew and then shrank. There is a ship-gate DAG, the canonical review orchestration, expressed as gate-dag.md and a gate-plan.sh planner with checkbox enforcement in CI, so the review gates a change has to clear are a declared graph instead of a thing I remember to run.

And there is a DATA_MODEL pipeline. A data-model-documenter agent runs in the first wave to capture a change's data model, a data-model-verifier agent checks it in a second wave, and JSON Schema extractors enforce it at Tier 0. The stack specialist agents dispatch the documenter at the close of a session, so the data model gets written down at the moment the agent still holds the full context for it, rather than reconstructed later from the code. It is the awareness-drift idea again, pointed at a different target: capture the settled thing while it is still settled.

This one is not part of v2, but you never saw it, so it belongs here. v1.4.0 shipped /v2-collab, an in-session multi-agent collaboration pod, and the post I wrote about it never went out.

The short version: it is a pod of agents that argue a deliverable out before you see it. The default roster is technical-pm -> engineer -> code-reviewer, and it is configurable. The PM frames the work, the engineer builds it, the reviewer critiques each round, and the loop runs for several rounds until the reviewer approves or a round cap stops it. The reviewer can reject and send the work back, which is the part that lets you stay out of the loop safely.

The fourth misconception is that this kind of thing needs infrastructure. It does not. /v2-collab runs entirely inside a Claude Code session on the subscription you already pay for. No Redis for shared state, no Docker, no API keys to provision. Roles are prompts, rounds are a loop, the reviewer's veto is an if. The one piece of real infrastructure it needs is a safe place to write what it makes, so output goes to a path you name, defaulting to ./v2-out/, behind fail-closed path sanitization that refuses to escape the target directory.

/v2-collab Build a single-page marketing site for an AI healthcare startup ... write it to ./out

What lands in ./out has already survived an argument you did not have to referee.

If you are running an old checkout, the upgrade is one command, and it is the same shape on both runtimes.

# Claude Code
curl -fsSL https://raw.githubusercontent.com/LazyIsEfficient/agentic-os/v2.4.0/install.sh | bash
# Cursor
curl -fsSL https://raw.githubusercontent.com/LazyIsEfficient/agentic-os/v2.4.0/install-cursor.sh | bash

The throughline across all of it is the same bet made in two directions. The prune cut the context that was not earning its place. The harness adds back the small deterministic layer that keeps the agent from losing the context that was. Less noise going in, more signal staying put. Cursor support widened where that bet runs, and on-by-default decided you should get it without opting in. The version you installed grew by adding skills. This one got better by removing them and remembering harder.

The whole thing is open source in agentic-os, one command to install on either runtime. If "the tool changed under me" is a feeling you would rather not have again, star the repo so the next release shows up where you will see it. And subscribe below, where I write up what this system teaches me, usually by going wrong first.

Subscribe on Substack

— Glenn Eggleton builds agentic engineering systems and writes about what survives contact with production.