AI agent configuration manager for Claude Code and OpenCode.
Configures a Lead agent (Opus) that orchestrates a team of 13 specialized subagents across three model tiers — so Opus plans, Sonnet executes, and Haiku explores.
git clone https://github.com/rubakas/agent-notes.git ~/agent-notes
ln -sf ~/agent-notes/bin/agent-notes /usr/local/bin/agent-notes
agent-notes install # interactive wizard guides you through setup
agent-notes doctorUpdate anytime with cd ~/agent-notes && git pull && agent-notes update.
| Component | Description |
|---|---|
| Skills | 31 on-demand knowledge modules (Rails, Docker, Git, Kamal) |
| Agents | 14 specialized AI subagents with hierarchical model strategy |
| Rules | Global instructions, code quality, and safety guardrails |
| Config | Global instructions for Claude Code, OpenCode, and GitHub Copilot |
agent-notes <command> [options]
| Command | Description |
|---|---|
install |
Interactive installer wizard (CLI, scope, skills selection) |
install --local [--copy] |
Direct install to current project (no wizard) |
uninstall [--local] |
Remove installed components |
update |
Pull latest, rebuild, reinstall |
doctor [--local] [--fix] |
Check installation health |
info |
Show status and component counts |
list [agents|skills|rules|all] |
List installed components |
validate |
Lint source configuration files |
memory [list|size|show|reset|export|import] [name] |
Manage agent memory |
| 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 |
# Interactive install (recommended)
agent-notes install
# Example wizard session:
#
# Which CLI do you use?
# 1) [*] Claude Code
# 2) [*] OpenCode
# Enter numbers to toggle (comma-separated), or press enter for defaults.
# Choice: ← press enter to keep both
#
# Where to install?
# 1) * Global (~/.claude, ~/.config/opencode)
# 2) Local (current project)
# Choice [1]: ← press enter for global
#
# How to install?
# 1) * Symlink (auto-updates when source changes)
# 2) Copy (standalone, allows local customization)
# Choice [1]: ← press enter for symlink
#
# Which skills to include?
# 1) [*] Rails — models, controllers, views, routes, testing (22 skills)
# 2) [*] Docker — Dockerfile, Compose patterns (4 skills)
# 3) [*] Kamal — deployment with Kamal (1 skill)
# 4) [*] Git — commit workflow, conventional commits (1 skill)
# Choice: ← press enter for all
#
# Ready to install:
# CLI: Claude Code + OpenCode
# Scope: Global (~/.claude, ~/.config/opencode)
# Mode: Symlink
# Skills: Rails (22), Docker (4), Kamal (1), Git (1)
# Agents: 13 (Claude Code) + 13 (OpenCode)
# Config: CLAUDE.md, AGENTS.md
# Rules: 2
# Proceed? [Y/n]: Y
# Direct install (scripted, no wizard)
agent-notes install --local
agent-notes install --local --copy
# Check health and fix issues
agent-notes doctor --fix
# Manage agent memory
agent-notes memory list
agent-notes memory show coder
agent-notes memory reset reviewerSpecialized subagents with hierarchical model strategy: Opus 4.6 decides, Sonnet 4 executes, Haiku 4.5 explores.
| Agent | Model | Role |
|---|---|---|
| lead | Opus 4.6 | Plans, delegates, reviews. The only Opus agent. |
| coder | Sonnet 4 | Implements features, fixes bugs, edits files. |
| reviewer | Sonnet 4 | Code quality review. Read-only. |
| security-auditor | Sonnet 4 | Security vulnerability analysis. Read-only. |
| test-writer | Sonnet 4 | Writes tests for any framework. |
| test-runner | Sonnet 4 | Diagnoses and fixes failing tests. |
| system-auditor | Sonnet 4 | Codebase health: duplication, N+1, coupling. Read-only. |
| database-specialist | Sonnet 4 | Schema design, indexes, query performance, migrations. Read-only. |
| performance-profiler | Sonnet 4 | Response times, memory, caching, bundle size. Read-only. |
| api-reviewer | Haiku 4.5 | API design, versioning, error handling, backward compatibility. Read-only. |
| tech-writer | Haiku 4.5 | Documentation: READMEs, API docs, changelogs. |
| devops | Sonnet 4 | Docker, CI/CD, deployment configs. |
| explorer | Haiku 4.5 | Fast file discovery and pattern search. Read-only. |
1. ANALYZE — Lead reviews requirements, explores codebase
2. EXECUTE — Delegates to specialized agents (parallel execution)
3. REVIEW — Quality check by reviewer agents
4. VERIFY — Final validation and integration
You (human)
|
+-- Simple task ------> Main session (direct work)
|
+-- Complex task -----> Lead (Opus 4.6)
+-- Explorer (Haiku 4.5) quick lookups
+-- Coder (Sonnet 4) implementation
+-- Reviewer (Sonnet 4) code review
+-- Test Writer (Sonnet 4) tests
+-- Test Runner (Sonnet 4) fix tests
+-- Security (Sonnet 4) security audit
+-- Auditor (Sonnet 4) codebase health
+-- DB Specialist (Sonnet 4) schema & queries
+-- Perf Profiler (Sonnet 4) performance
+-- API Reviewer (Haiku 4.5) API design
+-- Tech Writer (Haiku 4.5) documentation
+-- DevOps (Sonnet 4) infrastructure
Single source of truth: agent_notes/data/ → build → agent_notes/dist/ → install
- Source — YAML metadata + Markdown prompts
- Build — Generate platform-specific configs
- Dist — Built artifacts ready for installation
- Install — Deploy via symlinks or copy
agent-notes/
├── bin/agent-notes # CLI wrapper (entry point)
├── agent_notes/ # Python implementation
│ ├── __init__.py, cli.py # Core modules
│ ├── VERSION # Package version
│ ├── data/ # Single source of truth
│ │ ├── agents/
│ │ │ ├── agents.yaml # Agent metadata
│ │ │ └── *.md # Agent prompt files
│ │ ├── skills/ # Skill directories
│ │ ├── rules/ # Code quality rules
│ │ └── global.md # Global instructions
│ └── dist/ # Built artifacts
│ ├── claude/, opencode/
│ ├── rules/
│ └── skills/
├── scripts/ # Build/utility scripts
└── tests/ # Test suite
git clone https://github.com/rubakas/agent-notes.git ~/agent-notes
ln -sf ~/agent-notes/bin/agent-notes /usr/local/bin/agent-notes
agent-notes installAfter cloning, agent-notes install launches the interactive wizard to configure your setup.
pip install agent-notes
agent-notes installUse --local --copy for project-specific customizations. The wizard handles local installs too, while --local --copy is for scripted/CI use:
agent-notes install --local --copyThen edit the copied files in .claude/ or .opencode/ directories.
Precedence: Project-level configs replace global versions entirely.
On-demand knowledge modules loaded mid-conversation.
Rails:
rails-models, rails-controllers, rails-routes, rails-concerns, rails-views, rails-views-advanced, rails-view-components, rails-view-components-advanced, rails-helpers, rails-javascript, rails-jobs, rails-mailers, rails-broadcasting, rails-migrations, rails-active-storage, rails-validations, rails-testing-controllers, rails-testing-models, rails-testing-system, rails-style, rails-controllers-advanced, rails-models-advanced, rails-initializers, rails-lib
Docker:
docker-dockerfile, docker-dockerfile-languages, docker-compose, docker-compose-advanced
Kamal:
rails-kamal
Git:
git — git workflow, commit chunking, conventional commit messages
Claude Code / OpenCode:
Use the rails-models skill to help with this association
Load the docker-compose skill for multi-service setup
- Python 3.9+
- PyYAML (
pip install pyyaml)
python3 -m pytest tests/python3 -m agent_notes buildpython3 -m agent_notes validateagent_notes/data/— single source of truth (edit here)agent_notes/dist/— generated output (do not edit)agent_notes/— CLI implementationtests/— test suitescripts/— dev-only tools (release, etc.)
When adding new content:
- Edit source files — all changes go in
agent_notes/data/directory - Run build —
agent-notes buildto generate platform configs - Validate —
agent-notes validatebefore committing - Keep it generic — remove app-specific references
- Show examples — include code samples with explanations
- Stay modular — each skill should be independently usable
- Stay concise — agent prompts under 60 lines
MIT