Skip to main content
plugin CX Codex

agent-retro — Claude Code plugin: what it does, how to install

agent-retro is a plugin for Claude Code and Codex that reviews weekly activity in 12 animated slides with stats and four prompt-coaching tips to inspect your own habits.

MIT ★ 1,596 updated 2026-10-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install agent-retro@awesome-codex-plugins
Open on GitHub

What agent-retro does

agent-retro reads local Claude Code and Codex logs, plus ChatGPT or claude.ai exports placed in ~/Downloads. It turns the week into 12 animated slides: 8 usage metrics covering tokens, projects, habits and an archetype, followed by 4 coaching tips tied to the evidence. If the agent can publish pages, you receive a private link; otherwise the result is a local HTML file.

Run /agent-retro:retro to build the weekly review. The command accepts only=codex for source selection and days=14 for a longer lookback; chatgpt explains how to add ChatGPT history, while help lists the options. Files and prior reviews live in ~/agent-retro/, unless AGENT_RETRO_HOME points elsewhere. With too few prompts or judged reactions, the output becomes a short factual recap without coaching or an archetype.

The processing stays local, while the model receives a redacted prompt digest for writing the deck. Redaction covers API keys, tokens, private keys, URL credentials, emails, phone and card numbers, and the home-folder name. The plugin needs macOS or Linux with python3, so it will not run without those prerequisites.

What it helps with

  • review weekly usage across Claude Code and Codex logs
  • compare agent habits with earlier retrospectives
  • spot prompts followed by acceptance or course correction
  • turn observed prompting patterns into a few next-step tips

Example prompts for the agent

  • Run /agent-retro:retro and build my review for this week.
  • Run /agent-retro:retro only=codex days=14 using Codex data from the last 14 days.
  • Use /agent-retro:retro chatgpt to show me how to add my ChatGPT history.

How to install agent-retro

Plugin marketplace

/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install agent-retro@awesome-codex-plugins

Step by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own

Questions about agent-retro

How do I install agent-retro in Claude Code?

Run /plugin marketplace add hashgraph-online/awesome-codex-plugins, then run /plugin install agent-retro@awesome-codex-plugins.

What does agent-retro do?

It turns Claude Code and Codex activity into a weekly 12-slide review with usage stats and four evidence-linked coaching tips. The review is saved as local HTML or published as a private page.

What does agent-retro need to run?

It requires macOS or Linux with python3. The agent may also need approval to read ~/.claude, ~/.codex and ~/Downloads, and to write to ~/agent-retro.

Source text

agent-retro · MIT
# Agent Retro

A weekly look back at how you use AI coding agents. It's 12 animated slides: **8 fun stats** about your week (tokens, projects, habits, your archetype), with **4 bite-sized coaching tips** woven in, each right after the stat it comes from. The tips show what's working and one small thing to try.

## Install

The same plugin folder works in Claude Code and in Codex (the Codex CLI, or Codex in the ChatGPT desktop app). Each install step takes a local folder (such as `~/Downloads/agent-retro`), a GitHub `owner/repo`, or a git URL.

**Claude Code**

```
/plugin marketplace add <path-or-git-url-of-this-folder>
/plugin install agent-retro@agent-retro
```

From a terminal, the same two steps are `claude plugin marketplace add …` and `claude plugin install agent-retro@agent-retro`.

**Codex / ChatGPT**

```
codex plugin marketplace add <path-or-git-url-of-this-folder>
codex plugin add agent-retro@agent-retro
```

## Use

In Claude Code, run `/retro` (or `/agent-retro:retro` if another plugin also has a `/retro`). In Codex, ask for it ("build my Agent Retro") or mention the skill, `$agent-retro:retro`. Options go after the command or in the same message:

| Option | What it does |
|---|---|
| *(none)* | Build this week's Retro from every source it finds: Claude Code and Codex logs on your machine, plus any ChatGPT or claude.ai export in `~/Downloads` |
| `only=codex` | Use only the listed sources (comma-separated: `claude-code`, `codex`, `chatgpt`, `claude-ai`) |
| `days=14` | Look back 14 days instead of 7 |
| `chatgpt` | Ways to add your ChatGPT history, with prompts you can paste |
| `help` | Show the options |

With fewer than eight human prompts or eight judged reactions, you get a short factual recap with no coaching or archetype.

It takes a few minutes. You get a private link if your agent can publish pages, or a local HTML file otherwise. Everything is saved in `~/agent-retro/`, so next week's Retro can compare against this one and rotate in new slides. Set `AGENT_RETRO_HOME` to use a different folder.

If Codex's sandbox blocks reading `~/.claude`, `~/.codex` or `~/Downloads`, or writing to `~/agent-retro`, approve the request when it asks. The Retro needs those folders to count your week and remember past ones.

## Privacy

- **Everything is read locally:** `~/.claude/projects`, `~/.codex`, and export zips you put in Downloads.
- **Your agent sees redacted text only.** It reads a redacted digest of your prompts to write the deck, and sends that to its model provider as it would for any other task. Nothing else leaves your machine, except the finished deck if you publish it as a *private* page that only you can open until you share it.
- **Sensitive text stays out of the deck.** Quotes are short. Before the deck writer sees your prompts, the scripts redact API keys, tokens, private keys, credentials in URLs, password-like strings, emails, phone and card numbers, and your home-folder name.
- **Raw prompt text stays in memory.** Preparation creates a unique private build directory and writes only redacted measurements. Interrupted runs do not leave raw transcript files.

## How the coaching works

After each prompt, the Retro looks at your *next* message. "OK, now…", "let's build that" or "great" counts as landed. "That's not…", "why didn't you…" or "stop" counts as a course-correction. It compares prompts that did something (set a boundary, said what done looks like, shared the why) with those that didn't, and explains the pattern using well-known prompting practices. These are signals, not grades. Every tip is framed as "even better", never "wrong".

Requires macOS or Linux, with `python3` available.

© Matt Herz · MIT · hashgraph-online/awesome-codex-plugins

Similar plugins

All plugins for Agent setup: memory, context, orchestration →

From the same set391

The whole set →
agentops agentops is a plugin for Claude Code and Codex that provides engineering practices and skills for coding agents to plan tasks via BDD, test code, and preserve context across sessions. CX Codex ★ 1,596repo stars codiris-agentizer The codiris-agentizer plugin turns a website into a Next.js agent interface with chat, voice calls, and interactive products. Use it to generate and deploy the project. CX Codex ★ 1,596repo stars agentic-readiness-assessment The agentic-readiness-assessment plugin for Claude Code and Codex checks whether an agent can work independently in a repository, then returns a 14-area scorecard and prioritized fixes. CX Codex ★ 1,596repo stars agent-workflow-system agent-workflow-system — a plugin with seven skills that turn vague ideas into step-by-step plans, guide projects from start to handoff, and restore context after closing the window. CX Codex ★ 1,596repo stars agent-harness-skills agent-harness-skills — a plugin for Claude Code and Codex that builds the repository control layer agents need: entry points, boundaries, validation, runtime traces, and delivery records. CX Codex ★ 1,596repo stars agent-guard The agent-guard plugin for Claude Code and Codex intercepts tool inputs and outputs to block secrets. It runs locally by default without telemetry. CX Codex ★ 1,596repo stars agent-deck agent-deck binds MCP services, credentials, and playbooks to a workspace session. Use it when the same working process must carry across Claude Code and Codex. CX Codex ★ 1,596repo stars agency-continuity-audit The agency-continuity-audit plugin for Claude Code and Codex checks persistent agent workspaces, separating evidence of goals, state, and recovery from self-reports. CX Codex ★ 1,596repo stars

Project sponsors

Companies that keep this analytics open