Project Tracker System

A lightweight, table-based project tracking system with automated token usage and time tracking from git history.

About Knolling

This project is inspired by artist Tom Sachs' studio practice of knolling — the act of arranging objects at 90-degree angles and tidying all surfaces after finishing work. In his seminal video Ten Bullets, Sachs outlines his studio's operating principles, with Bullet #8 being "Always Be Knolling" (ABK).

Just as knolling resets a physical workspace to be shipshape and ready for the next session, this tool "knolls" your digital project state — logging time, tracking costs, organizing metadata, and preparing your workspace for the next work session. It's the practice of tidying up your project tracking at the end of each session so you can start fresh next time.

"Knolling is the process of arranging like objects in parallel or 90-degree angles as a method of organizing." — Tom Sachs

Features

• 📊 Table-based tracking - TSV format opens in any spreadsheet app
• 💰 Token tracking - Auto-aggregate Claude Code usage by project
• ⏱️ Activity-based time tracking - Precise session hours from Claude Code logs
• 🔍 Status filtering - View active/paused/completed projects
• ⚡ Quick updates - CLI tools for rapid field updates
• 📱 Cross-platform - Works on terminal and spreadsheet apps

Installation

All files are automatically installed in:

• Data: $PROJECTS_DIR/.project-tracker.tsv
• Tools: ~/.local/bin/project-{view,update,tokens,time}, session-hours
• Docs: $PROJECTS_DIR/.project-tracker-README.md

Ensure ~/.local/bin is in your PATH:

# Add to ~/.zshrc if not present
export PATH="$HOME/.local/bin:$PATH"

Quick Start

1. View Projects

project-view              # Show all projects
project-view active       # Filter by status

2. Update a Project

project-update gmail-integration status Active
project-update gmail-integration priority High
project-update gmail-integration started 2026-01-20
project-update gmail-integration hours 8.5

3. Track Usage

session-hours gmail-integration --update   # Bill current session hours (recommended)
project-tokens --update                     # Aggregate Claude Code tokens

CLI Reference

project-view

Display projects as a formatted table.

project-view [active|paused|completed|planned]

Examples:

project-view              # All projects
project-view active       # Only active projects

project-update

Update project fields.

project-update <project> <field> <value>

Fields:

• status - Active, Paused, Completed, Planned, Archived
• priority - High, Medium, Low
• started - YYYY-MM-DD
• deadline - YYYY-MM-DD
• progress - 0-100%
• tags - comma,separated,tags
• hours - Number (float)
• notes - "Text in quotes"

Special Commands:

• touch - Set Last_Active to today
• add-hours <N> - Add hours to existing total

Examples:

project-update my-project status Active
project-update my-project deadline 2026-03-15
project-update my-project tags work,backend,urgent
project-update my-project touch
project-update my-project add-hours 2.5

session-hours

Track billable hours from Claude Code session activity (recommended method).

session-hours                        # Show current session duration
session-hours <project>              # Preview billing to project
session-hours <project> --update     # Bill hours to project tracker

How it works:

• Reads start timestamp from current session's .jsonl log file
• Calculates elapsed time to the minute
• Rounds up to nearest 0.25 hour increment (15-minute billing blocks)
• Provides precise, activity-based tracking

Examples:

session-hours                              # Check current session time
session-hours gmail-integration            # Preview before billing
session-hours gmail-integration --update   # Bill to project (end of session)

Recommended workflow: Run session-hours <project> --update at the end of each work session for accurate time tracking.

---

project-tokens

Aggregate Claude Code token usage from session logs.

project-tokens [--update] [--quiet]

Options:

• --update / -u - Update tracker file with token counts
• --quiet / -q - Suppress display output

What it tracks:

• Input tokens (prompt + context)
• Output tokens (generated text)
• Cache tokens (for cost awareness)
• Estimated cost (based on Sonnet 4.5 pricing)

Data source: ~/.claude/projects/ session logs

Examples:

project-tokens                  # Show token usage
project-tokens --update         # Update tracker
project-tokens -u -q            # Silent update

project-time

Estimate project time from git commit history (fallback method).

project-time [--update] [--quiet]

Heuristic: Commits within 2 hours = one 1-hour session

Use case: For projects without Claude Code sessions, provides baseline time estimates from git history.

Options:

• --update / -u - Update tracker (only fills empty fields)
• --quiet / -q - Suppress display output

Examples:

project-time                    # Show estimates
project-time --update           # Update tracker

Note: For Claude Code projects, prefer session-hours for more accurate tracking.

Data Format

The tracker is a tab-separated file (.project-tracker.tsv) with these columns:

Column	Description	Example
Project	Folder name	gmail-integration
Status	Current state	Active, Paused, Completed
Priority	Importance	High, Medium, Low
Started	Start date	2026-01-20
Deadline	Due date	2026-03-15
Progress	Completion %	60%
Tags	Categories	work,backend
Input_Tokens	Claude input	45200
Output_Tokens	Claude output	12300
Hours	Time spent	12.5
Last_Active	Last worked	2026-02-07
Notes	Free text	Blocked on API approval

Editing Options

Terminal (read-only):

project-view

Spreadsheet (full edit):

open "$PROJECTS_DIR/.project-tracker.tsv"

CLI (field updates):

project-update <project> <field> <value>

Workflows

Starting a New Project

project-update my-new-project status Active
project-update my-new-project priority High
project-update my-new-project started $(date +%Y-%m-%d)
project-update my-new-project tags personal,learning

Daily Check-in

project-view active
project-update current-project touch

End of Session (Recommended)

session-hours current-project --update     # Bill precise session time
project-tokens --update                     # Sync token costs

End of Day

project-update current-project progress 75%
project-update current-project notes "Completed OAuth flow"

Weekly Review

project-tokens --update         # Refresh all token counts
project-view active             # Review active work

Completing a Project

project-update finished-project status Completed
project-update finished-project progress 100%
project-update finished-project notes "Deployed to production"

Technical Details

Session-Based Time Tracking (v2.0)

Activity-based tracking from Claude Code session logs:

1. Finds most recently modified .jsonl file in ~/.claude/projects/
2. Extracts start timestamp from first message
3. Calculates elapsed time to current moment
4. Rounds up to nearest 0.25 hour increment (15-minute billing blocks)

Advantages over git-based estimation:

• Tracks actual AI-assisted work time, not just git commits
• Accounts for research, debugging, and planning time
• Precise to the minute, not session-based estimates
• Works for all projects using Claude Code

Token Tracking

Parses Claude Code session logs (~/.claude/projects/*/...*.jsonl) to extract:

1. Token usage from assistant messages
2. Working directory (cwd) to map to project
3. Aggregates all sessions for each project

Only tracks sessions where cwd is inside $PROJECTS_DIR.

Git-Based Time Estimation (Fallback)

For projects without Claude Code sessions, uses git commit timestamps:

• Commits within 2 hours = one continuous work session
• Each session = 1 hour (configurable in script)
• Provides baseline estimate (actual time may vary)

Manual override if needed:

project-update my-project hours 12.5

Compatibility

• Shell: Works with bash 3.2+ (macOS default)
• Python: Requires Python 3 for token/time scripts
• Git: Required for time tracking feature
• Platform: macOS, Linux (untested on Windows)

Shell Aliases (Optional)

Add to ~/.zshrc for convenience:

alias pv='project-view'
alias pu='project-update'
alias pt='project-tokens'
alias sh='session-hours'              # Quick session time check
alias ptime='project-time'
alias pa='project-view active'

Cost Awareness

Claude Code token costs (Sonnet 4.5 pricing):

• Input tokens: $3.00 per 1M
• Output tokens: $15.00 per 1M
• Cache reads: $0.30 per 1M

Run project-tokens periodically to monitor spending:

project-tokens
# Shows total cost estimate across all projects

Backup & Sync

The tracker file lives in iCloud ($PROJECTS_DIR/.project-tracker.tsv), so it's:

• ✅ Automatically backed up
• ✅ Synced across devices
• ✅ Version controlled (if $PROJECTS_DIR is a git repo)

Consider also committing it to git:

cd "$PROJECTS_DIR"
git add .project-tracker.tsv
git commit -m "docs: update project tracker"

Troubleshooting

Commands not found

# Verify ~/.local/bin is in PATH
echo $PATH | grep .local/bin

# If missing, add to ~/.zshrc:
export PATH="$HOME/.local/bin:$PATH"
source ~/.zshrc

Token tracking shows no data

• Run Claude Code from within project directories
• Verify $PROJECTS_DIR is set correctly
• Check session logs exist: ls ~/.claude/projects/*/

Session hours tracking doesn't work

• Make sure you're running session-hours during or after a Claude Code session
• Session logs are stored in ~/.claude/projects/
• The script finds the most recently modified .jsonl file across all sessions

Git-based time tracking doesn't work

• Project must be a git repository
• Verify git is installed: git --version
• Check commits exist: cd <project> && git log
• Note: For Claude Code projects, use session-hours instead

License

MIT - Free to use, modify, and distribute.

Contributing

This is a personal tool, but feel free to fork and adapt for your needs!

---

Built with: Claude Sonnet 4.5 Last Updated: 2026-02-09 (v2.0 - Activity-based time tracking)