{"id":50810746,"url":"https://github.com/weak-fox/agent-retrospective","last_synced_at":"2026-06-13T04:33:30.427Z","repository":{"id":360615579,"uuid":"1250953111","full_name":"weak-fox/agent-retrospective","owner":"weak-fox","description":"Local-first Codex skill and CLI for incremental AI agent session retrospectives, reflection reports, and multi-agent session analysis.","archived":false,"fork":false,"pushed_at":"2026-05-27T06:04:02.000Z","size":31,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T07:20:34.002Z","etag":null,"topics":["agent-retrospective","ai-agent","codex","codex-skill","developer-tools","local-first","productivity","session-analysis"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/weak-fox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-27T05:39:52.000Z","updated_at":"2026-05-27T06:04:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/weak-fox/agent-retrospective","commit_stats":null,"previous_names":["weak-fox/agent-retrospective"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/weak-fox/agent-retrospective","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weak-fox%2Fagent-retrospective","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weak-fox%2Fagent-retrospective/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weak-fox%2Fagent-retrospective/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weak-fox%2Fagent-retrospective/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/weak-fox","download_url":"https://codeload.github.com/weak-fox/agent-retrospective/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weak-fox%2Fagent-retrospective/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34272603,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-retrospective","ai-agent","codex","codex-skill","developer-tools","local-first","productivity","session-analysis"],"created_at":"2026-06-13T04:33:27.324Z","updated_at":"2026-06-13T04:33:30.417Z","avatar_url":"https://github.com/weak-fox.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"**Language:** English | [简体中文](README.zh-CN.md)\n\n# agent-retrospective\n\nExplicit-only Codex skill and local-first CLI for maintaining a private LLM wiki over AI agent session history.\n\n`agent-retrospective` turns local agent sessions into a continuously updated reflection knowledge base. Raw sessions stay where each agent stores them; this project maintains the private wiki layer: indexes, structured summaries, run reports, weekly reports, yearly reports, and a long-lived synthesis.\n\n## Why This Exists\n\n- Incremental review: process new or changed sessions without rereading everything.\n- Explicit trigger: run only when the user names `$agent-retrospective`.\n- Agent-native analysis: guide the workflow without restricting how agents inspect files.\n- Local-first privacy: raw sessions stay local and generated reports live in a private data directory.\n- Wiki layer: maintain `index.md`, `log.md`, reports, and structured summaries so future runs have context.\n\n## Quick Start\n\nInstall or copy this folder into your Codex skills directory, then invoke:\n\n```text\n$agent-retrospective\n```\n\nYou can also run the CLI directly:\n\n```bash\npython3 src/agent_retrospective/cli.py\n```\n\nUse a custom private data location:\n\n```bash\nAGENT_RETROSPECTIVE_ROOT=/path/to/private-data python3 src/agent_retrospective/cli.py\n```\n\nBy default, the CLI uses the fixed private data directory `.agent-retrospective-data/` under the current workspace. This is code behavior, not just prompt guidance. Override it only when you want a different private data repository.\n\nThe built-in source profiles are tried by default:\n\n- Codex: `~/.codex`\n- Claude Code: `~/.claude/projects`\n- Cursor: `~/.cursor`\n- OpenCode: `~/.opencode`\n\nOnly existing session directories are scanned. You can narrow the run:\n\n```bash\npython3 src/agent_retrospective/cli.py --source codex\n```\n\n## Install In Agents\n\nCodex:\n\n```bash\nmkdir -p ~/.codex/skills\ncp -R /path/to/agent-retrospective ~/.codex/skills/agent-retrospective\n```\n\nClaude Code:\n\n```bash\ncp AGENTS.md CLAUDE.md /path/to/project/\n```\n\nCursor / OpenCode:\n\n- Add this repository to the project or user-level agent context.\n- Point the agent at `SKILL.md` and `scripts/run_review.sh`.\n- Invoke the workflow explicitly as `agent-retrospective`.\n\n## Repository Split\n\nRecommended setup:\n\n- Public skill repository: `agent-retrospective`\n- Private generated-data repository: `agent-retrospective-data`\n\nThe private data repository can include local paths, project names, timelines, remote environment clues, and personal workflow summaries. Keep it private.\n\n## Directory Layout\n\n```text\nagent-retrospective/\n├── AGENTS.md\n├── CLAUDE.md\n├── SKILL.md\n├── README.md\n├── README.zh-CN.md\n├── agents/\n│   └── openai.yaml\n├── scripts/\n│   └── run_review.sh\n└── src/\n    └── agent_retrospective/\n        ├── __init__.py\n        └── cli.py\n```\n\nGenerated private data is ignored by this repository:\n\n```text\n.agent-retrospective-data/\n├── index.md\n├── log.md\n├── agent_retrospective.md\n├── reports/\n│   ├── runs/YYYY-MM-DD-HHMM.md\n│   ├── weekly/YYYY-Www.md\n│   └── yearly/YYYY.md\n└── state/\n    ├── state.json\n    ├── session_summaries.jsonl\n    └── review_runs.jsonl\n```\n\n## How Incremental Review Works\n\nThe CLI maintains fingerprints in `state/state.json` and structured summaries in `state/session_summaries.jsonl`.\n\nA session is keyed by source, session id, and path. This keeps copied or forked sessions from overwriting each other. A session is treated as changed when its stored fingerprint differs from the current file metadata. Older sessions with newly appended user input are therefore picked up as changes. Active sessions that are still changing are skipped temporarily without advancing their stored fingerprint, so they remain pending for a later stable run.\n\nEach run refreshes:\n\n- `index.md`: agent-readable map of the private wiki\n- `log.md`: human-readable maintenance timeline\n- `agent_retrospective.md`: long-lived synthesis\n- `reports/runs/YYYY-MM-DD-HHMM.md`: current run report\n- `reports/weekly/YYYY-Www.md`: current week report\n- `reports/yearly/YYYY.md`: current year report\n\nWhen a run crosses into a new week or year, the previous week or year report is refreshed once more as a finalized period summary.\n\n## Privacy Model\n\n- Do not copy raw session files into this repository.\n- Do not commit generated data to the public skill repository.\n- Secret-like strings are redacted before summary output.\n- Generated data is intentionally detailed and should live in a private repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweak-fox%2Fagent-retrospective","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweak-fox%2Fagent-retrospective","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweak-fox%2Fagent-retrospective/lists"}