[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80783":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":16,"stars30d":17,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":22,"hasPages":20,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":35,"readmeContent":36,"aiSummary":37,"trendingCount":16,"starSnapshotCount":16,"syncStatus":38,"lastSyncTime":39,"discoverSource":40},80783,"ccstory","atomchung\u002Fccstory","atomchung","Claude Code usage recap with narrative. ccusage tells you the bill, ccstory tells the story.","https:\u002F\u002Fpypi.org\u002Fproject\u002Fccstory\u002F",null,"Python",40,4,39,38,0,1,2.1,"MIT License",false,"main",true,[24,25,26,27,28,29,30,31,32,33,34],"analytics","ccusage","claude","claude-code","cli","developer-tools","productivity","python","recap","usage-tracking","weekly-report","2026-06-12 02:04:06","# ccstory\n\n> **Your Claude Code week, in plain English.**\n> Reads `~\u002F.claude\u002Fprojects\u002F**\u002F*.jsonl` locally and writes a categorized recap\n> with active hours, costs, and a per-bucket narrative.\n\nSibling to [ccusage](https:\u002F\u002Fgithub.com\u002Fryoppippi\u002Fccusage):\n**ccusage tells you how much you spent · ccstory tells you what on.**\n\n## Who this is for\n\n- People who want to write a weekly status without scrolling scrollback.\n- People who saw a ccusage number and want to know what kind of work those\n  tokens went to.\n- People who do a Sunday-night reflection on what they actually shipped.\n\n## Quick start\n\n```bash\npipx install ccstory\nccstory init\nccstory week\n```\n\nThat's it. `init` is a one-time auto-categorize step that scans your\nrecent sessions; `ccstory week` produces the recap. Full report saves to\n`~\u002F.ccstory\u002Freports\u002Frecap-*.md`.\n\n## Demo\n\n```\n\n╭──────────────── Claude Code Recap · May 5 – 12, 2026 ────────────────╮\n│                                                                      │\n│  ★ Top focus  coding  10.9h  (53% of active time)                    │\n│    ↳ Built \u002Fshow-routine slash command using bash+python to fetch…   │\n│                                                                      │\n│  Active  20.6h  Sessions  74   Output  2.92M                         │\n│  Turns   3,692  Cache     96%  Cost    $1,608                        │\n│                                                                      │\n│  Time by category                                                    │\n│  coding          ███████████████░░░░░░░░░░░░░   10.9h    53%         │\n│  writing         █████████░░░░░░░░░░░░░░░░░░░    6.2h    30%         │\n│  research        █████░░░░░░░░░░░░░░░░░░░░░░░    3.5h    17%         │\n│                                                                      │\n│  Full report → ~\u002F.ccstory\u002Freports\u002Frecap-2026-05-10_2026-05-17.md     │\n│                                                                      │\n╰────────────────────────────── ccstory ───────────────────────────────╯\n```\n\nThe markdown report adds a **2–3 sentence synthesis per bucket** plus\nper-session one-liners. Run with `--llm-narrative` to upgrade per-session\nlines from the instant first-user-msg fallback to claude-polished prose:\n\n```\n### coding\n\nShipped the \u002Fshow-routine slash command end-to-end this week — bash+python\nwrapper to surface scheduled-task output, plus a routine-detail bookmark\nflow after the live debug session on Wednesday.\n\n- 2026-05-10 03:24 · 123m · 212 msg — Built \u002Fshow-routine slash command using\n  bash+python to fetch scheduled-task output and surface it inline.\n- 2026-05-08 12:30 · 67m · 294 msg — Debugged hook race condition in\n  background-task notification dispatch; landed fix in main.\n```\n\n## Usage\n\n### Basic\n\n| Command | What it does |\n|---|---|\n| `ccstory init` | One-time auto-categorize from recent sessions |\n| `ccstory` | Current month so far (default window) |\n| `ccstory week` | Past 7 days |\n| `ccstory month` | Current month |\n| `ccstory 2026-04` | A specific month |\n| `ccstory trend` | Last 8 weeks of sparklines |\n| `ccstory category list` | Show your custom bucket rules |\n| `ccstory category set \u003Cbucket> \u003Ckeyword>…` | Pin a project to a bucket |\n| `ccstory category unset \u003Cbucket> \u003Ckeyword>…` | Remove a keyword from a bucket |\n\n### Advanced\n\n**Window**\n\n| Command | What it does |\n|---|---|\n| `ccstory all` | Entire history |\n| `ccstory trend --weeks 12` | Custom trend range |\n| `ccstory trend --months 6` | By calendar months |\n\n**Narrative depth**\n\n| Flag | What it does |\n|---|---|\n| `--minimal` | Numbers only, no per-session lines |\n| `--llm-narrative` | `claude -p` per-session prose (slow, opt-in) |\n| `--no-aggregate` | Skip the per-bucket synthesis |\n\n**Comparison block** (vs-previous, auto-attached to week\u002Fmonth)\n\n| Flag | What it does |\n|---|---|\n| `--no-compare` | Skip the entire block |\n| `--no-compare-narrative` | Keep numeric deltas, drop the prose |\n\n**Session classification mode**\n\n| Flag | What it does |\n|---|---|\n| `--classify folder` | Folder-name rules only |\n| `--classify content` | `claude -p` reads each session |\n| `--classify hybrid` | User rule wins, else content (default) |\n\n**Export**\n\n| Flag | What it does |\n|---|---|\n| `--for=obsidian` | YAML frontmatter + `[[wikilinks]]` |\n\n**Output format**\n\n| Flag | What it does |\n|---|---|\n| `--format=card` | Force the Rich terminal card (default in a real tty) |\n| `--format=markdown` | Force the full Markdown report to stdout |\n| `--format=auto` (default) | Markdown when `CLAUDECODE=1` or stdout is not a tty (piped \u002F redirected), else card |\n\nThe auto-detect means asking Claude Code \"show me my week with ccstory\" renders an actual Markdown report in the chat instead of ANSI escape codes. The Markdown body is the same content saved to `~\u002F.ccstory\u002Freports\u002F` (`recap-*.md` for the default window, `trend-*.md` for `ccstory trend`), just printed to stdout so the chat can render it inline. In markdown mode all progress \u002F status lines route to stderr, so stdout is a clean Markdown stream you can pipe.\n\n**Refresh (apply rule changes retroactively)**\n\n| Flag | What it does |\n|---|---|\n| `--refresh` | Re-classify cached sessions in this window after a rule edit |\n| `--refresh-all` | Wipe the entire content-classification cache, not just this window |\n\n### Trend output\n\n```\nHours by bucket\ntotal          ▁▄▆▇▃█    16.5h   avg 9.0h   ▲ +183%\ncoding         ▁▂▃▄▁█    10.2h   avg 3.3h   ▲ +1148%\nwriting        ▁▇█▆▁▁     6.2h   avg 4.1h   ▲ +51%\nresearch       ▁▃▅█▆█     3.5h   avg 2.0h   ▲ +75%\n\nOverall\noutput         ▁▁▁▄▁█     3.0M   avg 0.8M   ▲ +260%\ncost           ▁▁▂▃▁█   $1,643   avg $463   ▲ +255%\nburn %         ▁▁▂▃▁█     201%   avg 57%    ▲ +255%\n```\n\nThe `burn %` row is API-equivalent cost as a percentage of your prorated\nmonthly quota. Set `monthly_quota_usd` in `~\u002F.ccstory\u002Fconfig.toml`\n(default $3,500 ≈ Max 20x plan); set to `0` to hide the row.\n\n## Categories\n\nFour default buckets, matched against the project folder name:\n\n| Bucket | Keywords (sample) |\n|---|---|\n| `investment` | investment, stock, portfolio, trading, ticker, etf, finance |\n| `writing` | blog, newsletter, post, docs, content, article |\n| `coding` | app, sdk, cli, plugin, mcp, server, frontend, backend, lib, … |\n| `other` | playground, scratch, sandbox, experiment |\n\nUnmatched projects fall back to `coding`. Customize in\n`~\u002F.ccstory\u002Fconfig.toml`:\n\n```toml\ndefault_bucket = \"coding\"\n\n[categories]\n\"work\"    = [\"company-repo\", \"internal-tool\"]\n\"writing\" = [\"blog\", \"newsletter\", \"essay\"]\n```\n\nFolder rules can be overridden per-session by content (`--classify content` \u002F\n`hybrid`), where one batched `claude -p` call re-buckets sessions by what they\nwere actually about. Results cache in `~\u002F.ccstory\u002Fcache.db` so reruns are\nfree.\n\n## Obsidian export\n\n`ccstory --for=obsidian` swaps the plain markdown for a PKM-vault-ready\nvariant with YAML frontmatter and `[[wikilinks]]`:\n\n```yaml\n---\ndate_start: 2026-05-10\ndate_end: 2026-05-17\nactive_hours: 20.6\ntop_focus: coding\nbuckets: [coding, writing, research]\ncost_usd: 1608.42\noutput_tokens: 2920000\n---\n```\n\nQueryable in Obsidian's Dataview \u002F Bases (`WHERE top_focus = \"coding\"`).\nBucket names with special characters are JSON-quoted so the frontmatter stays\nvalid even for `client: acme, inc`.\n\n## Custom pricing\n\nDefault API list prices snapshot to `2026-01`. The report footer always\nshows the snapshot date so a stale price table can't silently distort cost\nover time. Override per-model in `~\u002F.ccstory\u002Fconfig.toml`:\n\n```toml\n[prices]\nsnapshot_date = \"2026-04\"\n\n[prices.opus]\ninput       = 15.0\noutput      = 75.0\ncache_write = 18.75\ncache_read  = 1.5\n```\n\nPartial overrides are fine — unspecified keys keep their default. Defining a\nbrand-new model (`[prices.custom]`) with only some keys defaults the rest to\n`$0` with a warning so misconfig is loud.\n\n## How ccstory differs from ccusage\n\n|  | [ccusage](https:\u002F\u002Fgithub.com\u002Fryoppippi\u002Fccusage) | **ccstory** |\n|---|---|---|\n| Role | The bill | The story |\n| Active hours (5-min gap heuristic) | — | ✅ |\n| Activity categories | — | ✅ folder rules + content-aware |\n| Per-session narrative | — | ✅ via local `claude -p` |\n| Per-bucket synthesis | — | ✅ |\n| Cross-period narrative | — | ✅ |\n| Local-only \u002F no telemetry | ✅ | ✅ |\n\nPair them — `ccusage monthly` for the spend, `ccstory month` for the\nbreakdown:\n\n```bash\nccusage monthly\nccstory month\n```\n\n## Privacy\n\nEverything runs locally. ccstory never sends your conversation data\nanywhere.\n\n- **Data source**: `~\u002F.claude\u002Fprojects\u002F**\u002F*.jsonl` — Claude Code's own logs.\n- **Narratives**: subprocess-call your *local* `claude -p` (uses your own\n  session \u002F quota, no API key needed, no cost to ccstory).\n- **Cache**: `~\u002F.ccstory\u002Fcache.db` (sqlite, per-session summaries).\n- **Reports**: `~\u002F.ccstory\u002Freports\u002Frecap-*.md`.\n\nNo telemetry, no network calls, no upload buttons. Verify in\n[ccstory\u002Fsession_summarizer.py](ccstory\u002Fsession_summarizer.py).\n\n## Requirements\n\n- **Python 3.11+** and **pipx**\n  (`brew install pipx` on macOS, [other platforms](https:\u002F\u002Fpipx.pypa.io\u002Fstable\u002Finstallation\u002F)).\n- **Claude Code CLI** on `PATH` — required for `--llm-narrative`, content\n  classification, and the cross-period synthesis. Without it, narratives\n  fall back to the first user message and `--classify` falls back to\n  folder rules.\n\n## Implementation notes\n\n- **Time math**: 5-minute gap heuristic — consecutive messages within 5\n  minutes count as active, longer gaps are \"stepped away\". Wall-clock dedup\n  prevents parallel sessions from double-counting. The 5-min cap is a\n  practical floor for \"still at the keyboard\"; comparable across periods\n  even though not precise.\n- **Timezone**: session timestamps are parsed UTC-aware. Window boundaries\n  (`week`, `month`) are local-midnight aligned, so \"this week\" matches the\n  calendar week you actually lived in. `--weeks N` for trend mode does the\n  same.\n- **Cost comparison**: cross-period diffs use **output tokens**, not\n  `total_tokens`. In typical use ~96% of total_tokens is `cache_read`,\n  which inflates with turn count and system prompt size and isn't a stable\n  signal of work done. Output tokens stay comparable month over month.\n- **Pricing**: prices are list prices snapshotted by date (default\n  `2026-01`); the snapshot date renders in every report footer so stale\n  numbers can't sneak past unnoticed.\n\n## Roadmap\n\n- [ ] More export flavors (Logseq, Notion)\n- [ ] Optional PNG card export\n- [ ] `ccstory year` — annual recap (Spotify-Wrapped style)\n- [ ] Git commit \u002F PR correlation per session\n\nSee the [issue tracker](https:\u002F\u002Fgithub.com\u002Fatomchung\u002Fccstory\u002Fissues) for the\nfull backlog.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","ccstory 是一个用于生成 Claude Code 使用情况周报的工具，以简洁易懂的方式呈现开发活动。它通过读取本地 JSONL 文件来提供分类总结，包括活跃时间、成本以及每个类别下的工作内容叙述。项目采用 Python 开发，支持命令行界面操作，能够帮助开发者快速了解一周内的工作重点和成果，适合需要定期回顾或报告工作进展的技术人员使用。用户可以通过简单的几步安装并运行 ccstory，获得详细的周报输出，便于进行个人生产力分析与改进。",2,"2026-06-11 04:02:18","CREATED_QUERY"]