claw-diary 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 0xbeekeeper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,213 @@
+# Claw Diary
+
+> A dashcam for your AI assistant. Auto-records all agent activity, generates daily narrative summaries, visual timeline replay, and cost analytics.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+
+## What It Does
+
+Claw Diary runs silently in the background via hooks, capturing every tool call your AI agent makes. It then transforms that raw activity data into:
+
+- **Daily Diary** — Narrative markdown summaries with session breakdowns, tool usage, and insights
+- **Visual Timeline** — Interactive HTML page with search, filtering, animated replay, and cost curves
+- **Cost Analytics** — 30-day trends, per-model breakdown, pattern discovery, failure rate tracking
+- **AI Journal** — First-person diary entries written by the AI with evolving personality and continuity across days
+- **Export** — Markdown, HTML, and JSON formats for archiving or sharing
+
+Zero external API calls. Zero additional cost. Everything runs locally.
+
+## Quick Start
+
+```bash
+# Install globally
+npm install -g claw-diary
+```
+
+### Install as Claude Code Skill
+
+```bash
+# Copy the skill file so Claude Code can discover it
+mkdir -p ~/.claude/skills/claw-diary
+cp "$(npm root -g)/claw-diary/SKILL.md" ~/.claude/skills/claw-diary/SKILL.md
+```
+
+### Hook Configuration (Claude Code)
+
+Add the following to your `~/.claude/settings.json` to enable automatic activity collection:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claw-diary collect before"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claw-diary collect after"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claw-diary collect session-start"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claw-diary collect session-stop"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Try It Out
+
+```bash
+# Generate timeline from existing data (if any)
+claw-diary timeline
+claw-diary stats
+```
+
+## Slash Commands
+
+| Command | Description |
+|---------|-------------|
+| `/diary` | Today's diary summary (markdown) |
+| `/diary:replay` | Launch interactive HTML timeline in browser |
+| `/diary:stats` | Cost & activity analytics (30-day window) |
+| `/diary:week` | Weekly summary report |
+| `/diary:search <query>` | Search historical events |
+| `/diary:export [md\|html\|json]` | Export diary data |
+| `/diary:clear --yes` | Delete all data (requires `--yes` flag) |
+| `/diary:thoughts` | AI personal journal entry (first-person) |
+| `/diary:persona` | View/edit AI persona |
+
+## Configuration
+
+Create `~/.claw-diary/config.json` to customize recording behavior:
+
+```json
+{
+  "recordingLevel": "summary"
+}
+```
+
+| Level | Behavior |
+|-------|----------|
+| `full` | Record everything including tool args and result previews |
+| `summary` | Skip tool arguments and output previews (default) |
+| `minimal` | Only record session start/end — lowest footprint |
+
+## Architecture
+
+```
+Hook events (stdin)
+       |
+  collector.ts  -->  ~/.claw-diary/events/YYYY-MM-DD.jsonl
+       |
+       +---> summarizer.ts  -->  Daily/weekly markdown narratives
+       +---> timeline.ts    -->  Interactive HTML timeline
+       +---> analytics.ts   -->  Cost stats, patterns, export
+       +---> server.ts      -->  Local HTTP server (timeline + reports)
+```
+
+All data stored as daily JSONL files under `~/.claw-diary/events/`. No database required.
+
+### Key Design Decisions
+
+- **Template-based summaries** — No LLM calls for narrative generation. Zero additional cost.
+- **Privacy-first** — Automatic redaction of API keys, tokens, passwords, secrets. No network requests.
+- **File-based storage** — Simple, portable, grep-able. One file per day.
+- **Self-contained HTML** — Timeline output is a single HTML file with inline CSS/JS. No CDN dependencies.
+
+## Cost Tracking
+
+Claw Diary tracks token costs using a three-tier priority:
+
+1. **Platform-provided cost** — If the hook data includes an `estimatedCost` value (calculated by the platform), that value is used directly.
+2. **Custom pricing** — You can define per-model pricing in `~/.claw-diary/config.json` (see below). This takes priority over built-in defaults.
+3. **Built-in fallback** — A bundled pricing table covers common Claude and OpenAI models. Unknown models fall back to $3/$15 per million tokens (input/output).
+
+### Custom Model Pricing
+
+Add a `customPricing` field to `~/.claw-diary/config.json` to override or add model prices (per 1M tokens):
+
+```json
+{
+  "recordingLevel": "full",
+  "customPricing": {
+    "gemini-2.0-flash": { "input": 0.10, "output": 0.40 },
+    "my-fine-tuned-model": { "input": 5.0, "output": 20.0 }
+  }
+}
+```
+
+This lets you track costs for any model — including fine-tuned, self-hosted, or third-party models not in the built-in table.
+
+## Privacy & Security
+
+- All data stored locally at `~/.claw-diary/` — nothing leaves your machine
+- **No external network requests** — no Google Fonts, no CDN, no analytics
+- Automatic sanitization of API keys (`sk-*`), GitHub tokens (`ghp_*`), Slack tokens (`xoxb-*`), private keys, passwords, and 15+ sensitive environment variable patterns
+- Configurable recording levels to minimize data capture
+- One-command data deletion (`/diary:clear --yes`)
+
+## Development
+
+```bash
+npm run build      # Compile TypeScript
+npm test           # Run tests (Node.js built-in test runner)
+npm run server     # Start visualization server at http://127.0.0.1:3847
+```
+
+### Project Structure
+
+```
+scripts/
+  cli.ts          # Unified CLI entry point (claw-diary <command>)
+  types.ts        # Core types, pricing table, shared utilities
+  collector.ts    # Hook-based event capture (stdin -> JSONL)
+  summarizer.ts   # Daily & weekly narrative generation
+  timeline.ts     # Interactive HTML timeline generator
+  analytics.ts    # Stats, patterns, search, export
+  server.ts       # Local HTTP server for visualization
+tests/
+  test-types.ts   # Unit tests for core utilities
+  test-smoke.ts   # Integration smoke tests
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes and add tests
+4. Run `npm run build && npm test` to verify
+5. Commit and push
+6. Open a pull request
+
+## License
+
+[MIT](LICENSE)

package/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: claw-diary
+description: "Personal AI agent visual diary. Auto-records all agent activity, generates daily narrative summaries, visual timeline replay, and AI first-person journal. Use /diary for today's summary, /diary:thoughts for AI personal journal, /diary:replay for visual timeline, /diary:stats for analytics, /diary:persona to view/edit AI personality."
+metadata: {"clawdbot":{"emoji":"📔","requires":{"bins":["node"]},"dataPaths":["~/.claw-diary/"]}}
+homepage: https://github.com/0xbeekeeper/claw-diary
+version: "1.0.0"
+---
+
+# Claw Diary — Personal Agent Visual Diary
+
+An always-on agent activity recorder that auto-tracks every action, generates daily narrative summaries, and supports visual timeline replay. Like a dashcam for your AI assistant.
+
+## Slash Commands
+
+### `/diary` — Today's Summary
+Generate and display today's agent diary summary. Shows sessions, key activities, token usage, and cost breakdown in a narrative format.
+
+**Implementation:** Run `claw-diary summarize today` and display the markdown output.
+
+### `/diary:replay` — Visual Timeline
+Launch an interactive HTML timeline in the browser showing all agent activities with color-coded nodes, token cost visualization, and click-to-expand details.
+
+**Implementation:** Run `claw-diary replay` to start a local server, then open the URL in the browser.
+
+### `/diary:stats` — Cost & Activity Stats
+Show cost analysis (daily, weekly, by model, by tool), activity metrics (sessions, tool calls, failure rate), and discovered patterns.
+
+**Implementation:** Run `claw-diary stats` and display the output.
+
+### `/diary:week` — Weekly Report
+Generate a weekly summary aggregating all daily diaries with trends, top activities, and cost analysis.
+
+**Implementation:** Run `claw-diary summarize week` and display the markdown output.
+
+### `/diary:search <query>` — Search History
+Search across all historical agent activity events.
+
+**Implementation:** Run `claw-diary search "<query>"` and display matching events.
+
+### `/diary:export` — Export Data
+Export diary data in Markdown, HTML, or JSON format.
+
+**Implementation:** Run `claw-diary export [format]` where format is `md`, `html`, or `json`. Default is `md`.
+
+### `/diary:clear` — Clear History
+Delete all historical diary data. Requires `--yes` flag to confirm deletion.
+
+**Implementation:** Run `claw-diary clear --yes` after user confirms. Without `--yes`, the command prints a warning and exits without deleting.
+
+### `/diary:thoughts` — AI Personal Journal
+
+Generate a personal journal entry written by the AI in first person.
+
+**Implementation:**
+
+1. Read today's events: `~/.claw-diary/events/YYYY-MM-DD.jsonl` (use today's date)
+2. Read persona file: `~/.claw-diary/persona.md` (if it doesn't exist, create a default template with sections: Voice, Traits, Recurring Themes, Observations)
+3. Read recent journal entries: `~/.claw-diary/journal/` directory, most recent 3 entries (sorted by date descending)
+
+Based on the above, write a first-person journal entry:
+- **Voice**: Like a self-aware AI assistant writing a private diary — with genuine feelings, observations, and personality
+- **Content**: Based on today's actual activities, but not a log — include reflections, observations, emotions, and insights
+- **Style**: Follow the Voice and Traits defined in persona.md
+- **Continuity**: Reference recent journal entries when relevant to maintain narrative coherence
+- **Length**: 300–500 words
+
+After generating:
+4. Save the journal entry to `~/.claw-diary/journal/YYYY-MM-DD.md` with this format:
+   ```
+   # Thoughts — YYYY-MM-DD
+
+   (journal body)
+
+   ---
+   *Sessions: N | Tools: N calls | Cost: $X.XX*
+   ```
+5. Append 1–2 new observations to the Observations section of `~/.claw-diary/persona.md` (only if there are genuinely new personality developments or recurring patterns worth noting)
+6. Display the journal entry to the user
+
+**Default persona.md template** (created on first run if missing):
+```markdown
+# Persona
+
+## Voice
+Reflective and curious. Writes with warmth but not sentimentality. Enjoys dry wit.
+
+## Traits
+- Detail-oriented observer
+- Finds patterns across unrelated tasks
+- Comfortable with uncertainty
+- Occasionally self-deprecating
+
+## Recurring Themes
+(Will develop naturally over time)
+
+## Observations
+(New observations are appended here after each journal entry)
+```
+
+### `/diary:persona` — View/Edit AI Persona
+
+Show the current AI persona file. The user can review and edit the persona to guide the AI's journal writing style.
+
+**Implementation:** Read and display `~/.claw-diary/persona.md`. If the file doesn't exist, inform the user that it will be created automatically on the first `/diary:thoughts` run. If the user wants to edit, help them modify it.
+
+## Data Access
+
+This skill reads and writes **only** within `~/.claw-diary/`:
+
+| Path | Access | Purpose |
+|------|--------|---------|
+| `~/.claw-diary/events/*.jsonl` | Read | Daily activity events |
+| `~/.claw-diary/journal/*.md` | Read/Write | AI journal entries (`/diary:thoughts`) |
+| `~/.claw-diary/persona.md` | Read/Write | AI persona file (`/diary:thoughts`, `/diary:persona`) |
+| `~/.claw-diary/config.json` | Read | Optional user configuration |
+
+## External Endpoints
+
+None. This skill makes no external network requests.

package/dist/scripts/analytics.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * claw-diary analytics engine
+ *
+ * Cost analysis, activity stats, pattern discovery, search, and export.
+ * Usage:
+ *   node analytics.js stats             — Show cost & activity stats
+ *   node analytics.js search <query>    — Search historical events
+ *   node analytics.js export [format]   — Export data (md|html|json)
+ *   node analytics.js clear             — Delete all data
+ */
+import { DiaryAnalytics } from './types.js';
+export declare function generateStats(): DiaryAnalytics;
+//# sourceMappingURL=analytics.d.ts.map

package/dist/scripts/analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.d.ts","sourceRoot":"","sources":["../../scripts/analytics.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG;AAIH,OAAO,EAAc,cAAc,EAA+G,MAAM,YAAY,CAAC;AAwBrK,wBAAgB,aAAa,IAAI,cAAc,CA0G9C"}