Quick Example

/track:help
# Displays comprehensive hooks-based tracking documentation
# Commands, file formats, verbosity settings, and workflow examples

help - Hooks-Based Tracking System Help

Comprehensive help for the Track Plugin v2.0 hooks-based automatic tracking system.

Overview

The Track Plugin v2.0 uses Claude Code hooks for fully automatic reference and prompt tracking for academic work and project documentation.

Two tracking files:

• claude_usage/sources.md - Research sources (WebSearch, WebFetch, documentation)
• claude_usage/prompts.md - Major prompts and outcomes

Key features:

• Automatic tracking via hooks (PostToolUse, UserPromptSubmit, SessionEnd)
• No skill activation needed - hooks run automatically
• Per-project activation - only tracks when enabled
• Configurable verbosity - control what gets tracked
• Export support - generate bibliographies and methodology sections
• Attribution system - tracks [User] vs [Claude] initiated sources

v2.0 Architecture

Hooks-based tracking (NEW):

• PostToolUse hook → Automatically tracks WebSearch/WebFetch/Read/Grep to claude_usage/sources.md
• UserPromptSubmit hook → Captures user prompts to temporary storage
• SessionEnd hook → Pairs prompts with outcomes, writes to claude_usage/prompts.md

Fully automatic - no manual intervention:

• Hooks check for .claude/.ref-autotrack marker
• If present, hooks track automatically
• No skill activation needed (unlike v1.x)

Commands (Skills)

/track:init - Initialize tracking

Set up hooks-based tracking files and configuration for the current project.

Creates:

• claude_usage/sources.md (with preamble)
• claude_usage/prompts.md (with preamble)
• .claude/.ref-autotrack (enables hooks)
• .claude/.ref-config (verbosity settings)

Run this first before using other tracking commands.

---

/track:auto - Toggle hooks-based tracking

Enable or disable automatic hooks-based tracking.

/track:auto          # Toggle
/track:auto on       # Enable
/track:auto off      # Disable

Enabled: Hooks run automatically
Disabled: Hooks are inactive

Use when: You want to pause/resume automatic tracking.

---

/track:config - Manage verbosity and export

View or update tracking verbosity and export configuration.

/track:config                            # Interactive mode (AskUserQuestion)
/track:config prompts=all sources=off    # Direct mode
/track:config export_path=paper/refs/    # Set export path

Use when: You want to control what gets tracked or where exports go.

---

/track:export - Export tracked data

Generate bibliographies, methodology sections, or other export formats.

/track:export bibliography              # → exports/bibliography.md
/track:export methodology               # → exports/methodology.md
/track:export bibtex references.bib     # → references.bib
/track:export timeline                  # → exports/timeline.md

Use when: You need to generate output for academic papers or reports.

---

/track:help - Show this help

Display comprehensive documentation.

---

File Formats

claude_usage/sources.md

Format: Pure KV file with preamble

Pattern: [Attribution] Tool("query"): result

Examples:

[User] WebSearch("PostgreSQL foreign keys tutorial"): https://postgresql.org/docs/current/ddl-constraints.html
[Claude] WebFetch("https://go.dev/doc/", "embed.FS usage"): Use embed.FS to embed static files at compile time
[Claude] Read("docs/api.md"): Documentation reference
[Claude] Grep("middleware", pattern="CORS"): Documentation reference

Attribution:

• [User] - User explicitly requested ("search the web for...")
• [Claude] - Claude autonomously searched for missing information

Preamble: Explains format, usage, and configuration

---

claude_usage/prompts.md

Format: Three-line entries with blank separator

Pattern:

Prompt: "user request"
Outcome: what was accomplished
Session: timestamp

Example:

# Development Prompts and Outcomes

This file automatically tracks significant development work and decisions.

---

Prompt: "Implement user authentication with JWT"
Outcome: Created auth middleware, login/logout endpoints, JWT token generation and verification, integrated with database user model
Session: 2026-01-27 14:23:15

Prompt: "Debug slow database queries"
Outcome: Added query logging, identified N+1 problem in user posts endpoint, implemented eager loading, reduced query time from 2.3s to 0.15s
Session: 2026-01-27 15:42:08

Preamble: Explains format, usage, and configuration

---

Verbosity Settings

Located in ./.claude/.ref-config:

PROMPTS_VERBOSITY

• major (default) - Significant multi-step academic/development work
  • Heuristic: Response >100 words
  • Best for project documentation
• all - Every user request
  • Best for complete session logs
• minimal - Only explicit user requests to track
  • Best for selective curation
• off - Disable prompt tracking

SOURCES_VERBOSITY

• all (default) - Track all WebSearch/WebFetch/Read/Grep operations
  • Best for complete research audit trail
• off - Disable source tracking

EXPORT_PATH (new in v2.0)

• Default directory for /track:export output
• Examples: exports/, paper/references/, /tmp/tracking/
• Can be absolute or relative path

Academic Workflow Example

1. Setup (once per project):

/track:init

2. Work session:

• Hooks capture all searches and major work automatically
• Sources logged to claude_usage/sources.md
• Prompts logged to claude_usage/prompts.md
• No manual intervention needed

3. Review tracked data:

tail claude_usage/sources.md    # Recent sources
tail claude_usage/prompts.md    # Recent work
grep "authentication" claude_usage/prompts.md

4. Adjust if needed:

/track:config prompts=minimal    # Less verbose
/track:auto off                  # Pause tracking

5. Export for paper:

/track:export bibliography       # Generate bibliography
/track:export methodology        # Generate methodology section
/track:export bibtex refs.bib    # Generate BibTeX file

Tips

For research papers:

• Keep prompts=major and sources=all
• Review claude_usage/sources.md for bibliography
• Use prompts for methodology section
• Export to BibTeX for LaTeX papers

For development projects:

• Use prompts=all for complete audit
• claude_usage/prompts.md documents decisions
• Useful for project retrospectives
• Export timeline for progress reports

For focused work:

• Use /track:auto off to pause tracking
• Manual /track:export when needed
• Reduces noise during exploration

File Locations

• Tracking files: ./claude_usage/ directory
  • claude_usage/sources.md
  • claude_usage/prompts.md
• Configuration: ./.claude/.ref-config
• Auto-tracking marker: ./.claude/.ref-autotrack
• Temporary storage: ./.claude/.track-tmp/ (automatic cleanup)

Common Issues

"No tracking files found"
→ Run /track:init first

"Too verbose"
→ Use /track:config prompts=minimal

"Want to pause tracking"
→ Use /track:auto off

"Need to export for paper"
→ Use /track:export bibliography

"Where are my old files?"
→ v2.0 uses claude_usage/ directory instead of root-level files
→ Run /track:init to migrate from CLAUDE_*.md files

v2.0 Changes from v1.x

Major changes:

• Hooks-based architecture - Fully automatic, no skill activation
• New directory: claude_usage/ instead of root-level files
• File preambles: Explanatory headers in tracked files
• Export support: /track:export command for output generation
• Enhanced config: EXPORT_PATH setting added
• Deprecated: ref-tracker skill, /track:update command

Migration:

• Existing .ref-autotrack and .ref-config work unchanged
• Run /track:init to migrate old CLAUDE_*.md files
• Remove manual /track:update calls (automatic now)

Related

• Plugin hooks - PostToolUse, UserPromptSubmit, SessionEnd
• Global CLAUDE.md - Documents the system in detail
• Project CLAUDE.md - Can contain project-specific notes

---

For more help, consult plugin README or MIGRATION.md for v1.x → v2.0 upgrade guide.