Tip
This is the easiest way to keep your AGENTS.md in sync with your codebase's best practices and patterns.
Scale your team, be it agents 🤖 or humans 👩💻, by keeping track of your team's development patterns 📚
AGENTS.md is the new source of truth for your repo's structure, best practices, decisions and taste.
Don't let a good agnetic session go to waste. Commit it.
graph LR
A[Code]:::code --> B[Iterate]:::iterate
B --> C["/session-commit"]:::commit
C --> D["Scale Team<br>🤖 👩💻"]:::scale
D --> A
classDef code fill:#81C784,color:#1B5E20,stroke:#66BB6A
classDef iterate fill:#90CAF9,color:#0D47A1,stroke:#64B5F6
classDef commit fill:#FFCC80,color:#E65100,stroke:#FFB74D
classDef scale fill:#CE93D8,color:#4A148C,stroke:#BA68C8
- Quickstart
- How It Works
- Cross-Tool Compatibility
- Why This Exists
- What Does This Plugin Do?
- What Gets Captured
- Star History
Codex reads AGENTS.md natively — no plugin needed.
Install the /session-commit prompt:
mkdir -p ~/.codex/prompts
curl -sO --output-dir ~/.codex/prompts https://raw.githubusercontent.com/olshansk/agent-md/main/commands/session-commit.mdRun it:
/prompts:session-commitUpdate it:
curl -sO --output-dir ~/.codex/prompts https://raw.githubusercontent.com/olshansk/agent-md/main/commands/session-commit.mdRemove the command
rm ~/.codex/prompts/session-commit.mdAdd the marketplace:
/plugin marketplace add olshansk/agent-mdInstall the plugin:
/plugin install agent-md@olshansk
[!NOTE] After installing, restart Claude Code for the plugin to take effect.
Use the plugin:
/agent-md:session-commitUpdate the plugin:
/plugin update agent-md@olshansk[!TIP] Configure the plugin to auto update. Run
/plugin→ Select Marketplaces → Choose olshansk → Enable auto-update
Remove the plugin
Uninstall the plugin:
/plugin uninstall agent-mdRemove the marketplace (optional)
/plugin marketplace remove olshanskInstall the extension:
gemini extensions install https://github.com/olshansk/agent-md[!NOTE] After installing, restart Gemini CLI for the extension to take effect.
Run the command:
/session-commitUpdate the extension:
gemini extensions install https://github.com/olshansk/agent-mdRemove the extension
gemini extensions uninstall agent-mdOpenCode reads AGENTS.md natively — no plugin needed.
Install the /session-commit command:
mkdir -p ~/.config/opencode/commands
curl -sO --output-dir ~/.config/opencode/commands https://raw.githubusercontent.com/olshansk/agent-md/main/commands/session-commit.mdRun it:
/session-commitUpdate it:
curl -sO --output-dir ~/.config/opencode/commands https://raw.githubusercontent.com/olshansk/agent-md/main/commands/session-commit.mdRemove the command
rm ~/.config/opencode/commands/session-commit.mdThis plugin maintains AGENTS.md as the single source of truth for project knowledge. Each AI coding tool reads its own instruction file, and they all point back to AGENTS.md:
| Tool | Reads | Points to |
|---|---|---|
| Claude Code | CLAUDE.md |
AGENTS.md |
| OpenCode | AGENTS.md (native) |
— |
| Codex CLI | AGENTS.md (native) |
— |
| Gemini CLI | GEMINI.md |
AGENTS.md |
Run /agent-md:session-commit in Claude Code (or /session-commit in other tools) at the end of a coding session. The plugin captures learnings and writes them to AGENTS.md, making them available to every tool and every team member.
The key insight: AGENTS.md is tool-agnostic. A session captured in Claude Code benefits OpenCode, Codex, Gemini, and any human reading the repo.
graph TD
A[AGENTS.md]:::agents
B[CLAUDE.md]:::claude --> A
C[CODEX.md]:::codex --> A
D[GEMINI.md]:::gemini --> A
E[Claude Code]:::tool --> B
F[OpenCode]:::tool --> A
G[Codex CLI]:::tool --> A
H[Gemini CLI]:::tool --> D
classDef agents fill:#FFCC80,color:#E65100,stroke:#FFB74D
classDef claude fill:#EDAB91,color:#6D3A2A,stroke:#D4896E
classDef codex fill:#80CBC4,color:#004D40,stroke:#4DB6AC
classDef gemini fill:#9FA8DA,color:#283593,stroke:#7986CB
classDef tool fill:#BDBDBD,color:#212121,stroke:#9E9E9E
The plugin ensures these files exist in your project:
AGENTS.md— the source of truth (all learnings go here)CLAUDE.md— minimal pointer for Claude CodeCODEX.md— minimal pointer for Codex CLI (optional, since Codex readsAGENTS.mddirectly)GEMINI.md— minimal pointer for Gemini CLI- OpenCode reads
AGENTS.mddirectly — no pointer file needed
Every one of your coding sessions likely results in some best practice, pattern, or other tidbit of knowledge worth remembering for future sessions.
The only way to scale a team of human software engineers or fleet of agents is to disseminate best practices.
Best of all, we have AGENTS.md for this now!
graph TD
A[Read existing AGENTS.md]:::action --> B[Analyze session learnings]:::action
B --> C[Propose changes with diff format]:::action
C --> D{User confirms?}:::decision
D -->|Yes| E[Apply changes to AGENTS.md]:::action
D -->|No| F[Done - no changes]:::outcome
E --> G[Create CLAUDE.md / GEMINI.md / CODEX.md if missing]:::action
G --> H[Prompt to run /init]:::outcome
classDef action fill:#90CAF9,color:#0D47A1,stroke:#64B5F6
classDef decision fill:#FFCC80,color:#E65100,stroke:#FFB74D
classDef outcome fill:#81C784,color:#1B5E20,stroke:#66BB6A
| Category | Examples |
|---|---|
| Patterns | Code style, naming conventions |
| Architecture | Why things are structured a certain way |
| Gotchas | Pitfalls discovered during development |
| Debugging | What to check when things break |