{
  "markdown": "# Afterpaths\n\n**Smarter with every session, automatically.**\n\nExtract rules from what worked. Track what didn't. Find the best models for your stack.\n\nYou're running Claude Code, Cursor and Codex, but which model actually works best for your stack? What approaches lead to breakthroughs vs. expensive dead ends? How do you stop your agents from making the same mistakes?\n\nAfterpaths gives you a single view across all your AI coding tools: compare what's working, capture discoveries as rules, and guide your agent team away from costly diversions.\n\n![Afterpaths Demo](demo.gif)\n\n**What you're seeing:**\n1. **`ap audit`** — Overview of your sessions, models used, and rule status\n2. **`ap show 5 --raw`** — Raw session transcript (the messy JSONL data, made readable)\n3. **`ap show 5`** — LLM-generated summary extracting discoveries, dead ends, and decisions\n4. **`head .claude/rules/gotchas.md`** — Rules automatically extracted and ready for Claude's next session\n\n## The Problem\n\nYou're managing multiple agents - retaining critical context and learning from sessions is painful:\n\n- **Repeated mistakes** — Your agents hit the same gotchas. Three weeks later, same dead end, same wasted tokens.\n- **No cross-tool visibility** — Is Opus actually better than Sonnet for your codebase? Is Cursor outperforming Claude Code? You're guessing.\n- **Rules are tedious** — After a costly diversion, the last thing you want is to write a CLAUDE.md rule. So you don't. And the knowledge evaporates.\n- **Sessions vanish** — Session content is obscurely logged and hard to extract. Then it's often auto-deleted after 30 days. That breakthrough architecture decision? Context gone.\n\nAfterpaths captures sessions across tools, surfaces what's working, and generates rules automatically—so your agents learn from every session, and you retain all your rich session context.\n\n## How It Works\n\n```\nYour Sessions                      Afterpaths\n───────────────                    ────────────────────────────────────\n\nClaude Code  ──► ap log      ──► Browse sessions across IDEs\nCursor           ap stats    ──► Analytics: tokens, activity, errors\nCodex            ap summarize──► Session summaries (what happened)\n                 ap rules    ──► Rule files (what to remember)\n                 ap search   ──► Find past discussions & discoveries\n                                    │\n                                    ▼\n                           .claude/rules/ · .cursor/rules/\n                                    │\n                                    ▼\n                           Your next session is smarter\n```\n\n## Quick Start\n\n```bash\npip install afterpaths\n\n# Navigate to your project (rules are project-specific)\ncd ~/code/your-project\n\n# Run audit to see what you have\nap audit\n```\n\nThe audit shows your sessions across all tools, model performance, and whether you have rules set up. No API key needed.\n\n**From there, the recommended flow:**\n\n```bash\n# 1. Browse sessions and find significant work\nap log\n\n# 2. Summarize important sessions (requires API key)\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\nap summarize 1\n\n# 3. Extract rules from summaries → .claude/rules/\nap rules\n\n# 4. Search across past sessions\nap search \"database schema\"\nap search \"auth\" --deep    # also search raw transcripts\n\n# 5. Track ongoing performance\nap stats\nap stats --daily\n```\n\n> **Tip:** `ap` is the short alias for `afterpaths`. Both work identically.\n\nAll commands support `--json` for structured output (e.g., `ap log --json`, `ap show 1 --json`, `ap search \"query\" --json`).\n\nSee [docs/commands.md](docs/commands.md) for the full command reference and recipes.\n\n## From Session to Rules\n\n**Real example: A bug causing 76 missing sessions became a rule that prevents the same mistake.**\n\nWhile building afterpaths, sessions for a project weren't showing up. The path (let's call it) `/Users/Code/foo_bar` was being decoded as `/Users/Code/foo/bar`. After investigation, we discovered Claude Code uses lossy path encoding—both `/` and `_` become `-`.\n\n**The summary captured the discovery:**\n\n```markdown\n## Discoveries\n\n- **Claude Code's path encoding is lossy**: Project paths in `~/.claude/projects/`\n  are encoded by replacing `/` with `-`, but underscores are ALSO converted to\n  hyphens. Three different paths encode identically:\n  - `/Users/Code/foo_bar` → `-Users-Code-foo-bar`\n  - `/Users/Code/foo-bar` → `-Users-Code-foo-bar`\n  - `/Users/Code/foo/bar` → `-Users-Code-foo-bar`\n```\n\n**`ap rules` extracted it into `.claude/rules/gotchas.md`:**\n\n```markdown\n- **Claude Code lossy path encoding**: Claude Code encodes project paths by\n  replacing both `/` and `_` with `-`, making them indistinguishable when\n  decoding. When decoding, try underscore variants alongside hyphen variants\n  at each greedy step, preferring longer segments (single directories) over\n  nested paths.\n  _Source: 91b1ffbc_\n```\n\nNext time Claude works on path decoding in this codebase, it already knows about the lossy encoding—no need to rediscover it.\n\n## Why Afterpaths\n\n| Without | With Afterpaths |\n|---------|-----------------|\n| Discover gotcha, forget to document it | `ap summarize` captures it with full context |\n| Hit the same issue 3 weeks later | Rule in `.claude/rules/` prevents it |\n| No idea what's working | `ap stats` shows tokens, sessions, error rates |\n| Sessions scattered across IDEs | `ap log` unified view across Claude + Cursor |\n| Learnings siloed per tool | Rules sync to `.claude/rules/` and `.cursor/rules/` |\n\n## What Gets Extracted\n\n| Category | What it captures | Example |\n|----------|------------------|---------|\n| **Dead Ends** | Approaches that failed | \"Don't use X because Y\" |\n| **Decisions** | Architectural choices | \"We chose Redis over Postgres because...\" |\n| **Gotchas** | Non-obvious warnings | \"Watch out for X when doing Y\" |\n| **Patterns** | Techniques that worked | \"For X, use pattern Y\" |\n\nEach rule includes source session references so you can trace back to the original context.\n\n## Supported Tools\n\n| Tool | Status | Location |\n|------|--------|----------|\n| Claude Code | ✅ Ready | `~/.claude/projects/*.jsonl` |\n| Cursor | ⚠️ Partial | `~/Library/Application Support/Cursor/User/workspaceStorage/` |\n| Codex CLI | ✅ Ready | `~/.codex/` |\n\n### Known Limitations\n\n**Cursor sessions:** the adapter reads several known chat/composer formats from\n`state.vscdb` (including `workbench.panel.aichat.view.aichat.chatdata`,\n`composer.composerData`, and `allComposers`), but Cursor changes its storage\nschema often and some sessions will return `Entries: 0` even when the\n`state.vscdb` file is present. When this happens, `ap show <ref> --raw` and the\n`afterpaths_show_session` MCP tool emit a warning rather than silently\nreturning empty. The raw file is untouched — if you need that session, opening\n`state.vscdb` directly with `sqlite3` will still work.\n\nTool provenance features (`ap show --artifacts`, commit tracing, file\nactivity) only cover sessions whose entries the adapter can read.\n\n## MCP Server\n\nAfterpaths includes an MCP server that puts session history directly into your agent's tool list. Instead of relying on agents to discover the CLI, the MCP server makes session search, summaries, and rules available as native tools.\n\n```bash\n# Install with MCP support\npip install afterpaths[mcp]\n\n# Add to Claude Code\nclaude mcp add afterpaths -- afterpaths-mcp\n\n# Or run directly\npython -m afterpaths.mcp_server\n```\n\n**Tools exposed:**\n\n| Tool | Description |\n|------|-------------|\n| `afterpaths_list_sessions` | List recent sessions for context recovery |\n| `afterpaths_show_session` | Read session summaries and transcripts |\n| `afterpaths_show_artifacts` | Show artifacts ledger: files written/edited with provenance |\n| `afterpaths_summarize` | Generate summaries for sessions |\n| `afterpaths_search` | Search across past sessions (auto-escalates to transcripts on 0 summary hits) |\n| `afterpaths_get_rules` | Get extracted rules (dead ends, decisions, etc.) |\n\nOnce configured, agents can ask \"have we seen this before?\" or \"what were the dead ends?\" and get answers from your session history.\n\n## Privacy\n\n- **All local** — Summaries and rules stay in your project\n- **Your API key** — Uses your Anthropic/OpenAI key\n- **Read-only** — Never modifies your source code\n- **Gitignored** — `.afterpaths/` excluded by default\n\n## Storage\n\n```\nyour-project/\n├── .afterpaths/           # Summaries (gitignored)\n│   ├── summaries/\n│   └── meta.json\n├── .claude/\n│   └── rules/             # Generated rules (commit these!)\n│       ├── dead-ends.md\n│       ├── gotchas.md\n│       └── patterns.md\n└── src/\n```\n\n### Hand-edited notes in rule files\n\nEach rule file is split into a **manual section** (preserved across `ap rules` runs) and an **auto section** (regenerated each run):\n\n```markdown\n# Gotchas: Things to Watch For\n\n<!-- afterpaths:manual:start -->\n_Add project-specific notes here — preserved across `ap rules` runs._\n<!-- afterpaths:manual:end -->\n\n<!-- afterpaths:auto:start -->\n> Auto-generated by `afterpaths distill` | Updated: 2026-04-21 12:00\n> Sources: 3 session(s)\n\n## Rules\n\n- **Some extracted rule**: ...\n  _Source: abc12345_\n<!-- afterpaths:auto:end -->\n```\n\nPut hand-curated rules or project-specific reminders between the `manual:start` / `manual:end` markers — they'll survive every `ap rules` run. Content *outside* those markers (and outside the recognized boilerplate) blocks the run as a safety check. Pass `--force` to overwrite anyway, or wrap the content in manual markers to preserve it.\n\nIf you're upgrading from an earlier version and your rule files contain only auto-generated content, markers are inserted automatically on the next `ap rules` run with an empty manual section — no action required.\n\n## Roadmap\n\n- [x] Claude Code session parsing\n- [x] Cursor session support\n- [x] Session analytics (tokens, errors, daily trends)\n- [x] LLM summarization\n- [x] Automatic rule extraction\n- [x] Multi-target export (Claude, Cursor)\n- [x] Codex CLI support\n- [x] Cross-session search (`ap search`)\n- [x] JSON output (`--json` flag)\n- [x] MCP server for agent integration\n- [ ] Semantic search across sessions\n- [ ] Benchmarking and productivity insights\n\n## License\n\nMIT\n\n---\n\n*Manage your AI coding agents. Learn what works. Stop repeating mistakes.*\n\n<!-- mcp-name: io.github.burnssa/afterpaths -->\n",
  "bytes": 10353,
  "sha": "ccff031c62c9b557548d94549e5bfb0fb341c7d42ad0165ea7d855b792babc01",
  "repo_slug": "burnssa/afterpaths",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_burnssa_afterpaths_0fae9507/readme"
}