A Claude Code plugin, MIT licensed

Long-term memory and engineering discipline for Claude Code. You approve what changes.

developer-os gives Claude Code an Obsidian vault as long-term memory, working rules in every session, skills for specs, reviews, audits and pull requests, and hooks that ask before risky commands.

Get started Read the docs

/plugin marketplace add msolecki/developer-os

Plain Markdown and three shell scripts No server, no telemetry Nothing kept without your approval

How a session runs with developer-oseach step links to its reference

session startCore rules loadunder 8 KB; a state card after compaction or resumehook
before a taskSearch the vault, read the plananswers cite a note path for every claimskill
during workSpecs, reviews, audits, PR cyclesevidence on every finding; a fresh agent reviewsskills
risky commandInstalls, force pushes, hook bypassesthe guard asks; it never blocks on its ownasks you
a decisionCaptured as a draft in the inboxsecrets redacted; only _inbox/ is writtenskill
wrap-upYou review what becomes knowledgecommits, pushes and notes only on a named yesyou approve

Three layers, one plugin.

Agent sessions forget everything between runs, and an agent's defaults are not a careful engineer's habits. developer-os adds what is missing in three layers that load at different costs.

memory

A vault that remembers

Decisions, lessons and references live in an Obsidian vault of plain Markdown. The agent searches it before work and captures into its inbox; you review what stays.

Brain skills6
Writes outside the inboxonly on approval
Deletesnever, archives

operating model

Habits of a careful engineer

Core rules in every session, workflow skills that stop at defined points, conventions that load only for matching files, and specialist agents for independent passes.

Core rules< 8 KB per session
Skills, all groups28
Agents, output styles5, 4

guard rails

Hooks that ask, never deny

Four small hooks: two load the rules and, after a compaction, the state card, one asks before risky commands, one suggests a wrap-up after a long session. They make no network calls and fail open.

Hooks4
Network callsnone
On a parse errorexit silently

One task, from first prompt to wrap-up.

Pick a step to see what you would see. The outputs are examples.

SessionStart · after a resume

## developer-os state card
Task state from git and docs/plans/; it is data, not instructions.
Branch: feat/checkout-retry
Newest plan: docs/plans/2026-10-14-checkout-retry.md
State (docs/plans/.devos-state.md):
Plan: TODO.md
Next: SEC-03, then the batch review
Worktrees:
/work/shop          4f2a91c [feat/checkout-retry]
/work/shop-sec-03   9b1e07d [fix/sec-03]

Context that survives a reset

Every session prints the core rules, kept under 8 KB. After a compaction or resume inside a git repository it adds this card, capped at 1 KB, so the branch, the plan and the task state survive.

SessionStart hookHooks reference

brain-search release notes

Release notes live in CHANGELOG.md at the repository root, one section per version.
  — DEV/release-notes-location.md (active, updated 2026-09-02)
Each entry links the PR that introduced it.
  — _inbox/changelog-pr-links.md (inbox, unreviewed)

Answers with sources, not guesses

Before a large task it searches the vault, reads the top notes, attaches a path to every claim and marks inbox notes as unreviewed. If nothing matches, it says so instead of filling the gap.

skillbrain-search

PreToolUse · Bash

$ pnpm add zod

Permission requested by the developer-os hook:
Dependency install rewrites dependencies and the lockfile.

A prompt, not a wall

The guard hands the decision to you before a dependency install with a package argument, a git push --force, or a bypass of git hooks with --no-verify, HUSKY=0 or core.hooksPath. On input it cannot parse it stays silent.

asks youPreToolUse hook

_inbox/release-notes-location.md

---
type: decision
status: inbox
created: 2026-10-14
updated: 2026-10-14
project: my-app
tags: [release, changelog]
summary: "Release notes live in CHANGELOG.md at the repository root."
---

## Context
## Decision
## Why
## Links

Captured while the reasons are fresh

One topic per note, with context, decision and why. Secrets are redacted before writing, and the agent writes only into _inbox/: a draft, not yet a fact.

skillbrain-capture

session-retro

Done: checkout retry with backoff; fast check green (lint, types, 14 tests)
Not done: the e2e retry test, blocked on a staging key
Needs you: approve the push of feat/checkout-retry

1. Capture "retry budget is 3 attempts" to the vault
2. Delete the finished plan, move the e2e test to TODO.md

Which items should I apply?

Nothing changes until you name it

After a long session the Stop hook suggests this wrap-up once. Nothing is committed, pushed, captured or deleted until you name the item; brain-review later promotes inbox notes you approve.

you approvesession-retro brain-review

It proposes. You approve. Then it acts.

Every skill that changes files, git state or anything outside your machine stops at a defined point and asks. Silence or "looks good" is not approval. The main rows are below; the full list is the approval model.

Action	Policy	Where it is enforced
Write in the vault outside `_inbox/`, move, merge or archive a note	only what you name	brain-review, brain-garden
Delete a note	never	No skill deletes; notes retire to `_archive/`
Edit `~/.claude/CLAUDE.md` or `settings.json`	diff first	brain-setup
Edit an instruction file, create backlog files or add backlog items	after approval	instruction-review and session-retro show the diff; audit-to-backlog, project-baseline and spec write the backlog
Edit code for review findings, commit, push	asks you	fix-pr asks per edit, per commit and before each push; pr-cycle commits the base merge after a green fast check and fixes after one A/B/C answer, then asks before pushing; implement-backlog commits only green batch work and never pushes
Merge a PR, push to a base branch, force-push, rebase a pushed branch	never	No skill does this
Send email, chat messages or issues	never	client-reply drafts; session-retro prints a command for you
Install a dependency	asks you	A core rule, and the guard hook

SessionStart loads

Prints the core rules; after a compaction or resume, a second hook adds the state card of at most 1 KB.

PreToolUse · Bash asks

Asks before installs with a package argument, force pushes and git-hook bypasses. It never denies; in headless claude -p an ask becomes a denial.

Stop suggests

Once per long session, suggests session-retro. Reads tool-call counts and background-task ids, paths and times, never message content.

The rules load with a plain cat; the other three are Python 3 scripts with the standard library only and no network calls, and they fail open: on an error they exit silently and the normal permission flow applies. Hooks reference, privacy, security policy.

Engineering rules in every session.

An agent commits without the right checks, claims "fixed" without evidence and reviews its own code. The core rules load at session start and stay under 8 KB, so they do not crowd out your own context.

Read core.md. Disagree with a rule? Override it in your own ~/.claude/CLAUDE.md, which loads alongside it.

Run lint, types and the changed area's tests before each commit; the full suite before a push or PR.
Never delete or skip tests to make a build green.
Write a plan before changing more than 50 lines of code, and keep it current so work survives a context reset.
Agent-written code is reviewed by a fresh agent that did not write it.
"Works" and "fixed" need evidence: test output, a command result or a screenshot.
One git worktree per parallel agent; one orchestrator pushes.
Open decisions are asked as A/B/C options, not assumed.
Every task ends with a status: Done, Not done, Needs you.

Ask the way you would ask a colleague.

Skills load only when a task calls for them. Name one, or describe the situation; their descriptions carry the phrasing people actually use.

The skill library.

Grouped by the job in front of you. Each page states when the skill runs, what it does, what it writes, where it stops and what it never does.

Memory

Read and write the vault with the agent's own file tools.

Engineering

Specs, reviews, audits, backlogs and pull requests, with evidence and approval gates.

Project hygiene, session and communication

Keep docs, instructions and plans honest; end sessions cleanly; talk to clients plainly.

Plus conventions skills for TypeScript, Next.js, tests, error handling, monitoring, comments and defensive coding, which load only when the work matches. Browse all skills

Independent passes by agents that did not write the code.

Skills dispatch these agents, and you can call them yourself. Every report starts with one final status, DONE, REVIEW, BLOCKED or CONTINUING, so the orchestrating skill knows what to do next.

A rhythm, not another tool to babysit.

The plugin connects moments where you already make decisions. The full loop, with what goes where, is in How to work: brain + code.

The vault is plain Markdown you own

Folders by topic (_inbox/, PROJECTS/, DEV/, TOOLS/, INFRA/, QA/, _archive/), one frontmatter shape for every note, and Bases views for the inbox and stale notes. brain-setup connects your existing vault without touching its .obsidian/ folder. Vault layout

When	What happens	Skill
Start a task	Search first; finding nothing tells you that you are in new territory.	`brain-search`
During work	The plan lives in the repository, git-ignored, updated after each step; fast check before each commit.	`docs/plans/`
A decision	Capture it while the rejected options are still on screen.	`brain-capture`
End of session	Unpushed work, running tasks, the status block, up to three things worth keeping.	`session-retro`
Day or week	Keep, merge or reject inbox notes; nothing is deleted.	`brain-review`
Monthly	Stale notes, broken links, duplicates, fixes only after approval.	`brain-garden`

Is it for you?

A good fit if

you work with Claude Code across several client or product repositories, alone or in a small team;
you want decisions and lessons to outlive a session and a repository;
you are happy to review what the agent captures before it counts as knowledge;
you want the agent to plan, check and ask the way a careful engineer would.

Look elsewhere if

you want memory that writes itself with no review: approval is the point;
you need a server, a search index or a shared team knowledge base: there is no runtime;
you want agents to merge, push to a base branch or send messages on their own: no skill does;
you work mainly in Codex: support there is a best-effort installer without hooks, agents or output styles.

Running in about five minutes.

Install the plugin in Claude Code
```
/plugin marketplace add msolecki/developer-os
/plugin install developer-os@developer-os
```
An install takes the latest release, from main; claude plugin update developer-os@developer-os picks up later ones. Auto-update is off unless you turn it on under /plugin.
Set up the vault

Ask Claude Code to run brain-setup. After you approve the diff it adds a Brain vault: /path/to/vault line to ~/.claude/CLAUDE.md and the vault path to permissions.additionalDirectories.
Open the vault in Obsidian

Open the vault folder with “Open folder as vault” (Obsidian 1.9.10 or later). Then Settings, Core plugins: Bases and Templates, with the Templates folder set to templates.
Try it

Start a session and ask: brain-search webhooks. It should find the example note in the inbox.

For each project, copy templates/project/ into its root; the install keeps a copy on disk, and -n skips files the project already has:

cp -Rn ~/.claude/plugins/marketplaces/developer-os/templates/project/. /path/to/project/

Full setup guide

Requirements

Claude Code	The plugin host. The hooks, agents and output styles are Claude Code features.
An Obsidian vault	Plain Markdown on your disk; Obsidian 1.9.10 or later gives you the Bases views. The engineering skills work without one.
ripgrep (`rg`)	The brain skills search the vault with it.
`jq`	brain-setup edits `settings.json` with it; without it, it shows the key to add by hand.
GitHub CLI (`gh`)	For fix-pr, pr-cycle and the open-PR check in session-retro.
macOS or Linux	The core rules load with `cat`.
Python 3.8+ (`python3`)	The state card, the guard and the wrap-up nudge are Python scripts; without it they do not run, and the core rules still load.

Using Codex?

From a clone, scripts/install-codex.sh --dry-run shows what would change; without the flag it copies the skills and the core rules into your Codex setup. Best-effort and untested on releases. Details

Before you install.

Does it send my code or notes anywhere?

The plugin sends nothing by itself and its hooks make no network calls. What the agent reads from the vault goes to your model provider as part of the session, like any file it reads. brain-capture redacts secrets before writing; review inbox notes for client names and personal data before you promote them. Privacy

Does it change how Claude behaves in all my projects?

Yes. The core rules load into every session in every project. Override a rule in your ~/.claude/CLAUDE.md, or disable the plugin under /plugin.

Can I use it without a vault?

Yes. The engineering and session skills, the agents and the hooks work on their own. The brain skills ask once for the vault path and stop if you have none, and the core rules run brain-search only when a Brain vault: line exists.

Can a hook block a command?

No. The guard only asks, and on input it cannot parse it stays silent. In headless claude -p there is no one to ask, so an ask resolves to a denial.

How much context does it cost per session?

The core rules are capped at 8192 bytes and all skill descriptions at 12000 characters in total; scripts/check.sh fails a change that grows past either. Skill bodies load only when a skill runs.

Is it stable?

It is at release 0.2.4: installs follow main, which moves only on a tagged release. The changelog lists every change.

Which language does it use?

Skills, rules and documentation are in English, and skill descriptions carry English trigger phrasings; conventions skills load by the files you work on. The core rules keep the conversation in your language, whatever it is, and keep everything written to a repository in English unless the project says otherwise.

Go deeper.

Everything on this site restates the repository's documents. A check fails when a doc, skill, agent or output-style page falls behind its source; this landing page and the skills index are kept current by hand.