local-work: The Ultimate CLI Toolkit for Productive Developers

The Problem

As a developer, you've probably been through this:

Scattered tasks across Trello, Notion, GitHub Issues, and sticky notes
Disorganized notes in multiple files with no standard
Constant context switching between tools
Lack of history of technical decisions in projects
Manual time tracking that's imprecise

Most productivity tools are:

Too heavy (Jira, Asana)
Too generic (Notion, Evernote)
Not integrated with development workflow
Cloud-based (latency, privacy concerns)

What if there was a tool made BY developers, FOR developers?

The Solution: local-work

local-work is a professional CLI toolkit that unifies task management and note-taking in a single tool, designed specifically for the modern development workflow.

Why Use It?

[✓] Zero Configuration: Works out-of-the-box
[✓] Project-Aware: Automatically detects project root (Git, package.json)
[✓] Cross-Platform: Windows, macOS, Linux natively
[✓] Zero Dependencies: Only 137 kB, no npm bloat
[✓] Team-Friendly: Shareable configuration via Git
[✓] Offline-First: Your data stays local, secure, and private

Quick Start

Installation

npm install -g local-work

Done! The task and note commands are now globally available.

Setup in Existing Project

cd /path/to/your/project
task init
 
# Creates:
# .local-work/config.json  ← Share via Git
# tasks/                   ← Add to .gitignore
# notes/                   ← Add to .gitignore

First Task

task new "Implement OAuth2 authentication" -p high -e 8h
 
# Output:
# [+] Created task: TASK-001
# Title: Implement OAuth2 authentication
# Status: backlog
# Priority: high
# Estimated: 8h

Main Features

1. Intelligent Task Management

Auto-Incremental IDs

Forget complex UUIDs. Each task gets a sequential, readable ID:

TASK-001, TASK-002, TASK-003...

Synchronized across the whole team via .local-work/config.json.

Defined Workflow

backlog → active → completed → archived

task start TASK-001    # backlog → active
task done TASK-001     # active → completed
task archive 30        # completed → archived (>30 days)

Built-in Time Tracking

# Estimate time
task new "Fix login bug" -e 2h
 
# Work...
task update TASK-001 actual 2.5h
 
# View statistics
task stats
# ┌─────────────────────────────────┐
# │ Task Statistics                 │
# ├─────────────────────────────────┤
# │ Total: 42                       │
# │ Active: 5                       │
# │ Completed: 35                   │
# │ Avg completion: 3.2h            │
# │ Estimation accuracy: 87%        │
# └─────────────────────────────────┘

Priorities and Tags

task new "Refactor API" -p high -t backend,refactoring
task new "Update docs" -p low -t documentation
 
task list high         # List only high priority
task search "backend"  # Search by keyword or tag

2. Professional Note Management

Daily Notes

note daily
 
# Opens:
# notes/daily/2025-11-02.md
#
# # Daily Notes - 2025-11-02
#
# ## Today's Focus
# - [ ] Item 1
# - [ ] Item 2
#
# ## Notes
#

Perfect for standup meetings and retrospectives.

Meeting Notes

note meeting "Sprint Planning Q4"
 
# Template:
# # Meeting: Sprint Planning Q4
# Date: 2025-11-02
#
# ## Attendees
# -
#
# ## Agenda
# 1.
#
# ## Action Items
# - [ ]

Technical Decision Records (ADRs)

note tech "Migration from PostgreSQL to MongoDB"
 
# Creates:
# notes/technical/ADR-001-postgresql-mongodb-migration.md
#
# # ADR-001: PostgreSQL → MongoDB Migration
#
# ## Status
# Proposed
#
# ## Context
#
#
# ## Decision
#
#
# ## Consequences
#

ADRs are essential to document the why of architectural decisions.

Learning Notes (TIL - Today I Learned)

note til "React Server Components"
 
# notes/learning/2025-11-02-react-server-components.md

Capture learnings before they evaporate!

3. Multi-Workspace Support

Manage multiple isolated projects:

# Setup
task workspace add multify ~/GitHub/multifyco
task workspace add personal ~/personal-projects
task workspace add client ~/clients/acme
 
# Switch
task workspace switch multify
task list                    # Shows only Multify tasks
 
task workspace switch client
task list                    # Shows only client tasks

Each workspace has:

Independent numbering (TASK-001, TASK-002...)
Isolated configuration
Separate data

4. Subdirectory Awareness

Works from any folder in the project:

# Structure:
/my-project/
  ├── .git/
  ├── .local-work/config.json
  └── src/
      └── components/  ← You are here
 
# Commands work!
cd /my-project/src/components
task list              [✓] Works
task new "Fix bug"     [✓] Works
note daily             [✓] Works

local-work automatically detects the root by looking for:

.git/
package.json
.local-work/config.json
Other project markers

Real Use Cases

Workflow 1: Feature Development

# Monday - Planning
note daily
task new "Implement dark mode" -p high -e 6h -t frontend,ux
 
# Start work
task start TASK-015
 
# During development
task update TASK-015 actual 3h  # Checkpoint
 
# Important technical decision
note tech "Theming strategy with CSS Variables"
 
# Complete
task done TASK-015
 
# Review
task stats

Workflow 2: Bug Fixing Sprint

# Create multiple tasks
task new "Fix login redirect" -p high
task new "Fix mobile navigation" -p medium
task new "Fix typo in docs" -p low
 
# List by priority
task list high
 
# Work in sequence
task start TASK-042
# ... fix ...
task done TASK-042
 
task start TASK-043
# ... fix ...
task done TASK-043

Workflow 3: Continuous Documentation

# Capture learnings
note til "React 19 useOptimistic hook"
note til "Supabase RLS patterns"
 
# Document meetings
note meeting "Sprint 12 Retrospective"
 
# Search history
note search "supabase"
# Returns all notes mentioning "supabase"

Team Collaboration

Team Setup

Project Lead:

cd /path/to/project
task init
 
# Configure team defaults
task config set editor code
 
# Commit config
git add .local-work/config.json
git commit -m "Add local-work configuration"
git push

Add to .gitignore:

# local-work - local data
tasks/
notes/
 
# local-work - team config (KEEP)
# .local-work/config.json  ← DO NOT ignore

Team Members:

git pull
task list              # Works automatically!
task new "My feature"  # Creates TASK-042 (next in sequence)

Team Benefits

[✓] Synchronized IDs: Everyone shares the same numbering
[✓] Unified Config: Consistent editor, paths, defaults
[✓] Autonomy: Each dev manages their own tasks/notes
[✓] Traceability: ADRs document team decisions

Advanced Configuration

Custom Editor

# Via command (recommended)
task config set editor code  # VS Code
 
# Via environment variable
export EDITOR=vim
export EDITOR=nano

Custom Paths

# Override via ENV
export LOCAL_WORK_DIR=~/my-workspace
export LOCAL_WORK_TASKS_DIR=~/custom-tasks
export LOCAL_WORK_NOTES_DIR=~/custom-notes

Configuration Priority

When you run a command, local-work checks in this order:

Local project config (.local-work/config.json) - Highest priority
Environment variables (LOCAL_WORK_*)
Active workspace (global workspace)
Platform defaults (XDG, AppData, Library)

Comparison with Alternatives

Feature	local-work	Taskwarrior	Todo.txt	Org-mode	Notion
Zero Config	[✓]	[✗]	[✓]	[✗]	[✓]
Multi-Project	[✓]	[~]	[✗]	[✓]	[✓]
Notes System	[✓]	[✗]	[✗]	[✓]	[✓]
Time Tracking	[✓]	[✓]	[✗]	[✓]	[~]
Offline-First	[✓]	[✓]	[✓]	[✓]	[✗]
Team Sync	[✓] (Git)	[✗]	[✗]	[~]	[✓] (Cloud)
Learning Curve	Low	High	Low	Very High	Medium
Dependencies	Zero	Many	Zero	Emacs	Internet
Size	137 kB	~10 MB	~50 kB	~100 MB	N/A

Who is local-work For?

Ideal For:

CLI-first developers who live in the terminal
Agile teams needing lightweight task tracking
Open-source projects valuing privacy
Freelancers managing multiple clients
Solo developers wanting organization without overhead
Remote teams that document everything

Not Ideal For:

Large teams (>20 people) needing dashboards
Non-technical users without CLI comfort
Mobile app requirements for managing tasks
Enterprise integrations (Jira, Salesforce, etc.)

Quality and Maintenance

Comprehensive Testing

10 test files (unit, integration, e2e)
Jest as test runner
Coverage available via npm test:coverage

Professional Tooling

ESLint + Prettier configured
GitHub Actions for CI/CD
Conventional Commits for automatic changelog

Active Development

7 releases since launch
Latest version: v2.1.7 (published today!)
Zero open issues (bugs resolved quickly)

Complete Documentation

README.md: 21 KB of documentation
ONBOARDING.md: Quick start guide
SUBDIRECTORY_BEHAVIOR.md: Detailed explanation
CONTRIBUTING.md: Contributor guide

Practical Example: My Workflow at Multify

Here's how I use local-work daily on the Multify project (B2B SaaS):

# Initial setup (once)
cd ~/GitHub/multifyco
task init
task config set editor code
 
# Monday - Planning
note daily
task new "Implement i18n in Pricing" -p high -t frontend,i18n -e 4h
task new "Refactor credits system" -p high -t backend,refactoring -e 6h
task new "Update Stripe docs" -p low -t documentation -e 1h
 
# Start sprint
task list backlog
task start TASK-087  # i18n in Pricing
 
# During development (checkpoint)
task update TASK-087 actual 2h
 
# Important technical decision
note tech "Multi-Currency Pricing Strategy"
# Document context, decision, consequences
 
# Feature completed
task done TASK-087
 
# Weekly review
task stats
note search "pricing"  # Review all pricing decisions

Perceived Benefits

Less context switching: Everything in the terminal
Complete history: ADRs document the "why"
Real time tracking: Estimates vs. actual improve sprint by sprint
Easier onboarding: New devs read ADRs and understand decisions

Installation and Next Steps

1. Install

npm install -g local-work

2. Initialize in Project

cd /your/project
task init
task config set editor code

3. Create First Task

task new "Explore local-work" -p high -e 30m
task start TASK-001

4. Explore Commands

task list
task view TASK-001
task stats
 
note daily
note meeting "Team standup"
note til "local-work CLI"

5. Configure Git

# .gitignore
echo "tasks/" >> .gitignore
echo "notes/" >> .gitignore
 
# Commit config
git add .local-work/config.json
git commit -m "Add local-work configuration"

Resources

NPM: npmjs.com/package/local-work
GitHub: github.com/Jonhvmp/local-work
Issues: GitHub Issues
License: MIT (open source)

Conclusion

local-work is not just another productivity tool. It's a work philosophy for developers who value:

Simplicity over complexity
Performance over unnecessary features
Privacy over cloud sync
Terminal over heavy GUIs
Standards over infinite configurations

If you're a developer still managing tasks in generic tools, try local-work for a week. I guarantee you won't go back.

[★★★★★] Recommendation: HIGHLY recommended for developers working on multiple projects who value organization without overhead.

Feedback

Do you use local-work? Share your experience in the comments!

Have feature suggestions? Open an issue on GitHub.

Share this article

Listen to this article