claude-logbook 1.0.0__tar.gz

claude_logbook-1.0.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Elvis Claros Castro
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

claude_logbook-1.0.0/NOTICE

@@ -0,0 +1,5 @@
+claude-logbook
+Copyright 2026 Elvis Claros Castro
+
+This product includes software developed by Elvis Claros Castro.
+Licensed under the Apache License, Version 2.0 (see LICENSE).

claude_logbook-1.0.0/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: claude-logbook
+Version: 1.0.0
+Summary: Browse your Claude Code sessions and project memories: a terminal table and a self-contained HTML page.
+Author: Elvis Claros Castro
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/ElvisClaros/claude-logbook
+Project-URL: Issues, https://github.com/ElvisClaros/claude-logbook/issues
+Keywords: claude,claude-code,cli,jsonl,sessions,transcripts,memory,logbook
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Spanish
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# claude-logbook
+
+Browse every [Claude Code](https://claude.com/claude-code) conversation stored on
+your machine — as a table in your terminal, or as a single self-contained HTML
+page you open with a double click.
+
+**[Español](README.es.md)** · English · No dependencies, standard library only.
+
+> **The CLI, its output and its help text are in Spanish.** Only this README is
+> translated. The command reads local files and never sends anything anywhere.
+
+```
+  #   SESIÓN                           RUTA                    FECHA  CUÁNDO     MSG    DUR ID
+  1 | Migrar el pool de conexiones a … /home/ana/api           16 ago hoy          4     9m 5d10f1ee
+  2 | Timeouts intermitentes en el he… /home/ana/api           16 ago hoy          2     3m 0f60f37a
+  3 | Reescribir el buscador con Fuse… /home/ana/web           15 ago ayer         7    18m b69c1fc2
+  4 | por qué tarda tanto npm ci       /home/ana/web           13 ago hace 3d      1    <1m d4d2a5be
+  5 | sesión abierta sin mens… [vacía] /home/ana/infra         08 ago hace 1sem    —    <1m e0a4300e
+
+5 sesiones · 3 proyectos · -s <nº> para leer una
+```
+
+## ⚠️ Your transcripts are private
+
+`--json` and `--html` write out **the full text of your conversations and your
+projects' memories**: prompts,
+answers, file paths, branch names. The generated `sesiones.html` is a complete,
+readable copy of everything you ever typed into Claude Code.
+
+Do not commit it, do not upload it, do not paste it into a bug report. The
+repository's `.gitignore` already excludes `sesiones.html` and `data.json`, but
+the file itself is yours to look after.
+
+## Install
+
+Requires Python 3.9 or newer. Nothing else.
+
+```bash
+pipx install git+https://github.com/ElvisClaros/claude-logbook
+```
+
+Or with pip, or straight from a clone:
+
+```bash
+pip install git+https://github.com/ElvisClaros/claude-logbook
+
+git clone https://github.com/ElvisClaros/claude-logbook && cd claude-logbook
+python3 -m claude_logbook          # no install needed
+```
+
+## Usage
+
+```bash
+claude-logbook                     # table of every session
+claude-logbook docker              # filter by title, path or branch
+claude-logbook -s 3                # read conversation #3 from the table
+claude-logbook -s 5d10f1ee         # same, by UUID prefix
+claude-logbook -g "port already"   # search inside the conversations
+claude-logbook -r 3                # print the command that resumes it
+eval "$(claude-logbook -r 3)"      # …or resume it right away
+claude-logbook --html --open       # build sesiones.html and open it
+claude-logbook -m                  # your projects' memories
+```
+
+The number is the row's position **in the table you are looking at**, so if you
+filtered, repeat the filter to read that row:
+
+```bash
+claude-logbook docker              # shows 3 results
+claude-logbook docker -s 2         # reads the 2nd of those three
+```
+
+### Options
+
+| Flag | What it does |
+| --- | --- |
+| `-s`, `--show REF` | Print a conversation (table index or UUID prefix). |
+| `-r`, `--resume REF` | Print `cd <project> && claude --resume <uuid>`. |
+| `-g`, `--grep TEXT` | Keep sessions whose transcript contains `TEXT`. |
+| `-p`, `--project PATH` | Keep sessions whose project path contains `PATH`. |
+| `-n`, `--limit N` | Only the N most recent. |
+| `-E`, `--hide-empty` | Hide sessions with no messages. |
+| `--no-tools` | Hide tool calls when printing a conversation. |
+| `--no-pager` | Do not pipe the conversation through `$PAGER`. |
+| `--no-color` | Plain output (`NO_COLOR` is honoured too). |
+| `--json` | Dump every session as JSON on stdout. |
+| `--html [FILE]` | Build the standalone page (default `sesiones.html`). |
+| `--template FILE` | Use your own template for `--html`. |
+| `--open` | Open whatever `--html` produced in your browser. |
+| `--no-cache` | Ignore the cache and re-parse everything. |
+| `-m`, `--memory` | Work on memories instead of sessions. |
+| `--type KIND` | With `-m`: filter by `project`, `user`, `feedback` or `reference`. |
+| `--check` | With `-m`: audit indexes, links and origin sessions. |
+
+### Deleting sessions
+
+Irreversible, and it asks first unless you pass `-y`:
+
+```bash
+claude-logbook --delete-empty --dry-run   # what it would delete
+claude-logbook --delete-empty             # delete the empty ones
+claude-logbook -D 101 -D e0a4300e         # delete specific sessions
+claude-logbook -p /tmp --delete-empty     # only the empty ones of that project
+```
+
+It warns you about any file written in the last five minutes: that is very
+likely a session Claude Code still has open, and it will write it back on exit.
+
+## Project memory
+
+Claude Code stores per-project memories in
+`~/.claude/projects/<project>/memory/`: one `.md` per memory, with YAML
+frontmatter and a markdown body, plus a `MEMORY.md` that indexes them.
+
+**The index is the only part loaded into context when a session starts.** A
+memory that is on disk but missing from `MEMORY.md` stops being remembered even
+though the file is still there, so the gap between the two is worth watching.
+
+`-m` swaps the noun and reuses the verbs you already know:
+
+```bash
+claude-logbook -m                  # table of memories
+claude-logbook -m docker           # search name, description and body
+claude-logbook -m --type user      # only one kind
+claude-logbook -m -s 3             # read memory #3
+claude-logbook -m -s deadlock      # same, by name
+claude-logbook -m -p /home/u/proj  # only one project's
+```
+
+Claude picks the kind when it writes them: **project** is work in progress,
+**user** is who you are and how you work, **feedback** is corrections you gave,
+and **reference** points at external resources.
+
+### Auditing
+
+```bash
+claude-logbook -m --check
+```
+
+Exits 1 if it finds anything, and reports:
+
+- projects with memories but no `MEMORY.md`;
+- memories missing from their project's index;
+- index entries pointing at a file that no longer exists;
+- `[[...]]` links with no target — the format allows them, they mark something
+  not written yet;
+- memories whose origin session is gone from disk: the memory outlived the
+  conversation that created it.
+
+### Deleting memories
+
+Same as sessions: irreversible, asks first unless you pass `-y`. Besides
+removing the file it drops its line from `MEMORY.md`, so the index is not left
+pointing at nothing.
+
+```bash
+claude-logbook -m -D 3 --dry-run   # what it would delete
+claude-logbook -m -D deploy-docker # delete that memory
+```
+
+## The HTML page
+
+`claude-logbook --html` produces one file with the data embedded inside it. No
+server, no network, no build step — copy it to another machine and it still
+works.
+
+- Search by title, path, branch or UUID, and optionally inside the transcripts,
+  with the matching snippet shown under the row.
+- Filter by project, sort by any column, hide empty sessions.
+- Click a row to read the conversation in a side panel, with code fences,
+  headings and one line per tool call.
+- Copy the `cd … && claude --resume …` command for any session.
+- Light and dark themes, with a toggle that remembers your choice.
+- Each session gets its own URL fragment, so `sesiones.html#5d10f1ee-…` opens
+  that conversation directly.
+- Keyboard: `/` or `Ctrl`+`K` focuses the search box, `Esc` clears it or closes
+  the reader.
+
+Dates are relative to **when the data was read**, not to your clock, so "today"
+keeps meaning what it meant when you generated the page.
+
+## How it works
+
+Claude Code writes one JSON Lines file per conversation:
+
+```
+~/.claude/projects/<url-encoded-project-path>/<uuid>.jsonl
+```
+
+(`CLAUDE_CONFIG_DIR` is honoured if you moved that directory.)
+
+Every line is an event. `claude-logbook` walks them and keeps the conversation
+itself — your messages, Claude's replies, and a one-line summary per tool call
+such as `Bash: git status`. It deliberately **drops tool results**, which are
+about 95% of the bytes on disk and almost none of the meaning.
+
+A few details worth knowing:
+
+- **Titles.** Claude generates one during the session (`ai-title` events); the
+  most recent wins. Without one, the first thing you typed is used instead —
+  which is visible, because it starts in lowercase or reads like a loose
+  question.
+- **Empty sessions** were opened but never received a message: a cancelled
+  `/resume`, a `/login`.
+- **Non-interactive** sessions are `claude -p` with something piped into stdin —
+  typically a `git diff` to write a commit message. They are detected as a
+  single very long message with no back and forth.
+- **Inferred paths.** A cancelled `/resume` never records a `cwd`, and the
+  directory name cannot be reversed reliably (both `/` and `.` encode as `-`),
+  so the path is borrowed from another session of the same project and flagged.
+- **Sidechains** (subagent transcripts) are skipped.
+- **Cache.** Parsed sessions are cached in
+  `$XDG_CACHE_HOME/claude-logbook/cache.json`, keyed by size and mtime. It is
+  only an optimisation: if it is missing, stale or corrupt, everything is
+  re-parsed. `--no-cache` skips it entirely.
+
+### JSON schema
+
+`--json` prints an object with two arrays: `s` holds the sessions, most
+recently active first, and `m` the memories, most recently modified first.
+
+```json
+{"s": [ … ], "m": [ … ]}
+```
+
+Keys are one letter because the same records are embedded in the HTML, where
+the cost is paid once per record.
+
+Each session in `s`:
+
+| Key | Meaning |
+| --- | --- |
+| `id` | Session UUID (the file name). |
+| `p` | Project path (`cwd`). |
+| `b` | Git branch. |
+| `t` | Title. |
+| `ai` | `true` if Claude generated the title. |
+| `n` | `true` if it looks like a non-interactive `claude -p`. |
+| `e` | `true` if the session has no messages. |
+| `i` | `true` if `p` was inferred from a sibling session. |
+| `f` / `l` | First and last event timestamps (ISO 8601). |
+| `d` | Duration in minutes. |
+| `u` / `a` | Message counts, yours / Claude's. |
+| `k` | File size in KB. |
+| `v` | Claude Code version. |
+| `c` | Transcript: `[{"r": "u"｜"a"｜"t", "x": text}]`. |
+
+Each memory in `m`:
+
+| Key | Meaning |
+| --- | --- |
+| `name` | Name from the frontmatter (or the filename, if missing). |
+| `file` | File name, with extension. |
+| `p` | Project path. |
+| `desc` | Description from the frontmatter. |
+| `ty` | Kind: `project`, `user`, `feedback` or `reference`. |
+| `src` | UUID of the session that wrote it, when declared. |
+| `body` | Markdown body, without the frontmatter. |
+| `ln` | `[[...]]` links found in the body. |
+| `k` | Size in KB. |
+| `l` | Last modified (ISO 8601). |
+| `ix` | `true` if listed in `MEMORY.md`. |
+| `hix` | `true` if the project has a `MEMORY.md`. |
+
+## Development
+
+```bash
+git clone https://github.com/ElvisClaros/claude-logbook && cd claude-logbook
+python3 -m unittest discover -s tests -t .
+```
+
+The tests build fake `.jsonl` trees in a temporary directory and never touch
+`~/.claude`. There is nothing to install: no test runner, no dependencies.
+
+| Module | Responsibility |
+| --- | --- |
+| `claude_logbook/sessions.py` | Parsing the `.jsonl` files, the cache, filters. |
+| `claude_logbook/memory.py` | Reading the `memory/*.md` files and auditing them. |
+| `claude_logbook/terminal.py` | ANSI colours, the table, printing a conversation. |
+| `claude_logbook/webpage.py` | Embedding the data into the template. |
+| `claude_logbook/cli.py` | Argument parsing and the commands. |
+| `claude_logbook/template.html` | The page: markup, styles and the browser-side code. |
+
+## License
+
+[Apache-2.0](LICENSE).