sextant

Sextant

A per-project memory framework for Claude Code that injects the right rules and context at the moment the agent acts — by reading and writing through every one of Claude Code's hooks, not by hoping the model remembers.

What is Sextant?

Sextant is a per-project memory framework that deterministically feeds an agent the rules and context that apply to whatever it's about to do. Any time the agent reads a file, edits one, runs a command, or submits a prompt, Sextant has already run — it looks at what's happening, finds the rules and graph context that match, and injects them straight into the agent's context window for that step.

Claude Code already ships a memory system: CLAUDE.md files that load at the start of a session. They're useful, and Sextant doesn't replace them. But Claude Code's own docs are blunt about what CLAUDE.md is — "Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead." A long session drifts. The instruction you wrote at the top of CLAUDE.md is a thousand messages back by the time it matters, and the model can quietly deprioritize or ignore it.

Sextant lives entirely on that hook layer the docs point to. Instead of one big file loaded once and slowly forgotten, rules are attached to the things they're about — a specific file, a topic, a keyword — and delivered when that thing comes up. A rule about lib/auth.ts shows up the moment the agent opens lib/auth.ts. A safety rule about cookies can refuse to let an edit through until you've approved it. The point isn't more context; it's context that arrives on time and, where it matters, context the agent can't skip.

It also keeps a small amount of project knowledge that compounds over time: an AST graph of how your files connect, a log of bugs you've fixed, and a rule store the agent can add to as it learns. For larger pieces of work, Sextant includes a lightweight planning workflow — tranches — that keeps a feature's charter, spec, and live progress notes in sync as the agent builds (more on that below).

Everything lives under .sextant/ in your project. It's per-project by design: the rules for this repo don't leak into the next one.

How Sextant was born

This started as a personal annoyance. Claude kept not knowing things it should have known — that this file has a non-obvious constraint, that this workflow has a step you can't skip, that this directory is load-bearing in a way that isn't visible from the code. The obvious fix is to write it down in a markdown file. That doesn't really work. The agent reads the file once, then forgets it as the session fills up, or reads it and decides not to follow it. Plain instructions are suggestions, and over a long session, suggestions lose.

So Sextant takes a more stubborn approach. Rules get injected at the exact step they apply to, and some actions are blocked until the agent does them right — a malformed rule can't end the turn, an edit to a protected file is denied, a safety-critical change pauses for approval. It's the difference between leaving a sticky note and putting a gate on the door.

The tranche workflow came later, out of using the plugin on real work. It's a lighter alternative to heavier planning systems (like the superpowers plugin), shaped around how an agent actually moves through a feature:

• A charter that's frozen once work begins — the scope and the non-negotiables, written down so they can't quietly drift mid-feature.
• A spec that's allowed to change, but only with the change logged — so the living design stays honest about what it learned.
• Tranche docs that are written live, as the agent works on them — each one grounded in the latest state: what's already shipped, what's still in scope, and what the spec has frozen. The plan isn't a thing you write up front and abandon; it's written as the work happens, against the current reality of the work.

Does it work automatically?

Mostly, yes — and that's the design goal. The hooks do their job on every turn without you typing anything:

• Rules fire and get injected as the agent reads, writes, and runs commands.
• Graph context (a file's dependencies, dependents, and symbols) is attached when the agent opens a file.
• The end-of-turn digest, the auto-tagging of new rules, the gates that block bad actions, and the snapshots that survive a context compaction all happen on their own.