benjamin-docs

Local project memory for humans and AI agents.

npm package

benjamin-docs turns useful chats into project docs.

It keeps decisions, plans, open questions, and handoff notes in Markdown files inside your project.

No cloud. No dashboard. No transcript dump.

Why It Exists

Chats are great for thinking.

They are bad at becoming project memory.

benjamin-docs saves the useful parts: decisions, plans, open questions, and handoff notes.

So the next person or agent can start with context instead of asking you to explain everything again.

Install

pnpm add -g benjamin-docs
benjamin-docs install-skill
benjamin-docs introduce

Also works as a project dependency:

pnpm add benjamin-docs

Need npm or one-off runs?

npm install -g benjamin-docs
npx benjamin-docs

install-skill installs the bundled agent skill for local agents:

~/.agents/skills/benjamin-docs/
~/.codex/skills/benjamin-docs/
~/.claude/skills/benjamin-docs/
~/.cursor/skills/benjamin-docs/

Codex, Cursor, and Claude Code can use the shared ~/.agents/skills install.

Claude Desktop / Claude.ai uses uploaded skills:

benjamin-docs package-skill

Then upload ~/Downloads/benjamin-docs-skill.zip in Claude.

Use It From Any Chat

If you only have a chat and no project folder yet, ask your agent:

Use the benjamin-docs skill to create a project from this chat.

The agent should suggest:

~/Documents/Benjamin Docs/<Project Name>

It should ask before creating files. After you confirm, it creates a local project with:

README.md
benjamin-docs/
.benjamin-docs/

For the exact agent prompt:

benjamin-docs chat-project

Use It In An Existing Project

For an existing codebase:

benjamin-docs init --mode codebase
benjamin-docs next

Then ask your agent:

Capture the current project baseline with benjamin-docs.

When the docs are captured:

benjamin-docs ready

For a planning-only folder:

benjamin-docs init --mode planning
benjamin-docs next

For one feature:

benjamin-docs init --mode feature --feature billing-reminders

Check The Docs

benjamin-docs validate
benjamin-docs review
benjamin-docs doctor --strict
benjamin-docs ready

review looks for thin or starter-template docs.

doctor --strict fails on setup gaps, validation warnings, and validation errors.

ready runs the full gate: setup, validation, and docs quality.

What It Creates

benjamin-docs/
  project/
  handoff/
  engineering/
  features/
  releases/

.benjamin-docs/

benjamin-docs/ is for people and agents.

.benjamin-docs/ is metadata for validation, scopes, anchors, and exports.

Existing docs/ folders are left alone unless you explicitly configure otherwise.

Useful Commands

benjamin-docs introduce
benjamin-docs chat-project
benjamin-docs install-skill
benjamin-docs doctor
benjamin-docs doctor --strict
benjamin-docs review
benjamin-docs ready
benjamin-docs package-skill
benjamin-docs init
benjamin-docs init --mode codebase
benjamin-docs init --mode feature --feature <slug>
benjamin-docs next
benjamin-docs status
benjamin-docs validate
benjamin-docs scope create feature <slug>
benjamin-docs export --audience developer

Local Development

git clone https://github.com/msiksnis/benjamin-docs.git
cd benjamin-docs
pnpm install
pnpm check

Before publishing:

pnpm run release:check
tmpdir=$(mktemp -d)
pnpm pack --pack-destination "$tmpdir"
npm publish "$tmpdir"/benjamin-docs-*.tgz --access public

Contributing

Keep it local-first.

Keep docs readable by non-programmers.

Keep agent workflows explicit.

Avoid magic that writes outside the project unless the user runs a clear command.