claude-journal-tools
A Claude Code plugin for a personal cognitive-consolidation pipeline:
per-device Stop/SessionStart hooks that push session breadcrumbs to your
own encrypted claude-journal data repo, plus a /journal skill for
resolving consolidation proposals.
Read SECURITY.md first. These hooks push the contents
of your sessions (including transcripts) to a git repo on every session
exit. Your data repo must be private and git-crypt-encrypted. This
tools repo ships no data repo and no key — you supply your own.
Secrets are kept out of the journal by three layers: tool input/output is
dropped entirely (only prose is kept), the remaining prose is scrubbed for
known key shapes (API keys, tokens, PEM private keys, DB URIs, JWTs, the
git-crypt key, …), and everything is git-crypt-encrypted at rest. This is
defense-in-depth, not a guarantee — the encryption is the real boundary;
redaction is best-effort over known patterns. See
SECURITY.md → Secret handling.
Phase 1 (this repo's scope): structural breadcrumbs only — no in-hook LLM.
The central nightly Anthropic-cloud routine (Phase 2) does the LLM-driven
distillation across all devices' breadcrumbs, scheduled with Claude Code's
/schedule (see Phase 2 consolidator).
Documentation
Full docs live in docs/ — built to be read by both humans and
agents, with ASCII diagrams throughout:
| Doc | For |
|---|
| docs/index.md | Overview, mental model, glossary — start here |
| docs/architecture.md | Components, the two repos, three phases, encryption boundary, repo layout |
| docs/data-flow.md | The life of a breadcrumb: capture → consolidate → propagate, with sequence diagrams |
| docs/setup.md | Install, bootstrap, add devices, schedule, verify, troubleshoot |
| docs/reference.md | Env vars, CLI entrypoints, file layout, data formats, hooks, skills |
| docs/agents.md | How an AI agent should use a project wired into claude-journal |
Layout
claude-journal-tools/
├── .claude-plugin/
│ ├── plugin.json plugin manifest (hooks + auto-discovered skills)
│ └── marketplace.json marketplace entry for /plugin install
├── hooks/hooks.json declarative Stop + SessionStart hook wiring
├── tools/journal/ hook implementation, breadcrumb model, push/pull, init
├── tests/journal/ pytest suite (stdlib only, 196 tests across 19 files)
├── scripts/ bootstrap-journal-repo.sh + init-journal-device.sh (data-repo setup)
├── skills/ the /journal slash-command skill (see below)
└── docs/ design specs, phase plans, architecture + reference guides
Skills shipped under skills/:
journal/ — one skill, several /journal actions (per-action flows live in
journal/references/). See Commands for the full list.
Runtime is Python 3.11+, standard library only — no pip install, no
node_modules. The hooks run under whatever python3 is on your PATH.
Requirements
git, git-crypt, python3.11+ on PATHgh (authenticated) — only if you let the bootstrap create the GitHub repo- A private data repo + a git-crypt key. You can create both in one step
with
bootstrap-journal-repo.sh (below), or bring your own.
Install git-crypt:
# Oracle Linux / RHEL: sudo dnf --enablerepo=ol9_developer_EPEL install -y git-crypt
# Debian/Ubuntu: sudo apt-get install -y git-crypt
# macOS: brew install git-crypt
Install (Claude Code plugin)
/plugin marketplace add askenter/claude-journal-tools
/plugin install claude-journal@claude-journal-tools
That registers the Stop and SessionStart hooks and the single /journal
command (see Commands). The hooks won't do anything useful until you
create a data repo and name the device — the two one-time steps below.
Commands
The plugin ships one skill, journal, exposed as the /journal slash command.
It dispatches on the first word; each action's full flow lives under
skills/journal/references/.
