Skip to content

Commit d2c4aa0

Browse files
djdarcydjdarcy
committed
v0.1.4: Enhanced logging and developer tooling
Logging improvements: - Grep entries show glob filter: {Grep: pattern | "*.tsx" } (closes #6) - Write/Edit show content preview: {Write: "path" ← "content..." } (closes #7) - Agent context framework for subagent tool identification (ref #5) - Session resume now writes new SESSION START marker (closes #9) Developer tools: - sync-versions.py: version management with --bump, --set, --dev-refresh - docs/dev.md: contributor guide with testing workflows - Known quirks documented in installation.md - Added EnterPlanMode, ExitPlanMode, TaskOutput, TaskStop to tool categories (ref #8) - Fixed pre-commit hook regex patterns for .log/.tmp/.bak file detection
1 parent ce05057 commit d2c4aa0

10 files changed

Lines changed: 972 additions & 15 deletions

File tree

‎.claude-plugin/marketplace.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
33
"name": "dazzle-claude-plugins",
4-
"version": "0.1.3",
4+
"version": "0.1.4",
55
"description": "DazzleML Claude Code plugins",
66
"owner": {
77
"name": "DazzleML",
@@ -11,7 +11,7 @@
1111
{
1212
"name": "session-logger",
1313
"description": "Real-time session logging, command history, and auto-naming for Claude Code",
14-
"version": "0.1.3",
14+
"version": "0.1.4",
1515
"source": "./",
1616
"category": "developer-tools"
1717
}

‎.claude-plugin/plugin.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "session-logger",
3-
"version": "0.1.3",
3+
"version": "0.1.4",
44
"description": "Real-time session logging, command history, and auto-naming for Claude Code",
55
"author": {
66
"name": "djdarcy",

‎CHANGELOG.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,41 @@ All notable changes to claude-session-logger will be documented in this file.
55
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
77

8+
## [0.1.4] - 2026-02-01
9+
10+
### Added
11+
- **Grep glob filter logging** (#6): Grep entries now show file glob filter alongside pattern
12+
- Format: `{Grep: pattern | "*.tsx" }` when glob filter is used
13+
- **Write/Edit content preview** (#7): Shows first 20 characters of content being written
14+
- Format: `{Write: "path" ← "content preview..." }`
15+
- Newlines escaped as `\n`, non-printable chars replaced with `?`
16+
- **Agent context identification** (#5): Framework for identifying subagent tool calls
17+
- When detected, format: `{Bash|Explore: command }` or `{Read|Plan: "path" }`
18+
- Debug logging to investigate available JSON fields for agent detection
19+
- **Version sync tool** (`scripts-repo/sync-versions.py`): Centralized version management
20+
- `--bump patch/minor/major` to increment version
21+
- `--demote patch/minor/major` to decrement version
22+
- `--set X.Y.Z` to set version directly
23+
- `--phase alpha/beta/rc1/none` to set release phase
24+
- `--check` to verify all files are in sync
25+
- `--dev-refresh [VERSION...]` to clear plugin cache for development testing
26+
- Without args: clears target version
27+
- With args: clears specified version(s) (e.g., `--dev-refresh 0.1.3 0.1.4 0.1.5`)
28+
- Use `--dry-run` to preview, `--force` to skip confirmations
29+
- Calls `update-version.sh` automatically
30+
- **Developer guide** (`docs/dev.md`): Documentation for contributors
31+
32+
### Fixed
33+
- **Session resume detection** (#9): SESSION START marker now written when resuming a session
34+
- Previously, resumed sessions didn't get new markers due to persistent `.started` flag
35+
- Now clears `.started` and `.run` flags on SessionStart hook
36+
- Run number correctly increments by recounting markers in log file
37+
38+
### Changed
39+
- Content extraction for Read, Write, Edit, MultiEdit now handled separately
40+
- Added `truncate_preview()` helper for safe content truncation
41+
- Added `format_tool_name()` helper for agent-prefixed tool names
42+
843
## [0.1.3] - 2026-02-01
944

1045
### Fixed

‎README.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,10 @@ Run Number: 2
9797
Sesslog Directory: ~/.claude/sesslogs/my-project__833a100e-..._User/
9898
```
9999

100+
## Tips
101+
102+
- **First-time `/rename`**: The built-in `/rename` command may fail on first use in a new session (before any tools run). Just run it again or use any tool first. See [Known Quirks](docs/installation.md#known-quirks).
103+
100104
## Configuration
101105

102106
The hook creates these directories automatically:
@@ -139,7 +143,8 @@ claude-session-logger/
139143
├── scripts-repo/ # Development/repo scripts (not part of plugin)
140144
│ ├── hooks/ # Git hooks (pre-commit, etc.)
141145
│ ├── install-hooks.sh
142-
│ └── update-version.sh
146+
│ ├── sync-versions.py # Version synchronization tool
147+
│ └── update-version.sh # Git version string updater
143148
├── version.py
144149
└── ...
145150
```
@@ -190,6 +195,12 @@ These tools are complementary — you might use cchistory for quick historical l
190195

191196
Contributions welcome! Please open an issue or submit a pull request.
192197

198+
See **[Developer Guide](docs/dev.md)** for:
199+
- Local plugin testing workflow
200+
- Version management with `sync-versions.py`
201+
- Debugging tips and session state files
202+
- Pull request checklist
203+
193204
Like the project?
194205

195206
[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/djdarcy)

‎docs/dev.md‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
# Developer Guide
2+
3+
This guide covers development workflows for contributing to claude-session-logger.
4+
5+
## Quick Start for Development
6+
7+
```bash
8+
# Clone and enter the project
9+
git clone https://github.com/DazzleML/claude-session-logger.git
10+
cd claude-session-logger
11+
12+
# Install as local plugin for testing
13+
claude plugin marketplace add "./"
14+
claude plugin install session-logger@dazzle-claude-plugins
15+
16+
# Start a new Claude Code session to load the hooks
17+
```
18+
19+
## Project Structure
20+
21+
```
22+
claude-session-logger/
23+
├── .claude-plugin/ # Plugin packaging
24+
│ ├── plugin.json # Plugin metadata (version here)
25+
│ └── marketplace.json # Marketplace config (version here too)
26+
├── hooks/
27+
│ ├── hooks.json # Hook registration
28+
│ └── scripts/
29+
│ └── log-command.py # Main logging logic
30+
├── commands/ # Slash commands (/renameAI, /sessioninfo)
31+
├── scripts-repo/ # Development scripts
32+
│ ├── sync-versions.py # Version synchronization
33+
│ └── update-version.sh # Git version string updater
34+
├── version.py # Canonical version source (MAJOR.MINOR.PATCH)
35+
└── docs/
36+
├── installation.md # User installation guide
37+
└── dev.md # This file
38+
```
39+
40+
## Version Management
41+
42+
### Version Locations
43+
44+
Version numbers exist in multiple files. **`version.py` is the source of truth.**
45+
46+
| File | Field | Example |
47+
|------|-------|---------|
48+
| `version.py` | `MAJOR`, `MINOR`, `PATCH` | `0`, `1`, `4` |
49+
| `version.py` | `__version__` | `0.1.4_main_12-20260201-abc123` |
50+
| `.claude-plugin/plugin.json` | `"version"` | `"0.1.4"` |
51+
| `.claude-plugin/marketplace.json` | `"version"` (×2) | `"0.1.4"` |
52+
53+
### Sync Versions Script
54+
55+
The `sync-versions.py` script keeps everything in sync:
56+
57+
```bash
58+
# Check if versions are synchronized
59+
python scripts-repo/sync-versions.py --check
60+
61+
# Bump patch version (0.1.4 -> 0.1.5)
62+
python scripts-repo/sync-versions.py --bump patch
63+
64+
# Bump minor version (0.1.4 -> 0.2.0)
65+
python scripts-repo/sync-versions.py --bump minor
66+
67+
# Bump major version (0.1.4 -> 1.0.0) - requires confirmation
68+
python scripts-repo/sync-versions.py --bump major
69+
70+
# Demote patch version (0.1.4 -> 0.1.3)
71+
python scripts-repo/sync-versions.py --demote patch
72+
73+
# Demote minor version (0.1.4 -> 0.0.0)
74+
python scripts-repo/sync-versions.py --demote minor
75+
76+
# Set version directly (e.g., 0.1.4 -> 0.2.1)
77+
python scripts-repo/sync-versions.py --set 0.2.1
78+
79+
# Skip confirmation for major changes (use with caution)
80+
python scripts-repo/sync-versions.py --bump major --force
81+
python scripts-repo/sync-versions.py --set 2.0.0 --force
82+
83+
# Preview changes without modifying
84+
python scripts-repo/sync-versions.py --bump patch --dry-run
85+
86+
# Sync without updating git version string
87+
python scripts-repo/sync-versions.py --no-git-ver
88+
89+
# Clear plugin cache for development testing (--dev-refresh)
90+
python scripts-repo/sync-versions.py --dev-refresh # Clears target version
91+
python scripts-repo/sync-versions.py --set 0.1.4 --dev-refresh # Clears 0.1.4
92+
python scripts-repo/sync-versions.py --dev-refresh 0.1.3 0.1.4 # Clears multiple versions
93+
94+
# Preview cache clearing without removing
95+
python scripts-repo/sync-versions.py --dev-refresh --dry-run
96+
97+
# Skip confirmation prompts (use after reviewing with --dry-run)
98+
python scripts-repo/sync-versions.py --dev-refresh 0.1.3 0.1.4 --force
99+
```
100+
101+
### Version Bumping Workflow
102+
103+
```bash
104+
# 1. Make your code changes
105+
# 2. Update CHANGELOG.md with new version section
106+
# 3. Bump and sync versions
107+
python scripts-repo/sync-versions.py --bump patch
108+
109+
# 4. Verify everything is in sync
110+
python scripts-repo/sync-versions.py --check
111+
112+
# 5. Commit all changes
113+
git add -A
114+
git commit -m "Release v0.1.5: description of changes"
115+
116+
# 6. Tag the release
117+
git tag v0.1.5
118+
git push origin main --tags
119+
```
120+
121+
## Testing Changes
122+
123+
### Local Plugin Testing
124+
125+
After modifying hook scripts, reload them in Claude Code:
126+
127+
```bash
128+
# Method 1: Update the plugin (preferred)
129+
claude plugin update session-logger@dazzle-claude-plugins
130+
131+
# Method 2: Full reinstall (if update doesn't work)
132+
claude plugin marketplace remove dazzle-claude-plugins
133+
claude plugin marketplace add "./"
134+
claude plugin install session-logger@dazzle-claude-plugins
135+
136+
# IMPORTANT: Always restart Claude Code session after updating
137+
# Hooks are loaded at session start
138+
```
139+
140+
### Verifying Hook Loading
141+
142+
1. **Check debug log:**
143+
```bash
144+
tail -f ~/.claude/logs/hook-debug.log
145+
```
146+
147+
2. **Use /sessioninfo command** (if installed):
148+
```
149+
> /sessioninfo
150+
Session ID: abc123...
151+
Session Name: my-project
152+
```
153+
154+
3. **Check sesslog output:**
155+
```bash
156+
ls -la ~/.claude/sesslogs/
157+
cat ~/.claude/sesslogs/*/.*sesslog*.log
158+
```
159+
160+
### Testing Specific Features
161+
162+
| Feature | How to Test |
163+
|---------|-------------|
164+
| Grep logging | Run a Grep tool, check for `pattern \| "glob"` format |
165+
| Write/Edit preview | Write a file, check for `← "content..."` in log |
166+
| Agent context | Use Task tool with Explore, check for `Bash\|Explore:` |
167+
| Auto-naming | Start session in a project folder, check directory name |
168+
169+
## Debugging
170+
171+
### Hook Debug Log
172+
173+
All hook activity is logged to:
174+
```
175+
~/.claude/logs/hook-debug.log
176+
```
177+
178+
Add debug statements in `log-command.py`:
179+
```python
180+
debug_log(f"My debug message: {variable}")
181+
```
182+
183+
### Common Issues
184+
185+
| Issue | Solution |
186+
|-------|----------|
187+
| Stale plugin version | Remove marketplace, re-add, reinstall |
188+
| Hook not firing | Check hooks.json path, restart session |
189+
| Permission errors | Check file permissions in ~/.claude/ |
190+
| Unicode errors | Ensure UTF-8 encoding in file operations |
191+
192+
### Session State Files
193+
194+
Session state is persisted in `~/.claude/session-states/`:
195+
- `{id}.json` - Full session state
196+
- `{id}.name-cache` - Cached session name
197+
- `{id}.run` - Current run number
198+
- `{id}.started` - Session start marker
199+
200+
## Code Style
201+
202+
- Python 3.9+ compatible
203+
- Use type hints where practical
204+
- Keep functions focused and documented
205+
- Use `debug_log()` for troubleshooting output
206+
- Handle cross-platform paths via `dazzle_filekit`
207+
208+
## Dependencies
209+
210+
- **dazzle-filekit** - Cross-platform path normalization and symlink creation
211+
```bash
212+
pip install dazzle-filekit
213+
```
214+
215+
## Pull Request Checklist
216+
217+
- [ ] Code changes tested locally
218+
- [ ] Version bumped with `sync-versions.py`
219+
- [ ] CHANGELOG.md updated
220+
- [ ] All versions in sync (`--check` passes)
221+
- [ ] Documentation updated if needed
222+
- [ ] No sensitive data in commits

‎docs/installation.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -271,3 +271,21 @@ For this plugin:
271271

272272
- Expected to work (not yet tested)
273273
- No special configuration anticipated
274+
275+
---
276+
277+
## Known Quirks
278+
279+
### /rename requires transcript to exist
280+
281+
The built-in `/rename` command may fail with `ENOENT` on first use in a brand new session (before any tool calls create the transcript file). If this happens, simply run `/rename` a second time, or use any tool first (like asking a question), then rename.
282+
283+
```
284+
> /rename my-session-name
285+
⎿ Error: ENOENT: no such file or directory, open '...transcript.jsonl'
286+
287+
> /rename my-session-name
288+
⎿ Session renamed to: my-session-name
289+
```
290+
291+
This is a Claude Code behavior, not specific to this plugin.

0 commit comments

Comments
 (0)