terminal-wakatime

Track your time in bash, zsh, and fish with WakaTime! Better alternative to the WakaTime desktop app. Built by @zachlatta.

Quick Setup (30 seconds)

curl -fsSL http://hack.club/terminal-wakatime.sh | bash

This installs terminal-wakatime to ~/.wakatime/terminal-wakatime and adds eval "$(terminal-wakatime init)" to your ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish.

That's it. Your terminal work in bash, zsh, and fish now gets properly tracked in WakaTime with correct project detection.

The Problem with WakaTime Desktop App

You spend 3 hours coding, but WakaTime only shows 2 hours because:

• ❌ Can't see terminal work - Git commits, vim editing, testing, debugging = invisible
• ❌ Wrong project names - Everything becomes <<LAST_PROJECT>>
• ❌ Misses development work - git commit, tmux sessions don't count as coding time

terminal-wakatime fixes all of this. It properly tracks your terminal sessions with accurate project detection and file-level detail.

Works With Your Existing Plugins

✅ Vim plugin still tracks detailed keystrokes and cursor movement
✅ VSCode plugin still tracks file edits and project switching
✅ terminal-wakatime adds the missing terminal sessions, git work, and project context

No conflicts. They work together to give you complete tracking.

Before vs After

Before terminal-wakatime (WakaTime Desktop App Only):

Today's Coding Time: 2h 30m
├── VSCode: 2h 15m (my-website)
└── Terminal: 15m (<<LAST_PROJECT>>)

Missing: 4+ hours of git work, vim editing, testing, and debugging

After terminal-wakatime:

Today's Coding Time: 6h 45m
├── VSCode: 2h 15m (my-website) 
├── Terminal: 3h 30m (my-website)
│   ├── Git operations: 45m
│   ├── Vim editing: 2h 10m  
│   └── Testing/debugging: 35m
└── Terminal: 1h (hackclub-bot)
    └── Python scripting: 1h

Now tracking your complete development workflow with correct project names

What Gets Tracked

Files & Editing:

• vim src/app.js → Tracks file editing time in correct project
• nano README.md → Counts toward your coding time
• File saves and project switching

Development Tools:

• git commit, git push → Tracked as code review time
• npm test, cargo build → Tracked as debugging time
• docker run, ssh server → Tracked appropriately

Project Detection:

• Automatically detects project from your current directory
• Works with Git repos, package.json, Cargo.toml, etc.
• No more "Unknown Project" in your stats

Installation Options

Quick Install (Recommended)

curl -fsSL http://hack.club/tw.sh | bash

Manual Install

Download from releases, then:

# Add to your shell config (~/.bashrc, ~/.zshrc, etc.)
eval "$(terminal-wakatime init)"

Package Managers

For all of your favorite package managers don't forget to activate the packge with the following in your shell config:

eval "$(terminal-wakatime init)"

Go

# Go
go install github.com/hackclub/terminal-wakatime/cmd/terminal-wakatime@latest

Nix

# Direct installation with flakes enabled
nix profile install github:hackclub/terminal-wakatime

For use in your own flake:

# In your flake.nix
{
  inputs.terminal-wakatime.url = "github:hackclub/terminal-wakatime";
  
  outputs = { self, nixpkgs, terminal-wakatime, ... }: {
    # Access the package as:
    # terminal-wakatime.packages.${system}.default
  };
}

Configuration

WakaTime API Key Setup:

Optionally manually set your API key. If you're using Hackatime, this is already done automatically by the Hackatime setup script and you can ignore this.

terminal-wakatime config --key YOUR_WAKATIME_KEY

Basic Options:

# Set custom project name for current directory
terminal-wakatime config --project my-awesome-project

# Test your setup
terminal-wakatime test

How It Works

terminal-wakatime hooks into your shell to detect:

1. When you start working in a directory (project detection)
2. What files you're editing (vim, nano, code commands)
3. What tools you're using (git, npm, python, etc.)

It sends this data to WakaTime using the same format as other plugins, so everything appears seamlessly in your dashboard.

Editor Plugin Suggestions

When you use editors like vim or code, terminal-wakatime will suggest installing the dedicated plugin for better tracking:

💡 You're using Vim! Install vim-wakatime for detailed keystroke tracking:
   https://github.com/wakatime/vim-wakatime
   
   `terminal-wakatime` will still track your session time.

You can disable these suggestions:

terminal-wakatime config --disable-editor-suggestions

Troubleshooting

Not tracking activity?

# Check if properly installed
echo $PROMPT_COMMAND  # Should show terminal-wakatime

# Verify API key
terminal-wakatime config --show

# Test connection
terminal-wakatime test

Wrong project names?

# Check current project detection
terminal-wakatime debug

# Manually set project for this directory
terminal-wakatime config --project my-project

Issues with dependencies?

# Check wakatime-cli status
terminal-wakatime deps --status

# Reinstall if needed
terminal-wakatime deps --reinstall

Why Not Just Use WakaTime Desktop App?

WakaTime Desktop App only tracks window focus - it has no idea what you're actually doing in your terminal. When you're deep in a coding session doing git commits, vim editing, npm test, it just sees "Terminal app is open" with no context.

terminal-wakatime hooks directly into your shell (Bash/Zsh/Fish) to track:

• ✅ Actual commands and file editing
• ✅ Correct project detection from your current directory
• ✅ Real coding time vs just having terminal open
• ✅ Works alongside your existing editor plugins

Privacy

• No file contents are ever sent
• Only file paths, timestamps, and metadata
• All data encrypted in transit
• Same privacy model as other WakaTime plugins

Contributing

Built for Hack Club's Hackatime community, but works with standard WakaTime. Pull requests welcome!

git clone https://github.com/hackclub/terminal-wakatime
cd terminal-wakatime
go test ./...

Support

• 🐛 GitHub Issues
• 💬 Hack Club Slack #hackatime-dev channel
• 📖 WakaTime Docs