heron-claude-data
Skill1 starsChanged 56 days agoMITView on GitHub
Reference for the on-disk data the Claude Code CLI writes that Heron reads — live session registry (~/.claude/sessions/<pid>.json), transcript JSONL, history.jsonl, settings.json hooks — with field names, units, per-OS paths and pitfalls. Use when parsing, watching or debugging session discovery, status, titles or hook events.
Files
Claude Code data formats Heron depends on
Full detail with examples: docs/ARCHITECTURE.md and docs/HOOKS.md. Quick facts:
Root ~/.claude (macOS/Linux) · %USERPROFILE%\.claude (Windows) ·
CLAUDE_CONFIG_DIR overrides. claude::paths::ClaudePaths::detect() handles it.
Live registry sessions/<pid>.json — pid, sessionId, cwd, name,
status (busy | idle | needs_input | waiting), startedAt /
updatedAt / statusUpdatedAt in milliseconds, version, kind,
entrypoint. Files may outlive dead processes → verify the pid (sysinfo).
Sibling <pid>.<hash>.key is private: never open it.
Transcripts projects/<encoded cwd>/<sessionId>.jsonl — encoding replaces
non-alphanumerics with - (lossy; Windows drive C:\ → C--): take cwd
from the JSON lines. Title = first "type":"user" line whose message.content
(string, or array whose first {"type":"text"} block has text) does not start
with <. Read only the head (64 KB). Skip <sessionId>/subagents/.
History history.jsonl — {display, timestamp(ms), project, sessionId}.
Hooks live under hooks in settings.json; payload fields are in
docs/HOOKS.md. Heron keeps session_id, cwd, transcript_path, hook_event_name,
notification_type, reason, source, result, tool_name, message and discards
tool_input, user_input. Exec-form registration (command + args, no
shell) works on every OS; on Windows the command is powershell.exe running
the installed .ps1.
Debug helpers
ls -la ~/.claude/sessions/ ; python3 -m json.tool ~/.claude/sessions/*.json
ps -o pid=,tty=,command= -p <pid>
tail -3 ~/.claude/history.jsonl
ls "$HOME/Library/Application Support/com.muhammadmusadev.heron/events" # macOSIn this repository24 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ai-video-generationSkill
- claude-md-improverSkill
- code-reviewerSkill
- frontend-designSkill
- heron-buildSkill
- heron-tray-windowsSkill
- minimalist-uiSkill
- product-launch-videoSkill
- rust-engineerSkill
- secure-code-guardianSkill
- seo-auditSkill
- svelte5-initSkill
- svelte5-reviewSkill
- tauri-app-autostartSkill
- tauri-app-notificationSkill
- tauri-app-positionerSkill
- tauri-app-system-traySkill
- tauri-buildSkill
- tauri-securitySkill
- tauriSkill
- tauri-windowSkill
- test-masterSkill
- typescript-proSkill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.