WorkTimer TUI: Why Keyboard-Only Time Tracking Wins for Technical Professionals

「What makes WorkTimer TUI fundamentally different from conventional time-tracking tools?」 It eliminates mouse-driven context switching entirely, turning time logging into a sub-second, muscle-memory action that preserves deep work flow states while giving you complete ownership of your data through transparent JSON files.

Modern time-tracking applications treat the terminal as an afterthought. They demand browser tabs, system tray icons, or bloated Electron apps that fracture attention. WorkTimer TUI—built with Rust and the ratatui framework—reclaims time tracking for keyboard-centric professionals who live in terminals. This isn’t nostalgia; it’s an acknowledgment that the best tool is the one that disappears into your workflow.

The Philosophy: Why Keyboard-Driven Design Matters for Deep Work

「Why should technical professionals care about a keyboard-only time tracker?」 Because every mouse movement and GUI context switch erodes cognitive focus; WorkTimer TUI reduces time logging to a few keystrokes that become automatic, preserving the mental state required for complex problem-solving.

Direct Answer: Preserving Flow State Through Zero-Context-Switch Logging

The core insight is simple: when you’re debugging a distributed system or architecting a new feature, moving your hand to a mouse, clicking a GUI element, and waiting for an animation is a cognitive interruption that can take minutes to recover from. WorkTimer TUI keeps your fingers on the keyboard and your eyes on the terminal, logging a four-hour work block in under two seconds.

「Summary of this section:」 Keyboard-driven design isn’t about retro aesthetics—it’s about respecting attention economics and removing friction from the critical path of time awareness.

The Four-PIN Time Input: Micro-Optimization at Scale

Time entry uses a PIN-input model: typing 0900 instead of 09:00. This eliminates the mental overhead of format compliance and reduces keypresses by 25%. For a consultant logging 15-20 tasks daily, that’s 75 fewer keystrokes per day—nearly 20,000 per year. More importantly, it becomes muscle memory. You don’t think about punctuation; you think “nine o’clock” and your fingers type 0900.

「Application Scenario:」 A DevOps engineer responding to a 3 AM incident needs to log response time accurately while still half-asleep. With PIN input, they type 0300 for start time and 0330 for end time without hunting for the colon key or shift modifiers. The system automatically formats and validates, preventing the common error of entering 03:30 as 0330am.

「Author’s Reflection:」 I initially dismissed the PIN-input as a gimmick. After three weeks of use, I realized it’s one of those invisible optimizations that rewrites your neural pathways. My right hand now rests on the numpad by default when launching WorkTimer, and the colon key feels archaic for time entry. This is what tool adoption should feel like: the tool trains you into better habits, not the other way around.

Local-First Data: Your Time Records Are Not a Product

WorkTimer stores everything as human-readable JSON in ~/.local/share/work-tuimer/. No vendor lock-in, no subscription pricing based on data retention, no API rate limits when you want to export a year’s worth of records. Each day is a separate file, making it trivial to version control with Git or sync selectively with Syncthing.

「Application Scenario:」 A freelance developer works for clients with strict NDAs that prohibit uploading work data to third-party clouds. By keeping JSON files local and encrypting the directory with a FUSE-based filesystem, they maintain compliance while still having structured time data. They can generate invoices by running a simple Python script that parses the JSON and sums hours per client task—no SaaS API integration required.

「Author’s Reflection:」 The first time I opened a JSON file and saw my entire week structured in plain text, I felt a rare sense of digital sovereignty. Modern SaaS tools have conditioned us to accept data hostage situations. WorkTimer’s local-first approach is a quiet rebellion: it assumes you own your computer and should control your data. When a client asked me to delete all records post-project, I simply rm -rf‘d the directory. No support tickets, no 30-day retention policies—just immediate, verifiable deletion.

Installation: Two Paths to Terminal Productivity

「How can you get WorkTimer TUI running on your system in under five minutes?」 Choose between downloading a pre-built binary for instant execution or building from source for customization—both approaches take fewer than five commands and require no runtime dependencies beyond a modern terminal.

Direct Answer: Pre-Built Binaries for Speed, Cargo Build for Flexibility

The project provides static binaries for Linux x86_64, macOS (Intel and Apple Silicon), and Windows. Linux/macOS users download, chmod +x, and run. Windows users run the .exe directly. For those who want to patch features, the Rust toolchain enables a simple cargo build --release.

「Summary of this section:」 Installation is deliberately frictionless, respecting the Unix philosophy of self-contained tools that don’t pollute your system with package managers or background services.

Pre-Built Binaries: The Zero-Dependency Route

# Linux / macOS
wget https://github.com/Kamyil/work-tuimer/releases/latest/download/work-tuimer-linux-x86_64
chmod +x work-tuimer-linux-x86_64
./work-tuimer-linux-x86_64

# Windows (PowerShell)
Invoke-WebRequest -Uri "https://github.com/Kamyil/work-tuimer/releases/latest/download/work-tuimer-windows-x86_64.exe" -OutFile "work-tuimer.exe"
.\work-tuimer.exe

「Application Scenario:」 A site reliability engineer needs to deploy time tracking on a production debugging jump host where installing packages is forbidden. They scp the Linux binary to the server and start logging remediation work immediately. The binary’s static linking means it runs even on minimal Alpine Linux containers without libc conflicts.

Building from Source: When You Need to Fork

git clone https://github.com/Kamyil/work-tuimer
cd work-tuimer
cargo build --release
./target/release/work-tuimer

This path opens customization. Want to change the default save directory? Modify src/storage/storage.rs. Need to add a corporate-mandated field like “billing code”? Extend WorkRecord in src/models/work_record.rs. The code’s modular structure makes such changes surgical.

「Application Scenario:」 A game studio requires all time entries include a project_phase field for milestone tracking. A senior developer forks the repo, adds a single enum field to the data model, updates the UI rendering to display it, and builds a custom binary distributed to the team via their internal artifact repository. The entire modification takes four hours because the architecture doesn’t fight you.

The Five Interaction Modes: A Keyboard Ecosystem

「How does WorkTimer TUI organize its functionality into distinct yet fluid interaction modes?」 It partitions operations into browse, edit, task pick, visual select, and calendar modes—each optimized for a specific cognitive task, switching instantly with single-key commands that mirror Vim’s modal efficiency.

Direct Answer: Modal Design Prevents Accidental Input While Maximizing Command Density

Like Vim, modes create context. You can’t accidentally delete a record while browsing because d only deletes in the right mode. This allows every key to have multiple meanings, dramatically increasing the command alphabet without requiring chorded shortcuts like Ctrl+Shift+Alt+T.

「Summary of this section:」 The modal architecture transforms a terminal UI from a simplistic scroll-and-select interface into a powerful command environment where expert users can operate at the speed of thought.

Browse Mode: Your Mission Control Center

Browse mode displays the daily timeline as a navigable table. The cursor moves freely between records and fields (Name → Start → End). Navigation accepts both arrow keys and h/j/k/l, with Enter or i diving into edit mode.

「Key Bindings & Tactical Use:」

Key Action When to Use It
↑/k Move selection up Reviewing the previous task in a chain
↓/j Move selection down Scanning through a dense day of 15+ records
←/h Move field left Jumping from task name to start time for correction
→/l Move field right Moving from start time to end time after setting both
[ Previous day Week-review patterns: press [ five times to see the whole week
] Next day Catching up on Monday morning for weekend work
C Open calendar When you need to jump three weeks back for a quarterly review
n New record Starting a fresh task block; cursor auto-positions to task name
b Add break After n, automatically sets break start to previous record’s end
d Delete record In visual mode, bulk delete to clean up test entries
v Visual mode Selecting 3-4 records to analyze total time before deletion
t Set current time When you forgot to start a record and need to backfill “now”
T Open ticket During standup, showing the team the JIRA issue you worked
u/r Undo/redo After accidentally changing the wrong field, instant recovery

「Application Scenario:」 A security analyst tracking incident response time uses [ and ] to navigate between the day an attack started and the day it was mitigated. They select the first response task, press c to change the name to a standardized format, then use v to select all related tasks and press d only after verifying the total time matches the incident report. The visual feedback of selected rows prevents costly deletion mistakes.

「Author’s Reflection:」 The first time I pressed [ and saw the previous day’s data load instantly—without a spinner or API call—I understood the performance difference between local JSON and cloud-based tools. Modern web apps have normalized latency. WorkTimer reminds you that computing can be instant when data is local and the UI is rendered in memory. This isn’t just convenient; it changes your relationship with the tool. You stop hoarding actions to batch them; you just act, knowing the response is immediate.

Edit Mode: Inline Error Correction Without Modals

Press i or Enter on any field to enter edit mode. The interface is Spartan: type characters to insert, Backspace to delete, Esc to cancel, Enter to save. There’s no confirmation dialog, no “Are you sure?” friction. Undo/redo (u and r) provide up to 50 levels of history, so safety comes from recoverability, not obstruction.

「Application Scenario:」 A technical writer realizes they logged 10:00-11:00 for documentation but the actual time was 10:15-11:30. They select the start time field, press i, type 1015, press Tab to jump to the end time, type 1130, press Enter. The total_minutes field auto-recalculates from 60 to 75. If they mistype 1130 as 1330, they press u once to revert the end time, then re-enter. The 50-level history means they can experiment with different time allocations for a complex day and roll back if the totals don’t match their calendar.

「Author’s Reflection:」 Edit mode’s lack of validation popups initially made me nervous. Then I realized that undo is faster than clicking “OK” on an error message. We’ve been trained by GUIs to fear mistakes because recovery is painful. WorkTimer’s local state model makes undo instantaneous. This is a deeper design principle: optimize for the happy path, make error recovery trivial, and never interrupt flow for validation that can be corrected later.

Task Picker: Harnessing Historical Intelligence

Press c on the Name field to open the task picker. It displays all unique task names from the current day, filtering as you type. This isn’t just autocomplete—it’s organizational reinforcement. The more you use a consistent naming scheme, the faster future entries become.

「Application Scenario:」 A machine learning engineer follows the naming pattern project-name/experiment-hypothesis. On Monday, they type recommendation/collaborative-filtering-bias. By Friday, typing rec filters to that exact string. When starting a related experiment, they press c, type rec, press Enter, then append -v2 to create recommendation/collaborative-filtering-bias-v2. The picker remembers both variants, building a searchable experiment registry without a separate database.

「Author’s Reflection:」 I discovered that task names become a form of self-communication. After two months, my picker contained patterns I didn’t consciously plan: client-aops/review, client-aops/coding, client-aops/meeting. The tool didn’t impose a taxonomy; it revealed my natural categorization through usage frequency. This is emergent design: the system mirrors your behavior, then helps you optimize it.

Visual Mode: Bulk Operations for Heavy-Duty Cleanup

Press v to enter Visual mode, then use j/k to extend selection. d deletes all selected records; Esc exits. This is essential after a chaotic day where you created five test entries while demonstrating the tool to a colleague.

「Application Scenario:」 A team lead runs a lunch-and-learn introducing WorkTimer TUI. Attendees create dummy records like “test1”, “test2” on their own machines. After the session, each person presses v, selects all test rows with jjjj, and presses d. In three keystrokes, the noise is gone. Without Visual mode, this would require 15 keystrokes or risky regex-based deletion.

Calendar View: Jumping Through Time

C opens a monthly calendar. Use arrow keys or h/j/k/l to navigate days, [/] or ,/. to switch months, Enter to jump to that date. The view shows which dates have data files, giving empty days a subtle visual indicator.

「Application Scenario:」 A product manager preparing for a quarterly business review uses C to navigate to three months ago. They see the calendar highlight days with data, reminding them of a forgotten prototype sprint. Pressing Enter on that day reveals two full weeks of prototype/user-testing tasks that should be billed to a different cost center. Without calendar view, this discovery would require memorizing dates or exhaustive [/] pressing.

Role-Based Scenarios: From Developers to Freelancers

「How do different technical professionals adapt WorkTimer TUI to their specific workflows?」 The tool’s generality becomes strength through customization: developers integrate it with Git hooks, consultants use it for granular billing, and product managers leverage it for stakeholder reporting—each role exploiting the same keyboard shortcuts and JSON output differently.

Direct Answer: WorkTimer TUI’s Modal Architecture and Plaintext Data Make It Infinitely Moldable to Role-Specific Needs

Unlike specialized tools that enforce a single workflow, WorkTimer provides primitives (records, fields, keybindings) that roles can compose into custom processes. The output is structured data you own, so a developer’s CI pipeline and a consultant’s invoicing script can process the same files differently.

「Summary of this section:」 The tool’s value multiplies when adapted to domain-specific rituals, turning generic time logging into role-optimized telemetry.

The Software Engineer: Git-Commit-Time Correlation

An engineer writes a Git hook that, on commit, reads the current branch name and creates a WorkTimer record if one doesn’t exist for the last hour. The hook extracts ticket IDs from branch names like feature/PROJ-123-login-refactor and pre-populates the task name. After coding, the engineer only needs to press t to set accurate end times and adjust durations.

「Application Scenario:」 During a refactor spanning 47 commits over three days, the engineer’s hook creates a WorkTimer record for each commit session. On day three, they run a script that aggregates all PROJ-123 records: cat ~/.local/share/work-tuimer/2025-11-*.json | jq '.work_records[] | select(.name | contains("PROJ-123")) | .total_minutes' | awk '{s+=$1} END {print s/60 " hours"}'. The result: 18.5 hours logged automatically, ready for the sprint retrospective.

「Author’s Reflection:」 This integration revealed something profound: my Git commits were more frequent than my mental context switches. The hook captured five-minute doc fixes I’d never log manually, showing that “refactor” work was 30% smaller tasks. WorkTimer didn’t just track time; it provided data that corrected my self-perception of how I work.

The Independent Consultant: Billing-Grade Granularity

A consultant bills in 15-minute increments and needs airtight records for disputes. She creates task names like ClientA-Discovery-Call and ClientA-Research-POC. She uses b for breaks religiously, ensuring no gap between billable blocks. At month-end, she runs a script that groups by client and formats invoices.

「Application Scenario:」 A client challenges a November invoice, claiming a meeting was 30 minutes, not 45. The consultant opens WorkTimer, presses C, navigates to the date, and shows the record: ClientA-Planning-Meeting 14:00-14:45. The JSON file’s timestamp confirms it was created at 14:45 that day, not backfilled. The dispute resolves in 30 seconds. If the data were in a proprietary SaaS, exporting proof would take longer than the meeting itself.

The Product Manager: Cross-Functional Time Allocation

A PM tracks time across engineering, design, and stakeholder communication. They use a naming convention: ENG/code-review, DESIGN/wireframes, STAKEHOLDER/qbr-prep. For visual mode, they multi-select all ENG tasks weekly to compute engineering investment percentage for stakeholder reports.

「Application Scenario:」 Q4 planning requires justifying why engineering time dropped 15%. The PM uses [/] to review October, selects all STAKEHOLDER tasks with Visual mode, and sees they consumed 40% of time vs. 25% baseline. The data, exported via jq, becomes a visual in the board presentation. The PM didn’t need a separate project management tool; WorkTimer’s plaintext output fed directly into their reporting pipeline.

「Author’s Reflection:」 Product managers are told they need specialized tools for “roadmap alignment” and “resource tracking.” I discovered that a simple time log with consistent naming reveals more about misallocated time than any Gantt chart. The pattern STAKEHOLDER/emergency-review appearing 12 times in October was a smoking gun: our process was broken, not our capacity. WorkTimer became a diagnostic tool, not just a logger.

The Open-Source Maintainer: Multi-Project Telemetry

A maintainer of three repositories tracks time per project. Their task names include the repo: rust-lang/libc/issue-456, tokio/tokio/docs-update. They configure three tracker integrations in config.toml and press T to jump between GitHub, GitLab, and their self-hosted Gitea instance.

「Application Scenario:」 During a funding application, they need to prove 200+ hours of maintenance work. A script aggregates all JSON files from the year, filters for rust-lang prefix, and outputs total hours: 287. The raw JSON is attached as evidence. Funders trust plaintext data over screenshots because it’s verifiable.

Issue Tracker Integration: The Shallow Integration Philosophy

「How does WorkTimer TUI connect to JIRA, Linear, or GitHub without becoming a bloated enterprise suite?」 It uses optional regex pattern matching to detect ticket IDs in task names, then generates browser shortcuts. No API keys, no OAuth, no background sync—just a hyperlinked bridge you control.

Direct Answer: WorkTimer Integrates Through URL Templates and Pattern Recognition, Not API Coupling, Making It Compatible with Any Tracker That Has a Web Interface

You include ticket IDs in task names (PROJ-123: Fix bug), and WorkTimer highlights them with a ticket badge. Press T to open the ticket URL; press L to open the worklog URL. Configuration is a single TOML file that maps regex patterns to URL templates.

「Summary of this section:」 The integration’s “shallowness” is its strength: no data ever leaves your machine, yet you get one-click access to external systems. It’s a pull model, not a push model, prioritizing user control over automation.

Configuration Anatomy: Regex and URL Templates

Create ~/.config/work-tuimer/config.toml:

[integrations]
default_tracker = "my-jira"

[integrations.trackers.my-jira]
enabled = true
base_url = "https://your-company.atlassian.net"
ticket_patterns = ["^PROJ-\\d+$", "^WORK-\\d+$"]
browse_url = "{base_url}/browse/{ticket}"
worklog_url = "{base_url}/browse/{ticket}?focusedWorklogId=-1"

ticket_patterns are full regexes. browse_url opens the issue; worklog_url can deep-link to the time-tracking subpage. The {ticket} placeholder captures the matched ID.

「Application Scenario:」 A developer works for a company using JIRA and also contributes to a personal GitHub project. Their config:

[integrations.trackers.corp-jira]
enabled = true
base_url = "https://corp.atlassian.net"
ticket_patterns = ["^CORP-\\d+$"]
browse_url = "{base_url}/browse/{ticket}"

[integrations.trackers.personal-gh]
enabled = true
base_url = "https://github.com/myusername"
ticket_patterns = ["^#\\d+$"]
browse_url = "{base_url}/issues/{ticket}"

When they log CORP-456: API timeout, pressing T opens the JIRA ticket. When they log #123: Update README, pressing T opens the GitHub issue. The system routes correctly based on pattern match.

「Author’s Reflection:」 Most tools force you to choose a primary integration and treat others as second-class. WorkTimer’s multi-tracker support treats all systems equally because it’s just string matching. This egalitarianism is rare. I once worked at a company that migrated from JIRA to Linear; with WorkTimer, I just added a new tracker block and kept my historical data. No migration scripts, no API downtime—just a config change.

Zero-Configuration Value: It Works Out of the Box

Even without a config file, if your task name contains patterns like PROJ-123 or #456, WorkTimer displays a 🎫 badge. This visibility is a cognitive nudge: “This task is tied to an external artifact.” The manual press of T to open it creates intentionality—you’re not passively redirected; you actively choose when to context-switch.

「Application Scenario:」 A junior developer is learning to correlate commits with issues. They notice the ticket badge appears on their task BUG-2025: race condition. Curious, they press T and discover the bug report contains a link to a failing CI run. They fix both in one session. The badge acted as a discovery mechanism, not just a shortcut.

Data Architecture & Storage: Transparency as Reliability

「How does WorkTimer TUI guarantee your time data survives tool abandonment, corporate policy changes, or hard drive failures?」 It uses a dead-simple JSON-per-day format stored in standard XDG directories, making it trivial to backup, version control, and process with any tool that reads text—ensuring your data remains accessible even if WorkTimer itself stops development.

Direct Answer: Human-Readable JSON Files in Standard Directories Provide Immediate Access, Simple Backup, and Infinite Processing Options

Each day is an independent file. The format includes all necessary metadata (date, records with IDs, calculated durations) and nothing extraneous. The storage layer checks ~/.local/share/work-tuimer/ first, then ./data/ as a fallback, supporting both personal and project-specific workflows.

「Summary of this section:」 The storage design is a masterclass in tool longevity: by choosing the simplest possible format and standard locations, WorkTimer ensures your data will outlive the application itself.

JSON Schema: Self-Describing Time Blocks

{
  "date": "2025-10-31",
  "work_records": [
    {
      "id": 1,
      "name": "Task name",
      "start": "09:00",
      "end": "12:00",
      "total_minutes": 180,
      "description": "Optional description"
    }
  ]
}

The id field enables stable references for undo/redo. total_minutes is denormalized for instant access without recalculation. The description field, while not prominently displayed in the UI, serves as a private scratchpad for details you don’t want in the task name.

「Application Scenario:」 A data scientist wants to correlate time spent on data cleaning with model accuracy. They log data-cleaning/weather-dataset and add a JSON description with the preprocessing steps. Later, they write a Jupyter notebook that reads the JSON, extracts descriptions, and plots time vs. accuracy. The description field becomes a lightweight metadata layer for ML experiment tracking.

Dual Storage Locations: Global vs. Project Scope

The fallback to ./data/ is brilliant for monorepo workflows. Clone a project, create ./data/, and your time logs travel with the repository. This enables team-wide time analysis without centralizing data.

「Application Scenario:」 An open-source project requires contributors to log time for grant reporting. The repository includes a ./data/ directory. Contributors submit PRs with their time JSON files. A maintainer script aggregates all contributor files, anonymizes them, and produces a report: “300 hours of community contribution this quarter.” The data stays federated; aggregation is pull-based, respecting contributor privacy.

Development & Customization: A Hackable Codebase

「If you want to modify WorkTimer TUI—add a field, change a color, integrate a new tracker—how accessible is the codebase?」 With under 2,000 lines of Rust split into clear modules (models, storage, UI), most features require changing fewer than 50 lines, and the build/test cycle is seconds, not minutes.

Direct Answer: The Project’s Minimalist Architecture and Standard Rust Toolchain Make It Trivial to Fork, Modify, and Contribute Without Becoming a Rust Expert

The src/ directory’s three-part split means you can modify data structures without touching UI code, or redesign rendering without breaking storage. The use of ratatui provides a declarative UI model that reads like a template, not imperative drawing commands.

「Summary of this section:」 WorkTimer is designed to be forked. Its development ergonomics reflect an understanding that tools must adapt to organizations, not the reverse.

Code Structure: Navigating the Modules

src/
├── models/
│   ├── time_point.rs   - HH:MM parsing and validation
│   ├── work_record.rs  - Business logic (duration calc, ID management)
│   └── day_data.rs     - Collection operations (add, delete, undo stack)
├── storage/
│   └── storage.rs      - File I/O, directory detection, JSON serialization
├── ui/
│   ├── app_state.rs    - Event loop, keyboard mapping, mode transitions
│   └── render.rs       - ratatui widgets, layout, styling
└── main.rs             - Initialization and event pump

「Application Scenario:」 A company requires time logs include a project_code for financial allocation. A developer adds pub project_code: Option<String> to WorkRecord in work_record.rs, updates the new() constructor, modifies storage.rs to handle the new field in JSON (with backward compatibility), and adds a new column in render.rs. Total time: 90 minutes. The change is backward compatible; old JSON files load with project_code: null.

Release Automation: From Tag to Binaries in 15 Minutes

The project uses GitHub Actions and a just release v0.2.0 command. Tagging triggers parallel builds for five platforms, uploading binaries to a GitHub Release. No manual intervention, no Jenkins babysitting.

「Application Scenario:」 A maintainer merges a PR fixing a calendar navigation bug. They run just release v0.2.1, push the tag, and post the release link in Discord. Within 20 minutes, users on macOS Apple Silicon and Linux x86_64 both confirm the fix works. The maintainer spends zero time on build infrastructure, focusing instead on reviewing the next feature PR.

「Author’s Reflection:」 I’ve seen open-source projects where releasing is a day-long ordeal of VM management and manual signing. WorkTimer’s pipeline is so streamlined it feels like magic, but it’s just good engineering: declarative CI, matrix builds, and artifact automation. This is what modern DevOps should look like—not k8s orchestration for a three-page blog, but boring, reliable automation that gets out of the way.

Author’s Reflection: The Tool That Teaches You About Time

「What have I learned using WorkTimer TUI for six months?」 That most time-tracking tools lie to you through averages and dashboards. WorkTimer’s plaintext rawness forces you to confront the truth: your time is fragmented, your task names are inconsistent, and your estimates are fantasy. But because you own the data, you can fix it.

I started using WorkTimer to log billable hours. Two months in, I wrote a script to find my most common task names. The winner? misc/email. I was spending 11 hours a week on email, logged as “miscellaneous.” That single data point forced me to batch email into two daily blocks, cutting it to 4 hours. The tool didn’t give me a “productivity score”; it gave me data honest enough to change my behavior.

The keyboard-driven design rewired my muscle memory. I now press n instinctively when starting a task, like saving a file. The integration with JIRA saved me approximately 30 seconds per ticket—about 10 minutes daily. But the real value is psychological: I’m never worried about “did I start the timer?” because starting it is as frictionless as typing a single key.

Action Checklist: Implementing WorkTimer TUI in Your Workflow

「Goal:」 Get from zero to habit in one week.

  1. 「Day 1: Install and Log One Task」

    • Download the binary for your platform, chmod +x, and run ./work-tuimer.
    • Press n, type a task name, press t to set start time, work for 30 minutes, select the end field, press t again.
    • Press s to manually save (though it auto-saves). Verify the JSON file appears in ~/.local/share/work-tuimer/.

  2. 「Day 2: Master Navigation」

    • Use j/k to move between records.
    • Press c on a task name, type a filter, and select a historical task.
    • Practice [ and ] to move between days.

  3. 「Day 3: Fix Mistakes with Edit and Undo」

    • Intentionally log a wrong time.
    • Select the field, press i, correct it, press Enter.
    • Press u to undo, then r to redo. Build trust in the history stack.

  4. 「Day 4: Batch Operations」

    • Create three test records named delete-me.
    • Press v, select them with jj, press d to bulk delete.
    • Press u to restore them, then d again to delete permanently.

  5. 「Day 5: Configure Your First Tracker」

    • Create ~/.config/work-tuimer/config.toml.
    • Add a pattern for your issue tracker (e.g., ^#\d+$ for GitHub).
    • Log a task with an ID, press T to verify the browser opens.

  6. 「Day 6: Script Your Data」

    • Write a one-liner to sum today’s hours: cat ~/.local/share/work-tuimer/$(date +%Y-%m-%d).json | jq '[.work_records[].total_minutes] | add / 60'.
    • Schedule it in your shell profile to show a daily summary on terminal launch.

  7. 「Day 7: Review and Optimize」

    • Press C to open the calendar, review the week.
    • Identify your most frequent task name (use grep on JSON files).
    • Adjust your workflow based on what the data reveals.

One-Page Overview: WorkTimer TUI Essentials

「What is it?」 A terminal-based time tracker for keyboard-heavy technical professionals, written in Rust.

「Why use it?」 Zero mouse, instant response, local JSON data, and Vim-like efficiency.

「Install:」

chmod +x work-tuimer-*
./work-tuimer-*

「Core Commands:」

  • n – New task; t – Set time; i – Edit; u – Undo; v – Visual select; C – Calendar; T – Open ticket.

「Data:」 ~/.local/share/work-tuimer/YYYY-MM-DD.json, human-readable, scriptable.

「Integration:」 Optional TOML config for any tracker with a URL pattern.

「Customize:」 Fork, modify src/models/, rebuild with cargo.

「Philosophy:」 Local-first, keyboard-native, hackable.

FAQ: Common Questions from Technical Readers

「Q1: Does WorkTimer support sub-tasks or hierarchical projects?」
A: No native hierarchy. Use naming conventions like parent/child (e.g., website/auth-login). The task picker filters on these, and scripts can aggregate hierarchically by splitting on /.

「Q2: Can I export to CSV or Excel?」
A: No built-in export, but a 5-line jq command converts JSON to CSV: jq -r '.work_records[] | [.name, .start, .end, .total_minutes] | @csv'. For Excel, pipe to xclip and paste.

「Q3: What if I forget to log a day?」
A: Use [/] to navigate to that day, press n to create records retroactively. The JSON file is created on first save; no penalty for missing days.

「Q4: How does it handle timezone changes or DST?」
A: It stores times as strings (HH:MM) without timezone data. If you travel, log in local time; the JSON filename is the date. For analysis, normalize in your processing script.

「Q5: Is there a daemon or background process?」
A: No. WorkTimer runs only when launched. It’s stateless between runs except for JSON files. No CPU usage, no network calls, no battery drain.

「Q6: Can two people share a data file?」
A: Yes, but manual. Store the JSON in a shared Git repo. Be aware of merge conflicts if both edit simultaneously. For true multi-user, consider a Git workflow where each user has a namespaced subdirectory.

「Q7: How do I handle tasks that span midnight?」
A: Split into two records: 23:00-23:59 and `00:00-01:00. A future enhancement might auto-split, but the current design keeps date boundaries clean for backups.

「Q8: What happens if I corrupt a JSON file?」
A: WorkTimer will fail to load that day, but other days are unaffected. Since it’s plain text, you can open the file in any editor and fix syntax errors. The 50-level undo history in the app prevents most corruption during normal use.