agent-notes 2.30.0

AI agent configuration manager for Claude Code, OpenCode, and Copilot

agent-notes

AI agent configuration manager for Claude Code and OpenCode — orchestrates a team of 19 specialized subagents across three model tiers.

Quick Start

pip install agent-notes
agent-notes install    # interactive wizard guides you through setup
agent-notes doctor

What's Included

• 19 specialized AI subagents (Opus reasons, Sonnet executes, Haiku explores)
• 47+ on-demand skills (Rails, Docker, Git, Kamal, Process)
• Global rules and guardrails
• Agent memory with 3 storage options (Local, Obsidian, Wiki)
• Configuration for Claude Code, OpenCode, and GitHub Copilot

---

Installation

PyPI (recommended)

pipx (isolated environment, no manual venv needed):

pipx install agent-notes
agent-notes install

venv + pip (if you prefer to manage your own environment):

python -m venv .venv && source .venv/bin/activate
pip install agent-notes
agent-notes install

Upgrade from a previous version

Update in place (normal upgrade):

With pipx:

pipx upgrade agent-notes && agent-notes install

With venv:

pip install --upgrade agent-notes && agent-notes install

Clean reinstall (from an older version, fresh slate):

If you are on a significantly older version or want a fresh configuration, uninstall completely and reinstall:

With pipx:

agent-notes uninstall && pipx uninstall agent-notes && pipx install agent-notes && agent-notes install

With venv:

agent-notes uninstall && pip uninstall agent-notes && pip install agent-notes && agent-notes install

Local build (developers)

git clone https://github.com/rubakas/agent-notes.git
cd agent-notes
pipx install -e .        # editable: CLI runs live from the working tree
agent-notes install

With editable mode, the CLI runs directly from your source files. After edits, run agent-notes install to rebuild dist/ and reinstall into your Claude config. No rebuild command needed between iterations.

To produce a release artifact (wheel for distribution), use python -m build + pipx reinstall dist/*.whl — this is separate from local development.

Plugin (limited functionality)

• Claude Code: install via the Claude Code plugin marketplace or copy/symlink .claude-plugin/ into ~/.claude/plugins/agent-notes/.
• OpenCode: copy or symlink .claude-plugin/ into ~/.config/opencode/plugins/agent-notes/ and add "plugin": ["agent-notes"] to opencode.json.

The plugin runs a session.start hook that surfaces agent-notes context to the CLI session. It does not include the full agent-notes CLI (wizard, doctor, config, memory, etc.). For those, use install method 1 or 2.

API keys

Provider API keys live in ~/.agent-notes/credentials.toml (mode 0600, never committed). Add or update via:

agent-notes config providers

The wizard prompts for the key with hidden input; agent-notes never logs or prints the value. To check whether a provider is configured without exposing the key:

agent-notes config provider openrouter   # prints "configured" or "no key"

Uninstall

To fully remove agent-notes:

pipx:

agent-notes uninstall
pipx uninstall agent-notes

Run agent-notes uninstall first — it removes agent files, hooks, settings.json entries, context file, and state that agent-notes installed. Then pipx uninstall removes the package itself. The agent-notes uninstall command must run while the CLI is still installed.

venv:

agent-notes uninstall
deactivate
rm -rf .venv

Run agent-notes uninstall first to clean up installed components, then deactivate the environment and delete the .venv directory.

Note on memory and vault permissions:

If you configured agent-notes to access your memory vault (Obsidian or local), those read/write permissions are intentionally left in place after uninstalling so Claude Code and other tools can still access your notes. To remove them, edit ~/.claude/settings.json and delete the entries under permissions.allow that reference your vault path (e.g. Read(/path/to/your/vault/**), Write(/path/to/your/vault/**), Edit(/path/to/your/vault/**)).

---

Agent Team

Specialized subagents with hierarchical model strategy: Opus 4.6 reasons, Sonnet 4.6 executes, Haiku 4.5 scouts.

Agent	Role	Model Tier	Purpose
lead	orchestrator	opus	Plans, coordinates, verifies — the team lead
architect	reasoner	opus	System design, module boundaries, refactor planning
debugger	reasoner	opus	Complex bug investigation, root-cause analysis
coder	worker	sonnet	Implementation, file edits, bug fixes
reviewer	worker	sonnet	Code quality, readability, correctness
security-auditor	worker	sonnet	Auth, injection, XSS, secrets exposure
test-writer	worker	sonnet	Creates tests for any framework
test-runner	worker	sonnet	Diagnoses and fixes failing tests
system-auditor	worker	sonnet	Duplication, dead code, coupling, complexity
database-specialist	worker	sonnet	Schema design, indexes, query performance
performance-profiler	worker	sonnet	Response times, memory, bundle size
api-reviewer	worker	sonnet	REST conventions, versioning, backward compatibility
devops	worker	sonnet	Docker, CI/CD, deployment, infrastructure
devil	worker	sonnet	Devil's advocate — challenges plans and assumptions
integrations	worker	sonnet	OAuth, webhooks, API clients, SSO
refactorer	worker	sonnet	Extracts methods, reduces duplication, improves naming
explorer	scout	haiku	Fast file discovery, pattern search
analyst	scout	haiku	Requirements translation, acceptance criteria
tech-writer	scout	haiku	READMEs, API docs, changelogs

4 roles, 19 agents, 3 model tiers. The tiered model strategy optimizes cost: Opus reasons ($15/1M tokens), Sonnet executes ($3/1M), Haiku scouts ($0.80/1M).

Delegation rules

• lead — Plans, coordinates, and verifies across the team
• architect / debugger — Deep reasoning for complex design and debugging
• coder — All file edits and implementation work
• reviewer — Code quality checks after implementation
• security-auditor — Auth, input handling, data access
• test-writer — Creates tests; test-runner diagnoses and fixes failures
• system-auditor — Duplication, dead code, architectural issues
• database-specialist — Schema design, queries, indexes
• performance-profiler — Latency, memory, bundle size
• api-reviewer — REST conventions, versioning, backward compatibility
• devops — Infrastructure, CI/CD, Docker
• integrations — OAuth, webhooks, API clients
• refactorer — Extraction, duplication, naming
• explorer — Fast discovery and pattern search
• analyst — Requirements and acceptance criteria
• tech-writer — Documentation, READMEs, API docs
• devil — Challenges assumptions and plans

---

Memory Storage

Agents accumulate knowledge across sessions. Choose a backend during agent-notes install:

Backends:

• default - Claude Code built-in md files (default) — Plain markdown in ~/.claude/agent-memory/<agent>/. No external tools. Simple, portable.
• Obsidian - session — Per-project session notes in Obsidian vault. Auto-creates <vault>/<project>/ with categories: Patterns/, Decisions/, Mistakes/, Context/, Sessions/. Includes YAML frontmatter and [[wikilinks]].
• Obsidian - brain — Karpathy's LLM Wiki pattern. Per-project knowledge brain in <vault>/<project>/raw/ and wiki/ (sources, concepts, entities, synthesis, sessions). Supports ingest/query/lint operations.
• None — Disables memory.

To reconfigure after install:

agent-notes install --reconfigure        # switch storage
agent-notes config memory               # interactive backend selector

Local (default)

Storage: ~/.claude/agent-memory/<agent>/

agent-notes memory list               # list all notes by agent
agent-notes memory show <agent>       # show one agent's notes
agent-notes memory size               # disk usage
agent-notes memory reset [agent]      # clear memory (confirmation required)
agent-notes memory export             # back up to memory-backup/
agent-notes memory import             # restore from memory-backup/

Obsidian (session or brain mode)

Storage: <vault-root>/<project-name>/ (auto-created per CWD)

Session mode commands:

agent-notes memory init               # create folder structure and Index.md
agent-notes memory list               # list all notes (by category or agent)
agent-notes memory vault              # show storage path and init status
agent-notes memory index              # regenerate Index.md
agent-notes memory add <title> <body> [type] [agent]  # type: pattern|decision|mistake|context|session
agent-notes memory reset [agent]      # clear memory (confirmation required)
agent-notes memory export             # back up to memory-backup/
agent-notes memory import             # restore from memory-backup/

Brain mode adds:

agent-notes memory ingest <title> <body> <concepts> <entities> <tags>  # manual ingest
agent-notes memory query <question>   # search wiki pages
agent-notes memory lint               # health-check

Setup: Run agent-notes install and choose Obsidian - session or Obsidian - brain. The wizard auto-detects vaults under ~/Documents, ~/Desktop, and ~. Then run agent-notes memory init.

---

Skills

47+ on-demand knowledge modules across Rails, Docker, Kamal, Git, and Process. Run agent-notes list skills for the current list, or browse agent_notes/data/skills/.

The session context hook auto-generates a skill index from SKILL.md frontmatter at install time, so agents always know what skills are available without loading full skill content. This keeps context overhead low while maintaining skill discoverability.

Using skills in Claude Code / OpenCode

Use the rails-models skill to help with this association
Load the docker-compose skill for multi-service setup

Core skills addressing failure modes

Failure mode	What goes wrong	Skills that help
Misalignment	Claude starts building before the problem is resolved	/grill-me, /grill-with-docs
Verbosity	Responses are bloated; context window fills with noise	/caveman, /setup-project-context
Broken code	Claude codes without a feedback loop or evidence trail	/tdd (improved), /debugging-protocol (improved)
Ball of mud	Architecture drifts; modules grow shallow and tangled	/improve-codebase-architecture, /zoom-out

Skill descriptions:

• /grill-me — Interview the user until the problem is fully resolved before touching code
• /grill-with-docs — Same, but cross-references CONTEXT.md and ADRs and updates them inline
• /caveman — Ultra-compressed reply mode (~75% token savings) for rapid iteration
• /setup-project-context — Bootstraps a CONTEXT.md domain glossary (ubiquitous language)
• /tdd — RED-GREEN-REFACTOR with tracer-bullet vertical slices; horizontal-slicing anti-pattern added
• /debugging-protocol — Phase 1 rewritten as "build a feedback loop first" with 9 strategies
• /improve-codebase-architecture — Deletion test to find shallow modules; surfaces deepening opportunities
• /zoom-out — Quick orientation map of an unfamiliar code area
• /handoff — Compact conversation into a handoff document for a fresh agent session
• /to-prd — Synthesize conversation into a Product Requirements Document
• /to-issues — Break a plan/PRD into vertical-slice issues (HITL/AFK classification)
• /prototype — Throwaway prototypes: terminal app for logic or UI variations for visual
• /write-a-skill — Meta-skill for creating new skills with proper structure

---

Configuration

CLI Reference

agent-notes <command> [options]

Command	Description
install [--local] [--copy] [--reconfigure]	Interactive wizard or direct install
uninstall [--local | --global]	Remove installed components (both scopes by default)
doctor [--local] [--fix]	Check installation health
info	Show status and component counts
list [clis|models|roles|agents|skills|rules|all]	List engine components or installed
set role <role> <model> [--cli <cli>]	Change model for a role (Phase 10+)
regenerate [--cli <cli>]	Rebuild files from state.json (Phase 10+)
validate	Lint source configuration files
memory [add|init|vault|index|ingest|query|lint|list|size|show|reset|export|import] [name]	Manage agent memory
cost-report	Show session cost breakdown by agent and model

Supported platforms

Platform	Install target	Config format
Claude Code	~/.claude/	YAML frontmatter + Markdown prompts
OpenCode	~/.config/opencode/	YAML frontmatter + Markdown prompts
GitHub Copilot	~/.github/	copilot-instructions.md

Quick usage examples

# Interactive install (recommended)
agent-notes install

# Direct install (scripted)
agent-notes install --local --copy

# Check health and fix issues
agent-notes doctor --fix

# List agents, models, or skills
agent-notes list agents
agent-notes list models
agent-notes list skills

# Manage agent memory
agent-notes memory list
agent-notes memory add "Rails enum prefix" \
  "Always use _prefix: true to avoid method name collisions" \
  pattern coder

# Check API key configuration
agent-notes config provider openrouter   # prints "configured" or "no key"

# Reconfigure providers
agent-notes config providers

# Show installation status
agent-notes info

# Validate configuration files
agent-notes validate

Role models

Configure which Claude model powers each role. The default uses Opus 4.6 for reasoning, Sonnet 4.6 for execution, Haiku 4.5 for exploration.

agent-notes set role lead claude-opus-4-20250514
agent-notes set role coder claude-sonnet-4-20250514
agent-notes set role explorer claude-haiku-4-5-20251001

Providers

agent-notes supports multiple API providers for routing requests. Configure providers via:

agent-notes config providers     # interactive wizard
agent-notes config provider <name>      # check if configured (without exposing key)

---

Development

Building and testing

Python 3.10+ required. Create an isolated environment and run tests:

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"      # installs runtime deps + pytest
pytest -q

The test suite automatically builds dist/ before collection (via the pytest_sessionstart hook in tests/conftest.py), so you do not need to run python -m build manually before testing.

Development workflow

One-time setup (choose one):

• Inside a venv: python -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"
• Or expose the CLI globally via pipx (editable): pipx install -e .

Iteration loop:

1. Edit source in agent_notes/data/ (skills, rules, agents, etc.) or Python modules
2. Run agent-notes install to rebuild dist/ and reinstall into your Claude config
3. For a clean reset, run agent-notes uninstall && agent-notes install
4. Run agent-notes validate to lint configuration files
5. Run tests: pytest -q (the suite auto-builds dist/ first via the conftest hook)

Full local reset (one-liner):

pipx uninstall agent-notes && pipx install -e . && agent-notes uninstall && agent-notes install

This command swaps any wheel install for an editable one and clears your Claude config. After this, future edits only need agent-notes install (or agent-notes uninstall && agent-notes install for a clean wipe).

Profiles:

By default, agent-notes install re-runs the interactive wizard and prompts for an optional profile label. To reinstall non-interactively into the same profile, use agent-notes install --profile <label> (e.g. work → installs into ~/.claude-work).

The plugin build scripts (scripts/build-claude-plugin.sh, scripts/build-opencode-plugin.sh) automatically use .venv/bin/python when present, fall back to system python3, and honor a PYTHON= override.

Note: uv is used only in the local development and release workflow (see scripts/release). It is not required to install or use agent-notes — end users should use pipx or pip / venv.

Test structure

• tests/functional/ — Unit tests
• tests/integration/ — Build output and artifact validation
• tests/plugins/ — Plugin artifact validation

Releasing

The release process is automated via scripts/release, which runs exclusively against the project .venv (invoking .venv/bin/python directly, never system python3). The pre-flight phase aborts with a clear error if .venv does not exist or cannot import agent_notes, tomli_w, build, and twine.

Provision the release environment once:

pip install -e ".[dev]" twine

Run the release:

scripts/release              # Full release: tests, build, PyPI upload, git tag, marketplace bundle
scripts/release --dry-run    # Check-only: tests, build, twine check, smoke install; skip upload

The --dry-run flag is useful to validate the entire workflow before committing tags and pushing to PyPI.

Contributing guidelines

When adding new content:

1. Edit source files — all changes go in agent_notes/data/ directory
2. Rebuild and test — agent-notes install rebuilds dist/ and reinstalls; pytest -q auto-builds first
3. Validate — agent-notes validate before committing
4. Keep it generic — remove app-specific references
5. Show examples — include code samples with explanations
6. Stay modular — each skill should be independently usable
7. Stay concise — agent prompts under 60 lines

(Note: python -m build is only needed to produce a release wheel for distribution, not for local development.)

Architecture

agent-notes is a 4-layer engine (domain / registries / services / commands). All extensible content (CLIs, models, roles, agents, skills, rules) lives in agent_notes/data/ as YAML — adding a new CLI/model/role is a YAML drop, no Python changes. Context is loaded in tiers: always-loaded (CLAUDE.md, rules, skill catalog), lazy-loaded (full skill content, agent prompts), and pull-based (memory notes).

See docs/ARCHITECTURE.md, docs/ADD_CLI.md, docs/ADD_MODEL.md, docs/ADD_ROLE.md.

---

Inspired by

• Andrej Karpathy's LLM Wiki — The wiki memory backend implements his compile-once, query-forever knowledge pattern with structured page types and three core operations (ingest, query, lint)
• Matt Pocock's skills repo — Skill format (SKILL.md per directory), failure-mode table (misalignment, verbosity, broken code, architectural degradation), and several core skills (tdd, grill-me, grill-with-docs, improve-codebase-architecture, zoom-out, caveman)

License

MIT