@franshjy/dbrief 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# Dbrief
+
+Dbrief extracts daily session activity into artifacts for generating Markdown daily notes.
+Currently only support Codex, with Opencode and Claude Code support on the way.
+
+## How does Dbrief work?
+
+Dbrief obtains your sessions from your coding agents' respective directories and extracts logs based on the selected date.
+You can install the skill to the agent of your choice, and you can either:
+- Edit the skill to modify the location, writing style, or note layout
+- Or just use it directly with the default layout.
+
+## Installation
+
+```bash
+npm install -g @franshjy/dbrief
+```
+
+## Quick Start
+
+```bash
+cd ~/your-project
+dbrief install              # Install dbrief-note skill
+dbrief extract              # Extract today's sessions
+codex "Generate my daily note from dbrief_2026-06-04.json"
+```
+
+The CLI produces the JSON artifact. Codex uses the installed skill to turn that artifact into a portable Markdown note with `Summary`, `Projects`, and `Other` sections.
+
+## Commands
+
+### extract
+
+Extract session data for a date or date range.
+
+```bash
+dbrief extract                              # Today -> ./dbrief_YYYY-MM-DD.json
+dbrief extract --date 2026-06-01            # Specific date -> ./dbrief_2026-06-01.json
+dbrief extract --from 2026-05-01            # From date to today
+dbrief extract --to 2026-06-01              # From earliest to date
+dbrief extract --from 2026-05-01 --to 2026-06-01  # Date range -> current directory by default
+dbrief extract --out ./output.json          # Custom output path
+```
+
+**Options:**
+- `--date <date>`: Target date (today, yesterday, or YYYY-MM-DD)
+- `--from <date>`: Start date for range extraction
+- `--to <date>`: End date for range extraction
+- `--out <path>`: Output file (single day) or directory (range)
+- `--codex-dir <path>`: Codex data directory (default: ~/.codex)
+
+### install
+
+Install the dbrief-note skill to `.codex/skills/dbrief-note/` in the current directory. The skill currently writes Markdown only and is currently only installed on Codex, though you can manually install the skill on any coding agent you want.
+
+```bash
+dbrief install
+```
+
+### inspect
+
+Inspect a generated artifact. Defaults to pretty-printed JSON. Use `--format summary` for a compact overview.
+
+```bash
+dbrief inspect --input ./dbrief_2026-06-04.json
+dbrief inspect --input ./dbrief_2026-06-04.json --format summary
+```
+
+**`--format summary`** prints a compact breakdown: date, timezone, and per-project thread/message/context counts.
+
+**Options:**
+- `--input <path>`: Input artifact file (required)
+- `--format summary`: Print a compact summary instead of full JSON
+
+## Artifact Schema
+
+Output is minified JSON. Messages are tuples of `["u"|"a", content_string]`.
+
+```json
+{
+  "date": "2026-06-04",
+  "timezone": "Asia/Bangkok",
+  "projects": [
+    {
+      "project_key": "C:/dev/projects/codex-trails",
+      "threads": [
+        {
+          "title": "How does codex store compressed context?",
+          "branch": "master",
+          "context": [],
+          "messages": [
+            ["u", "How does codex store compacted context?"],
+            ["a", "Three compaction paths exist: local, remote v1, remote v2..."],
+            ["u", "Can I extract the summary from JSONL?"],
+            ["a", "Only `replacement_history` is persisted. The summary is ephemeral."]
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Extraction modes:**
+- **Full** (no compaction): `context` = `[]`, `messages` = all messages
+- **Hybrid** (compacted): `context` = replacement_history, `messages` = post-compaction messages
+
+## Note Writing Contract
+
+The primary output of `dbrief extract` is JSON. The final daily note is generated by Codex using the installed `dbrief-note` skill.
+
+The default Markdown structure is:
+
+```markdown
+# {date}
+
+## Summary
+
+## Projects
+
+## Other
+```
+
+## Dev Setup
+
+```bash
+npm install
+npm run build
+npm link (to access the dbrief command)
+```
+
+## License
+
+This project is licensed under the GNU Affero General Public License v3.0
+(`AGPL-3.0`). See [LICENSE](./LICENSE) for the full text.
+
+If you run a modified version of this project as a network service, AGPL
+requires you to make the corresponding source code available to those users.