https://github.com/hackclub/terminal-wakatime
Track your time in the terminal!
https://github.com/hackclub/terminal-wakatime
Last synced: 7 months ago
JSON representation
Track your time in the terminal!
- Host: GitHub
- URL: https://github.com/hackclub/terminal-wakatime
- Owner: hackclub
- Created: 2025-06-04T13:27:16.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-08-05T10:53:47.000Z (about 1 year ago)
- Last Synced: 2025-10-04T22:32:11.701Z (10 months ago)
- Language: Go
- Homepage:
- Size: 156 KB
- Stars: 19
- Watchers: 0
- Forks: 5
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# `terminal-wakatime`
Track your time in bash, zsh, and fish with WakaTime! Better alternative to the WakaTime desktop app. Built by [@zachlatta](https://github.com/zachlatta).
## Quick Setup (30 seconds)
```bash
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 `<>`
- ❌ **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 (<>)
```
*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)
```bash
curl -fsSL http://hack.club/tw.sh | bash
```
### Manual Install
Download from [releases](https://github.com/hackclub/terminal-wakatime/releases), then:
```bash
# 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:
```bash
eval "$(terminal-wakatime init)"
```
## Go
```bash
# Go
go install github.com/hackclub/terminal-wakatime/cmd/terminal-wakatime@latest
```
### Nix
```bash
# Direct installation with flakes enabled
nix profile install github:hackclub/terminal-wakatime
```
For use in your own flake:
```nix
# 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](https://hackatime.hackclub.com), this is already done automatically by the [Hackatime setup script](https://hackatime.hackclub.com/my/wakatime_setup) and you can ignore this.
```bash
terminal-wakatime config --key YOUR_WAKATIME_KEY
```
**Basic Options:**
```bash
# 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:
```bash
terminal-wakatime config --disable-editor-suggestions
```
## Troubleshooting
**Not tracking activity?**
```bash
# 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?**
```bash
# Check current project detection
terminal-wakatime debug
# Manually set project for this directory
terminal-wakatime config --project my-project
```
**Issues with dependencies?**
```bash
# 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](https://hackatime.hackclub.com) community, but works with standard WakaTime. Pull requests welcome!
```bash
git clone https://github.com/hackclub/terminal-wakatime
cd terminal-wakatime
go test ./...
```
## Support
- 🐛 [GitHub Issues](https://github.com/hackclub/terminal-wakatime/issues)
- 💬 [Hack Club Slack](https://hackclub.com/slack) `#hackatime-dev` channel
- 📖 [WakaTime Docs](https://wakatime.com/help)