hyperfocus

hyperfocus is a fast, local-first CLI action tracker for people who want a simple daily system without opening a browser, maintaining a spreadsheet, or surrendering their data to a service.

It installs a terminal command named focus.

Run focus, check off what you did today, add a short note if you want, and get a clean view of your recent consistency, streaks, and momentum.

Why Hyperfocus?

Most habit trackers assume every habit happens every day. Real life is messier than that.

hyperfocus tracks actions, not rigid habits. An action can be daily, weekdays only, weekends only, specific days of the week, or a target number of times per week. You can skip an action without hurting your score, snooze it for a few days, archive it while preserving history, and edit the underlying JSON directly when you want full control.

Everything is stored locally in human-readable JSON.

Installation

Install globally from npm:

npm install -g @thefridgecoder/hyperfocus

Then run:

focus

For local development from this repository:

npm install
npm run build
npm link
focus

First Run

The first time you run focus, Hyperfocus creates:

~/.hyperfocus/actions.json
~/.hyperfocus/history.json

If no actions exist yet, it starts an onboarding flow and helps you create your first actions.

Quick Start

Add an action:

focus --add

See what is due today:

focus --today

Check in for today:

focus

See your recent grid:

focus --grid 14

See analytics:

focus --stats

Core Concepts

Actions

Hyperfocus calls tracked items actions instead of habits.

Examples:

• Drink water
• Walk outside
• Gym
• Study TypeScript
• Review calendar
• Inbox zero
• Call family

Actions can have:

• id: stable kebab-case identifier
• name: display name
• description: optional helper text during check-in
• category: simple tag such as health, work, or learning
• cadence: schedule logic
• status: active or archived

Check-ins

Running the base command launches the daily check-in:

focus

The check-in uses an interactive multi-select list. Toggle completed actions for today, optionally mark uncompleted actions as skipped, snooze actions temporarily, and add a short daily reflection.

If today is already logged, running focus shows the grid instead of forcing you through the check-in again.

Skips

Skipping is for real-life exceptions like illness, travel, injury, emergencies, or planned rest.

Skipped actions:

• Do not count against your daily score
• Preserve streaks
• Are stored with a reason in history.json

Daily score uses:

completed / (due - skipped)

So if 5 actions are due, 1 is skipped, and 4 are completed, the score is 100%.

Snoozes

Snoozing hides an action for a set number of days. This is useful for temporary breaks, travel, seasonal work, or actions that are currently blocked.

Snoozes live in history.json.

Archiving

Archiving hides an action from future check-ins while preserving its historical data.

Use archive when an action is no longer relevant but you still want old stats and logs to remain intact.

Commands

Daily Use

focus

Launch the smart daily flow. If today has not been logged, this opens check-in. If today has already been logged, it shows the grid.

focus --today
focus --daily
focus --due

Show a clean dashboard of actions due today, including category, current state, cadence, score, and today's note if one exists.

focus --undo

Remove today's log. Useful if you made a mistake during check-in and want to redo the day.

Action Management

focus --add
focus -a

Interactively add a new action. You can choose name, description, category, and cadence.

focus --remove

Archive or delete an action. Archiving is recommended because it preserves history.

focus --list

List all actions.

focus --config

Open ~/.hyperfocus/actions.json in your default terminal editor.

Views

focus --grid
focus -g

Show the default history grid.

focus --grid 7
focus --grid 14
focus --grid 30

Show a grid for a specific number of days.

The grid includes:

• Date
• One column per visible action
• Completion symbols
• Daily score
• A one-line pulse heatmap

Symbols:

check completed
~ skipped
x missed
. not due

focus --grid 14 --category health

Filter the grid by category.

Analytics

focus --stats
focus -s

Show deeper analytics:

• Current streak for each active action
• Grace day state
• 30-day completion rate
• All-time high score
• Best weekly average
• Best monthly average
• Best quarterly average
• Longest perfect streak
• Action MVP
• Momentum score
• Pulse heatmap

Data Portability

focus --export backup.json

Export all action definitions and history to JSON.

focus --export backup.csv

Export a spreadsheet-friendly CSV.

focus --import backup.json

Import data from a previous Hyperfocus export.

focus --cleanup 365

Prune logs older than the provided number of days while keeping the action list intact.

Help

focus --help
focus -h

Print the command reference.

Scheduling

Actions support several cadence types.

Daily

Due every day.

{
  "cadence": {
    "type": "daily"
  }
}

Weekdays

Due Monday through Friday.

{
  "cadence": {
    "type": "weekdays"
  }
}

Weekends

Due Saturday and Sunday.

{
  "cadence": {
    "type": "weekends"
  }
}

Specific Days

Due on specific days of the week.

Hyperfocus uses human-friendly day numbers:

1 = Sunday
2 = Monday
3 = Tuesday
4 = Wednesday
5 = Thursday
6 = Friday
7 = Saturday

Example: Sunday, Tuesday, and Saturday:

{
  "cadence": {
    "type": "specificDays",
    "days": [1, 3, 7]
  }
}

Times Per Week

Due enough times during the week to hit a weekly goal.

{
  "cadence": {
    "type": "timesPerWeek",
    "times": 3
  }
}

Data Files

Hyperfocus keeps two files in your home directory.

actions.json

Path:

~/.hyperfocus/actions.json

This is the "brain" of the app. It contains action definitions, schedules, categories, metadata, and settings.

Example:

{
  "_metadata": {
    "guide": "Edit this file directly if you like. Action ids must be unique kebab-case strings. status can be active or archived. cadence.type supports daily, weekdays, weekends, specificDays, or timesPerWeek.",
    "dayNumbers": "For specificDays, use 1=Sunday, 2=Monday, 3=Tuesday, 4=Wednesday, 5=Thursday, 6=Friday, 7=Saturday.",
    "cadenceExamples": {
      "daily": { "type": "daily" },
      "weekdays": { "type": "weekdays" },
      "gymTueThuSat": { "type": "specificDays", "days": [3, 5, 7] },
      "threeTimesWeekly": { "type": "timesPerWeek", "times": 3 }
    }
  },
  "settings": {
    "graceDaysPer30": 1,
    "defaultGridDays": 14
  },
  "actions": [
    {
      "id": "drink-water",
      "name": "Drink Water",
      "description": "Keep a bottle nearby.",
      "category": "health",
      "cadence": { "type": "daily" },
      "status": "active",
      "createdAt": "2026-05-07T12:00:00.000Z"
    }
  ]
}

history.json

Path:

~/.hyperfocus/history.json

This is the "vault" of the app. It stores daily completion data, skip reasons, notes, update timestamps, and snoozes.

Example:

{
  "_metadata": {
    "guide": "Raw completion vault. logs are keyed by yyyy-MM-dd. skipped actions do not count against daily score. snoozes hide actions through the listed date."
  },
  "snoozes": {
    "gym": "2026-05-10"
  },
  "logs": {
    "2026-05-07": {
      "date": "2026-05-07",
      "completed": ["drink-water"],
      "skipped": {
        "gym": "travel"
      },
      "note": "Long travel day, kept the basics alive.",
      "updatedAt": "2026-05-07T22:15:00.000Z"
    }
  }
}

Manual Editing

You can edit actions.json directly.

Hyperfocus validates the file every time it runs. If the JSON is malformed or an action does not match the expected shape, the CLI prints a helpful error instead of crashing with a stack trace.

Rules to remember:

• Action ids must be unique
• Action ids should use kebab-case, like read-20-minutes
• status must be active or archived
• cadence.type must be daily, weekdays, weekends, specificDays, or timesPerWeek
• specificDays.days uses 1=Sunday through 7=Saturday
• timesPerWeek.times must be at least 1

Scoring

Daily score is calculated as:

completed / (due - skipped)

Examples:

4 completed, 5 due, 0 skipped = 80%
4 completed, 5 due, 1 skipped = 100%
0 due actions = 100%

Score colors:

green  = 100%
yellow = greater than 50%
red    = 50% or lower

Streaks and Grace Days

Streaks count consecutive due days where an action was completed or skipped.

Hyperfocus also supports grace days. By default, one missed day every 30 days can be absorbed without breaking a streak.

Configure this in actions.json:

{
  "settings": {
    "graceDaysPer30": 1
  }
}

Set it to 0 if you want strict streaks.

Pulse Heatmap

The pulse is a compact one-line heatmap showing recent daily consistency.

Pulse .....###########

It is meant to give you a quick visual sense of whether your routine is warming up, cooling down, or staying steady.

Terminal Behavior

Hyperfocus is designed to be used daily and quickly.

• The base focus command starts check-in immediately
• Ctrl+C exits gracefully
• History views nudge you if today has not been logged
• Grid columns adjust to terminal width
• Older history is dimmed
• The current day is highlighted

Publishing Notes

This package is npm-ready because package.json includes:

{
  "bin": {
    "focus": "dist/index.js"
  }
}

Before publishing:

npm run build
npm pack --dry-run
npm publish

License

MIT