Worktrace

Extract today's Claude Code work history from ~/.claude/history.jsonl and generate a structured markdown summary grouped by project and ticket.

CRITICAL: Execution Rules

MUST DO:

• Run python scripts/worktrace.py --config config.json
• Wait for complete script output before summarizing
• Use the Python script for ALL data extraction

NEVER DO:

• Parse ~/.claude/history.jsonl directly with Bash/jq
• Use find, grep, cat to read session files manually
• Proceed without running the Python script first

WHY: The script handles complex logic (date filtering, ticket extraction, session lookup) that is error-prone and inefficient when done manually with shell commands. The script is optimized for this task.

First-time Setup

When config.json doesn't exist in the plugin directory:

1. Ask user for output directory (use user's preferred language)

   • English: "Please provide the directory path for daily files (e.g., ~/.wiki/work-wiki/daily)"
   • Korean: "daily 파일을 저장할 디렉토리 경로를 알려주세요 (예: ~/.wiki/work-wiki/daily)"

2. Ask user for ticket patterns (optional)

   • Default pattern: [A-Z]+-\d+ (matches PROJ-123 style)
   • Ask if they have custom patterns

3. Create config.json with user's answers:

   {
     "output_dir": "<user-provided-path>",
     "ticket_patterns": ["[A-Z]+-\\d+"],
     "timezone": "Asia/Seoul"
   }

Quick Start

1. Set up config (optional but recommended):

   cp config.example.json config.json
   # Edit config.json to set output_dir

2. Run with config:

   python scripts/worktrace.py --config config.json

3. Or run directly with CLI args (overrides config):

   python scripts/worktrace.py --output-dir /path/to/daily

Priority: CLI args > config.json > defaults

Workflow (Phase-based)

Phase 0: Configuration Check (First-time only)

IF config.json does not exist:
  1. Ask user for output directory path (in user's language)
  2. Ask user for ticket patterns (optional, default: [A-Z]+-\d+)
  3. Create config.json with user's answers
  4. Continue to Phase 1

Phase 1: Data Extraction (MUST use Python script)

# REQUIRED: Run the Python script
python scripts/worktrace.py --config config.json

# Or with CLI overrides
python scripts/worktrace.py --output-dir /path/to/daily --date 2024-01-15

Important:

• MUST wait for complete script output before proceeding
• NEVER attempt to parse files manually with Bash

Phase 2: Summarization

1. Read script output (markdown or JSON)
2. Refer to references/summarize.md for summarization rules
3. Transform raw output into meaningful summary:
   • Group similar activities
   • Remove noise and duplicates
   • Infer context from activity patterns

Phase 3: Output

1. If output_dir is configured: Script saves directly to daily file
2. If not configured: Present summarized content to user
3. Verify the output file was updated correctly

Common Options

Option	Description
--output-dir PATH	Save to daily file in directory
--ticket-pattern REGEX	Custom ticket pattern (repeatable)
--timezone TZ	Timezone for "today" calculation
--config FILE	Load settings from JSON config
--json	Output as JSON instead of markdown

Examples

Extract with custom ticket patterns:

python scripts/worktrace.py \
  --ticket-pattern "AMAP-\d+" \
  --ticket-pattern "IE-\d+"

Use config file:

python scripts/worktrace.py --config config.json

Output Format

## Claude Code Work History

### PROJ-123 (webapp)
- Implement login form validation
- Fix password reset flow

### API-456 (api-service)
- Fix null pointer exception in user service

### Other (docs)
- Update README documentation

File Handling

When output_dir is specified:

• Creates {YYYY-MM-DD}.md in the directory
• If file exists: replaces ## Claude Code Work History section only
• Other sections in the file are preserved

Configuration

For detailed configuration options including:

• Frontmatter template
• Ticket pattern examples
• Timezone settings
• CLI usage examples

See references/template.md

Error Handling

Common Issues and Solutions

Issue	Cause	Solution
"No entries found"	No activity for the target date	Check --date option or verify Claude Code was used
Script not found	Wrong working directory	Run from plugin root directory
Permission denied	File access issue	Check file permissions for ~/.claude/
Config not found	Missing config.json	Run First-time Setup (Phase 0)

Debug Mode

If issues persist, use JSON output for debugging:

python scripts/worktrace.py --config config.json --json

This outputs raw data structure for inspection.

Fallback Behavior

If the Python script fails:

1. Check that ~/.claude/history.jsonl exists
2. Verify Python 3 is available (python --version)
3. Check config.json is valid JSON
4. Try running without config: python scripts/worktrace.py --output-dir /path/to/daily