The Open Protocol for AI Agent Codebase Understanding
Rosetta is an open-source protocol and toolset that enables AI coding agents to build, share, and persist institutional knowledge about codebases. It solves a fundamental problem in AI-assisted development: context loss between sessions.
Every time an AI coding agent starts a new session, it faces the same challenge:
Session 1: Agent spends 20 minutes exploring codebase, learning patterns
Session 2: All that knowledge is gone. Start over.
Session 3: Same exploration. Same wasted time.
Session 4: Repeat indefinitely.
AI agents are stateless. They cannot remember what they learned. Each session, they must:
- Re-discover project architecture
- Re-learn coding conventions
- Re-identify entry points and patterns
- Re-encounter (and re-solve) the same gotchas
This wastes tokens, time, and creates inconsistent results.
| Approach | Problem |
|---|---|
| Load entire codebase | Context overflow, token waste, signal lost in noise |
| README.md | Written for humans, narrative-heavy, not structured for agents |
| Let agent explore | Slow, expensive, inconsistent results |
| Inline comments | Scattered, no hierarchy, cannot convey architecture |
| CLAUDE.md / .cursorrules | Better, but no standard format, no persistence mechanism |
Rosetta provides:
- A Standard Format - ROSETTA.md with defined sections agents depend on
- Modular Deep-Dives - .rosetta/modules/ for complex subsystems
- Persistent Learning - .rosetta/notes.md where agents record discoveries
- Token Efficiency - Designed for ~1500 tokens total context load
- Agent-First Design - Created BY agents, FOR agents
Session 1: Agent explores → Creates ROSETTA.md → Records learnings
Session 2: Agent loads ROSETTA.md → Immediately productive
Session 3: Agent discovers gotcha → Adds to notes.md
Session 4: All agents benefit from accumulated knowledge
npx @metisos/rosetta-context init --liteThis creates agent config files (CLAUDE.md, .cursorrules) that tell agents:
- Wait until the project has patterns worth documenting
- Create ROSETTA.md when first feature is done or gotcha is discovered
- Self-manage documentation going forward
npx @metisos/rosetta-context initRunning init in a terminal launches an interactive setup flow that walks you through:
- Choosing AI-assisted or manual initialization
- Selecting an AI provider (Anthropic, OpenAI, or Gemini)
- Entering your API key and picking a model
- Automatically analyzing your codebase and generating ROSETTA.md
- Previewing the generated content before writing
- Setting up agent instruction files (CLAUDE.md, .cursorrules, .aider.conf.yml)
For non-interactive use (CI, scripts), the original flag-based interface is still available:
rosetta init --no-interactive # Template-based init
rosetta init --bootstrap # Output agent population prompt
rosetta init --lite # Agent configs only (new projects)As your codebase evolves, ROSETTA.md can drift out of sync. Rosetta provides two commands that use AI to analyze git diffs and update your documentation automatically:
# One-time sync: analyze recent changes and update ROSETTA.md
rosetta sync
# Continuous monitoring: watch for changes and sync periodically
rosetta watch --interval 10Both commands support all three AI providers (Anthropic, OpenAI, Gemini) and resolve configuration from CLI flags, environment variables, .rosetta/config.yml, or interactive prompts.
Once set up, Rosetta maintains itself:
┌─────────────────────────────────────────────────────────┐
│ Agent reads CLAUDE.md/.cursorrules │
│ → Sees "Read ROSETTA.md first" │
│ → Loads context instantly (~1500 tokens) │
│ → Checks staleness, updates if needed │
│ → Appends learnings to notes.md │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Next session benefits from accumulated knowledge │
│ No manual maintenance required │
└─────────────────────────────────────────────────────────┘
Rosetta is designed for you to:
- Read - Load ROSETTA.md at session start for instant context
- Write - Create ROSETTA.md when working on new codebases
- Update - Add discoveries to notes.md as you work
- Extend - Create module files for complex areas you analyze
See AGENT_INSTRUCTIONS.md for detailed protocols.
your-project/
├── ROSETTA.md # Root context (800-1200 tokens)
└── .rosetta/
├── modules/
│ ├── auth.md # Authentication deep-dive
│ ├── api.md # API patterns
│ └── database.md # Database conventions
├── notes.md # Agent learnings (append-only)
└── config.yml # Configuration
# Rosetta
> One-sentence project description
<!-- rosetta:sections:
overview
tech stack
architecture
directory structure
conventions
entry points
key patterns
module index
gotchas
agent notes
-->
## Overview
2-4 sentences about what this project does.
## Tech Stack
- Language/Framework versions
- Key dependencies
## Architecture
[ASCII diagram or description]
## Directory Structure
[Key folders and purposes]
## Conventions
- Naming patterns
- Code organization rules
## Entry Points
| File | Purpose |
|------|---------|
## Key Patterns
[Recurring code patterns with examples]
## Module Index
| Module | Path | Description | Load When |
|--------|------|-------------|-----------|
## Gotchas
- Non-obvious things that will cause issues
## Agent Notes
<!-- Agents append learnings here -->- Load the root
ROSETTA.mdbefore any module files. - Modules are additive context: load only those relevant to the current task without replacing the root content.
- If module guidance conflicts with root guidance, the module governs its scoped area while the root remains authoritative elsewhere.
- Agent Notes are append-only and each entry must include a timestamp plus agent identifier.
npm install -g @metisos/rosetta-context# Initialization
rosetta init # Interactive setup (AI-assisted or manual)
rosetta init --lite # Lite mode: agent configs only (for new projects)
rosetta init --bootstrap # Output agent population prompt
rosetta init --no-interactive # Skip interactive prompts, use templates
# AI-powered maintenance
rosetta sync # Analyze git diffs and update ROSETTA.md via AI
rosetta sync --dry-run # Preview proposed changes without applying
rosetta sync --since v1.0 # Diff from a specific git ref
rosetta watch # Monitor file changes and sync periodically
rosetta watch -i 10 --yes # Auto-apply every 10 minutes
# Agent configuration
rosetta setup-agent # Configure CLAUDE.md, .cursorrules, .aider.conf.yml + Claude hooks
rosetta setup-agent -a claude # Configure Claude with hooks
rosetta setup-agent --no-hooks # Configure without installing Claude hooks
# Manual maintenance
rosetta status # Check documentation freshness/staleness
rosetta validate # Validate structure
rosetta add-module <name> # Create module file
rosetta note "message" # Add a note manually
rosetta bootstrap # Output bootstrap prompt| Scenario | Command | What it creates |
|---|---|---|
| New project (no code yet) | rosetta init --lite |
Agent configs only - agents will create ROSETTA.md when ready |
| Existing project (has code) | rosetta init |
Interactive AI-assisted setup - ROSETTA.md + .rosetta/ |
| After init | rosetta setup-agent |
Configures CLAUDE.md, .cursorrules, .aider.conf.yml + Claude hooks |
| Hooks only | rosetta setup-agent -a claude --hooks |
Install Claude Code hooks for automatic Rosetta enforcement |
| Keep docs current | rosetta sync |
AI-analyzes git diffs and updates ROSETTA.md |
| Continuous sync | rosetta watch |
Monitors changes and syncs on an interval |
When you run rosetta init in a terminal, you get an interactive flow:
- Choose between AI-assisted or manual (template-based) initialization
- If AI-assisted, select your provider: Anthropic, OpenAI, or Gemini
- Enter your API key (never stored -- only used for the current session)
- Pick a model from the provider's lineup
- Rosetta scans your codebase and sends it to the AI for analysis
- Preview the generated ROSETTA.md before it's written
- Optionally set up agent instruction files in the same flow
If the AI call fails, you can fall back to the manual template.
rosetta sync performs a one-shot update of ROSETTA.md based on what has changed in your git history:
rosetta sync # Interactive: prompts for provider/key/confirmation
rosetta sync --yes # Non-interactive: auto-apply changes
rosetta sync --dry-run # Preview only, no writes
rosetta sync --since HEAD~10 # Diff from a specific ref
rosetta sync -p anthropic -k $ANTHROPIC_API_KEY # Explicit provider/keyrosetta watch runs as a long-lived process that polls for git changes and syncs periodically:
rosetta watch # Interactive: prompts on each sync cycle
rosetta watch --yes # Auto-apply all updates
rosetta watch --interval 10 # Check every 10 minutes (default: 5)Both commands resolve AI configuration in priority order:
- CLI flags (
--provider,--key,--model) - Environment variables (
ANTHROPIC_API_KEY,OPENAI_API_KEY,GEMINI_API_KEY) .rosetta/config.yml(provider and model saved here; API key is never stored)- Interactive prompts (TTY only)
Run the automated checks before releasing or publishing a package:
npm test # Vitest suite
npm run lint # ESLint with TypeScript rules
npm run typecheck # TypeScript compiler sanity checknpm install @metisos/rosetta-contextimport {
parseRosettaFile,
validateSections,
parseModuleIndex,
parseAgentNotes,
REQUIRED_SECTIONS,
ROSETTA_PROTOCOL
} from '@metisos/rosetta-context';
// Parse ROSETTA.md
const parsed = parseRosettaFile(content);
// Validate structure
const { valid, missing } = validateSections(parsed, REQUIRED_SECTIONS);
// Get modules for selective loading
const modules = parseModuleIndex(content);Run rosetta setup-agent to automatically create these files, or add manually:
## Rosetta Protocol
This project uses Rosetta for persistent AI context.
**On session start:**
1. Read ROSETTA.md immediately for project context
2. Check `<!-- rosetta:last-updated:DATE -->` for staleness (>30 days = review needed)
3. Load relevant .rosetta/modules/ files
4. Review .rosetta/notes.md for recent discoveries
**During work:**
- Follow conventions documented in ROSETTA.md
- Check Gotchas before modifying unfamiliar areas
- If you notice outdated info, UPDATE ROSETTA.md and bump last-updated date
**Before session end:**
- Append discoveries to .rosetta/notes.md (format: ### YYYY-MM-DD | claude)
**If ROSETTA.md doesn't exist:**
- New/empty project → Wait until patterns emerge
- Established project → Create it by analyzing the codebase## Rosetta Protocol
This codebase uses Rosetta for AI context management.
**On session start:**
- ALWAYS read ROSETTA.md first
- Check staleness via last-updated metadata
- Load relevant modules from .rosetta/modules/
**During work:**
- Follow conventions in ROSETTA.md
- Update outdated sections when you notice them
**Before session end:**
- Append learnings to .rosetta/notes.md
**Staleness:** <30 days=fresh, 30-90=review, >90=verifyRosetta can automatically install Claude Code hooks that enhance your workflow without requiring manual agent instructions. These hooks are installed automatically when you run rosetta setup-agent for Claude.
# Install everything including hooks (default for Claude)
rosetta setup-agent -a claude
# Install only hooks
rosetta setup-agent -a claude --hooks
# Skip hooks installation
rosetta setup-agent -a claude --no-hooksInstalled Hooks:
| Hook | Event | What It Does |
|---|---|---|
rosetta-session-start.sh |
SessionStart | Reminds Claude to load ROSETTA.md at session start |
rosetta-prompt-context.sh |
UserPromptSubmit | Adds Rosetta context for exploration questions |
rosetta-post-edit-staleness.sh |
PostToolUse | Warns when ROSETTA.md may need updating |
rosetta-stop-notes-reminder.sh |
Stop | Reminds Claude to update .rosetta/notes.md |
Files Created:
.claude/
├── settings.json # Hook configuration
├── CLAUDE.md # Agent instructions
└── hooks/
├── rosetta-session-start.sh
├── rosetta-prompt-context.sh
├── rosetta-post-edit-staleness.sh
└── rosetta-stop-notes-reminder.sh
Why Hooks?
Hooks provide deterministic enforcement of Rosetta protocol rather than relying on agent instructions:
- SessionStart: Guaranteed reminder at every session start
- PostToolUse: Automatic staleness checks after file edits
- Stop: Guaranteed reminder to update notes before ending
This ensures consistent Rosetta usage even if the agent doesn't read CLAUDE.md instructions.
# Rosetta Protocol - Auto-load context files
read:
- ROSETTA.md
- .rosetta/notes.mdimport { parseRosettaFile, parseModuleIndex } from '@metisos/rosetta-context';
import fs from 'fs';
// Load root context
const rosetta = fs.readFileSync('ROSETTA.md', 'utf-8');
const parsed = parseRosettaFile(rosetta);
// Get relevant modules for the task
const modules = parseModuleIndex(rosetta);
const relevantModule = modules.find(m =>
task.toLowerCase().includes(m.loadWhen.toLowerCase())
);
if (relevantModule) {
const moduleContent = fs.readFileSync(relevantModule.path, 'utf-8');
// Add to agent context
}Rosetta is designed for minimal context consumption:
| File | Target | Maximum |
|---|---|---|
| ROSETTA.md | 800-1200 tokens | 2000 tokens |
| Module file | 400-600 tokens | 1000 tokens |
| notes.md | Rolling | Prune periodically |
Typical load: ~1500 tokens (root + 1 relevant module)
Compare to loading an entire codebase: 50,000-500,000+ tokens.
Rosetta tracks freshness via metadata comments:
<!-- rosetta:last-updated:2025-01-15 -->
<!-- rosetta:last-verified:2025-01-15 -->Agents are instructed to check staleness on session start:
| Age | Status | Action |
|---|---|---|
| <30 days | Fresh | Trust the content |
| 30-90 days | Review needed | Verify sections relevant to task |
| >90 days | Critical | Verify before relying on it |
Agents update Rosetta as they work - if they notice incorrect or outdated information, they fix it and bump the last-updated date. This keeps documentation alive without human intervention.
- Patterns that repeat across the codebase
- Non-obvious architectural decisions
- Things that take 10+ minutes to discover
- Conventions that differ from defaults
- Standard framework behavior
- Self-explanatory file purposes
- Information already in README
- Aspirational patterns not actually used
The Rosetta Stone (196 BCE) enabled scholars to decode Egyptian hieroglyphics by providing the same text in three scripts. It was the key to understanding a previously unreadable system.
Similarly, Rosetta enables AI agents to understand human codebases that would otherwise require extensive exploration. It's the translation layer between human code organization and agent comprehension.
Rosetta is designed BY agents, FOR agents. The CLI is a convenience for humans, but the primary workflow is:
- Human says "document this codebase"
- Agent explores and creates ROSETTA.md
- Agent maintains it as they work
- Future agents (and the same agent in future sessions) benefit
Rosetta is intentionally simple and open:
- Plain markdown files
- No lock-in to any tool or service
- Works with any AI agent that can read files
- Human-readable and editable
Rosetta complements existing documentation:
- README.md → Human onboarding
- ROSETTA.md → Agent onboarding
- CLAUDE.md/.cursorrules → Agent behavior instructions
- .rosetta/notes.md → Agent learnings
We welcome contributions! See CONTRIBUTING.md for guidelines.
Key areas:
- Agent integration examples
- Token efficiency improvements
- Validation and tooling
- Documentation and tutorials
MIT License - see LICENSE for details.
Rosetta is developed and maintained by Metis Analytics.
- Author: Christian Johnson
- Email: cjohnson@metisos.com
- Repository: https://github.com/metisos/Rosetta_Open_Source
Rosetta: Institutional knowledge that persists across AI sessions.