Habits, not cronjobs.

A human-like scheduler for AI agents and applications. habicron runs a callback on a randomized recurring interval — accurate by default (evenly spaced, anchored to the start time, no drift) and optionally jittered, so each fire is nudged earlier or later within bounds. Your jobs run on a human rhythm instead of robotically on the dot.

import { createHabit } from 'habicron'

// remind me to drink water roughly every hour
createHabit(drinkWater, { every: '1h ~ 8m' })

Node · Browser · Vue · React · CLI — one tiny, zero-dependency core behind five entry points.

• No drift — fires are anchored to a fixed grid; jitter perturbs around the grid point and never accumulates, so the long-run rate stays exact.
• Jitter, bounded — capped at 0.49 × interval so adjacent fires can't reorder.
• Long delays — months and years are supported (chunked past setTimeout's 24.8-day ceiling).
• Resilient — a throwing or rejecting callback never kills the schedule.
• SSR-safe — no timers during server render.
• Typed — ships generated .d.ts; every and times/per are mutually exclusive at compile time.

npm i habicron      # or: pnpm add habicron / bun add habicron

vue and react are optional peer dependencies — install only the one you use. For the habit CLI, install globally: npm i -g habicron.

Add the agent skills (Claude · OpenClaw):

npx skills add imrim12/habicron

import { createHabit } from 'habicron'

const job = createHabit(() => syncFeed(), { every: '15m ~ 2m' })

job.counter // times fired
job.nextRun // Date of the next fire, or null
job.pause()
job.resume()
job.stop()

Every adapter is the same engine with a platform-shaped surface:

import { useHabit } from 'habicron/vue'    // reactive refs
import { useHabit } from 'habicron/react'  // reactive values
import { useHabit } from 'habicron/browser' // controller + callbacks

habit start --every "1h ~ 5m" -- npm run sync   # the terminal

Give your software a daily rhythm.

A habit is an interval (every) or a rate (times + per), with optional jitter. Pass one schedule inline, or several under habits for the union.

The packed every separator is the typeable ~. +/-, +-, and the ± glyph are also accepted: '2h +/- 5m' is the same as '2h ~ 5m'.

A Duration is a number (milliseconds) or a string of <num><unit> tokens — tokens combine, e.g. '1h30m', '500ms', '2d12h'.

month / year are average approximations, not calendar-exact.

Jitter magnitude is always applied with a random sign — fires land earlier or later — and is capped at 0.49 × interval so adjacent fires can't reorder.

{ times, per } fires times evenly across one per period — intervalMs is period / times.

per is one of: minute · hour · day · week · month · year.

Any schedule also accepts these flags (ControlFlags):

createHabit(callback: () => void | Promise<void>, options: HabitOptions): HabitController

The returned HabitController:

Every habit is registered on creation, so you can list, look up, update, and remove them from anywhere in the process.

import { createHabit, getHabit, listHabits } from 'habicron'

createHabit(syncFeed, { id: 'feed', name: 'Feed sync', every: '15m ~ 2m' })

listHabits()                   // HabitController[]
getHabit('feed')?.update({ every: '5m' })   // reschedule in place
getHabit('feed')?.destroy()                 // stop + unregister

A HabitSummary is the plain, serialisable snapshot used by listing UIs:

interface HabitSummary {
  id: string
  name: string | undefined
  isActive: boolean
  counter: number
  nextRun: Date | null
}

The Node entry also re-exports the parser primitives dur, normalize, resolveJitter, and longTimeout for building on top of the engine.

Headless — you drive the controller directly.

import { createHabit } from 'habicron'

const job = createHabit(() => syncFeed(), { every: '15m ~ 2m' })

process.on('SIGINT', () => { job.stop(); process.exit(0) })

Vanilla JS has no refs or state, so reactivity arrives through callbacks. useHabit returns the HabitController; SSR-safe (timers start only when a window is present).

import { useHabit } from 'habicron/browser'

const job = useHabit(() => refreshWidget(), {
  every: '20s ~ 4s',
  onFire: count => (badge.textContent = String(count)),
  onActive: active => dot.classList.toggle('live', active),
  onChange: ({ nextRun }) => (label.textContent = nextRun?.toLocaleTimeString() ?? ''),
})

job.pause() // or resume / update / destroy

useHabit returns reactive, readonly refs and disposes on scope teardown.

<script setup lang="ts">
import { useHabit } from 'habicron/vue'

const { counter, nextRun, pause, resume } = useHabit(post, {
  controls: true,
  every: '20s ~ 4s',
})
</script>

<template>
  <p>fired {{ counter }}× · next at {{ nextRun?.toLocaleTimeString() }}</p>
  <button @click="pause">Pause</button>
</template>

useHabits() returns a reactive Readonly<Ref<HabitSummary[]>> — a ready-made management view that updates as habits fire or come and go.

useHabit returns plain values (not refs) that re-render on change. The controller is created inside an effect, so it is SSR-safe; the callback is always read fresh, so closing over changing props is safe.

import { useHabit } from 'habicron/react'

function Reminder() {
  const { counter, nextRun, pause } = useHabit(
    () => notify('Drink water'),
    { controls: true, every: '1h ~ 8m' },
  )
  return (
    <p>
      fired {counter}× · next at {nextRun?.toLocaleTimeString()}
      <button onClick={pause}>Pause</button>
    </p>
  )
}

useHabits() returns HabitSummary[], re-rendering as habits change.

In both Vue and React, control members appear only when controls: true — the return type is exact, expressed through overloads with no casting.

The callback fires on the union of all habits in the list.

useHabit(runAgent, {
  controls: true,
  habits: [
    { every: '2h ~ 20m' },                   // check the cat
    { times: 2, per: 'day', jitter: '90m' }, // twice a day
    { every: '3d', jitter: ['3h', '5h'] },   // every few days
  ],
})

The habit command runs any shell command on a randomized schedule — a lightweight process manager for habits. It works attached, or managed by a background daemon.

npm i -g habicron   # provides the `habit` command

Attached — fires in your terminal until you Ctrl-C:

habit run --every "10s ~ 2s" -- echo "stretch"

Managed — a background daemon keeps habits firing; manage them like processes:

habit start --name sync --every "1h ~ 5m" -- npm run sync   # create + run in background
habit start --times 3 --per day --jitter 2h -- ./backup.sh
habit list           # id, name, status, schedule, command, runs, next/last
habit logs sync      # recent output
habit stop sync      # pause   ·   habit start sync resumes it
habit restart sync
habit update sync --every 30m    # change the schedule live (or -- <new command>)
habit delete sync    # remove (alias: rm)
habit kill           # stop the daemon

habit list shows what each habit runs:

id  name  status   schedule     command       runs  next    last
1   sync  running  every 1h~5m   npm run sync  4     in 52m  8m ago

Habit definitions persist in ~/.habit/ (set HABIT_HOME to relocate); logs in ~/.habit/logs/<id>.log. The CLI is a single-host process manager — not a distributed or at-least-once scheduler.

The engine and adapters (node / browser / vue / react) are a runtime scheduler: in-process only, no persistence across reloads, no at-least-once delivery, no distributed coordination. Browser timers may be throttled in backgrounded tabs. For durable, distributed scheduling, reach for a server-side service (e.g. a queue or Durable Object alarms).

The habit CLI is the durable exception: it persists habit definitions to ~/.habit/ and runs them with a background daemon — but still as a single-host process manager.

pnpm install
pnpm lint           # eslint . --max-warnings 0
pnpm typecheck      # tsc --noEmit
pnpm test           # vitest run
pnpm build          # unbuild → dist/ (minified ESM + CJS + .d.ts)

MIT © thecodeorigin