this repo has no description
1# Worklog Project
2
3A tool that summarizes Claude Code and OpenAI Codex CLI sessions into a daily worklog.
4
5## Architecture
6
7- **CLI** (`src/cli/`): Process sessions, serve web UI
8- **Core** (`src/core/`): Session parsing, DB, LLM summarization
9- **Web** (`src/web/`): React frontend + Express API
10- **DB**: SQLite at `data/worklog.db`
11
12Run `bun dev` for development (hot reload on :5173, API on :3456).
13
14### Multi-Source Session Support
15
16Both Claude Code and Codex CLI sessions are supported:
17- **Claude**: `~/.claude/projects/{encoded-path}/*.jsonl`
18- **Codex**: `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`
19
20Projects are unified by git root - same repo worked on with both CLIs shows as one project. The `source` column in `session_summaries` tracks origin.
21
22## Key Design Decisions
23
24### Session Filtering
25
26Only sessions with actual code changes (Write/Edit/NotebookEdit/MultiEdit) are included. Exploration-only sessions (just Read/Grep/Glob) are skipped entirely. This is intentional - reading code is not an accomplishment.
27
28### Prompting for Outcomes
29
30The LLM prompts explicitly say "OUTCOMES only, never exploration" to prevent summaries like "explored codebase" or "reviewed project structure". Focus is on what was BUILT, FIXED, or CHANGED.
31
32## Gotchas
33
34- **Haiku double-encoding**: Even with `mode: 'tool'`, Haiku sometimes returns double-encoded JSON where the entire response is a string with escaped quotes. The `tryRecoverMalformedResponse()` function in `summarizer.ts` handles this by regex-extracting fields from the malformed output. If you see "Session details unavailable", check the error logs for recoverable data.
35- Kill any stale process on port 3456 before running `bun cli serve`
36- **Monorepo path detection**: Claude's path encoding is lossy (`/` → `-`), so `taper-calculator-apps-web` could mean a dashed name or nested dirs. The code probes the filesystem right-to-left to find which interpretation exists, then uses git root as canonical project.
37- **Codex tool types**: Codex uses both `function_call` AND `custom_tool_call` in response_items. The `apply_patch` tool uses `custom_tool_call`, while `shell_command` uses `function_call`. Both must be handled in `codex-reader.ts`.
38- **Old Codex format (pre-October 2025)**: Sessions before October 2025 have a completely different structure - no `type: 'session_meta'` wrapper, no timestamps on individual entries, and `apply_patch` embedded in shell command heredocs. The working directory must be extracted from the `environment_context` message content, not metadata. See `codex-detector.ts` and `codex-reader.ts` for the dual-format handling.
39- **API/db default layering**: When changing default values (like query limits), check BOTH the db function AND the API handler. The API handler in `api.ts` can override db.ts defaults with its own fallback values.
40
41## Summary Quality
42
43Summaries should focus on **capabilities/value**, not code artifacts:
44- Good: "added multi-dose scheduling (backend, frontend)"
45- Bad: "built dose-splitter module, extended type system, created FrequencySelector"
46
47The `(backend, frontend)` scope suffix shows breadth of work without listing every file. Keep prompts aggressive about consolidation - Haiku tends toward verbosity.
48
49## Commands
50
51```bash
52bun cli process # Process new sessions (also regenerates affected daily summaries)
53bun cli process --week this # Process this week only
54bun cli regenerate # Regenerate missing daily summaries
55bun cli regenerate --force # Regenerate ALL daily summaries
56bun dev # Dev server with hot reload (:5173)
57bun cli serve # Production server (:3456)
58```