hackhours 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# HackHours
+
+HackHours is a local-first, offline coding activity tracker inspired by WakaTime. It runs as a lightweight background watcher, records activity in ChronoDB, and provides rich CLI summaries.
+
+## Features
+- Local-first, offline-only storage (ChronoDB JSON files)
+- Automatic session tracking with idle detection
+- Language, project, and file breakdowns
+- Daily/weekly/monthly summaries with ASCII charts
+- Cross-platform CLI (Windows/macOS/Linux)
+
+## Install (local dev)
+```bash
+npm install
+```
+
+## Build
+```bash
+npm run build
+```
+
+## Initialize
+```bash
+hackhours init
+```
+
+## Start/Stop Tracking
+```bash
+hackhours start
+hackhours stop
+```
+
+## Reports
+```bash
+hackhours today
+hackhours week
+hackhours month
+hackhours stats --from 2026-02-01 --to 2026-02-28
+hackhours languages --from 2026-02-01 --to 2026-02-28
+hackhours projects --from 2026-02-01 --to 2026-02-28
+```
+
+## Config
+Config is stored at `~/.hackhours/config.json`:
+```json
+{
+  "directories": ["C:/work/my-project"],
+  "idleMinutes": 2,
+  "exclude": ["**/node_modules/**", "**/.git/**"],
+  "dataDir": "C:/Users/USER/.hackhours/data"
+}
+```
+
+## Data Storage (ChronoDB)
+Data is stored in `~/.hackhours/data` by default. Collections used:
+- `sessions`
+- `events`
+- `aggregates`
+
+## Shell Completions
+```bash
+source completions/hackhours.bash
+```
+For zsh, copy `completions/_hackhours` into your `$fpath`.
+
+## Tests
+```bash
+npm test
+```
+
+## Notes
+- `hackhours start` spawns a detached background process.
+- Use `hackhours stop` to end tracking cleanly.

package/completions/_hackhours

@@ -0,0 +1,34 @@
+#compdef hackhours
+
+_hackhours() {
+  local -a commands
+  commands=(
+    "init:Initialize config"
+    "start:Start background tracking"
+    "stop:Stop background tracking"
+    "today:Today's summary"
+    "week:Weekly summary"
+    "month:Monthly summary"
+    "stats:Custom stats"
+    "languages:Language breakdown"
+    "projects:Project breakdown"
+    "files:File breakdown"
+  )
+
+  _arguments -C \
+    "1:command:->command" \
+    "*::arg:->args"
+
+  case $state in
+    command)
+      _describe "command" commands
+      ;;
+    args)
+      _arguments \
+        "--from[Start date (YYYY-MM-DD)]" \
+        "--to[End date (YYYY-MM-DD)]"
+      ;;
+  esac
+}
+
+_hackhours "$@"

package/completions/hackhours.bash

@@ -0,0 +1,18 @@
+_hackhours_completions()
+{
+  local cur prev opts
+  COMPREPLY=()
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  prev="${COMP_WORDS[COMP_CWORD-1]}"
+  opts="init start stop today week month stats languages projects files --from --to --help --version"
+
+  if [[ ${cur} == -* ]] ; then
+    COMPREPLY=( $(compgen -W "--from --to --help --version" -- ${cur}) )
+    return 0
+  fi
+
+  COMPREPLY=( $(compgen -W "${opts}" -- ${cur}) )
+  return 0
+}
+
+complete -F _hackhours_completions hackhours

package/dist/analytics/queries.d.ts

@@ -0,0 +1,10 @@
+import { ChronoCollections } from "../storage/chrono.js";
+export type Summary = {
+    totalTimeMs: number;
+    filesEdited: Map<string, number>;
+    languages: Map<string, number>;
+    projects: Map<string, number>;
+    activityByHour: number[];
+    activityByDay: Map<string, number>;
+};
+export declare const buildSummary: (collections: ChronoCollections, from: number, to: number, idleMinutes: number) => Promise<Summary>;

package/dist/analytics/queries.js

@@ -0,0 +1,56 @@
+import { getEventsInRange, getSessionsInRange } from "../storage/queries.js";
+import { minutesToMs, toDateKey } from "../utils/time.js";
+const addToMap = (map, key, value) => {
+    map.set(key, (map.get(key) ?? 0) + value);
+};
+export const buildSummary = async (collections, from, to, idleMinutes) => {
+    const events = await getEventsInRange(collections, from, to);
+    const sessions = await getSessionsInRange(collections, from, to);
+    const idleMs = minutesToMs(idleMinutes);
+    const now = Date.now();
+    const sessionsById = new Map(sessions.map((s) => [s.sessionId, s]));
+    const eventsBySession = new Map();
+    for (const event of events) {
+        if (!eventsBySession.has(event.sessionId)) {
+            eventsBySession.set(event.sessionId, []);
+        }
+        eventsBySession.get(event.sessionId)?.push(event);
+    }
+    const summary = {
+        totalTimeMs: 0,
+        filesEdited: new Map(),
+        languages: new Map(),
+        projects: new Map(),
+        activityByHour: Array.from({ length: 24 }, () => 0),
+        activityByDay: new Map(),
+    };
+    for (const session of sessions) {
+        const sessionEnd = session.endTimestamp ?? now;
+        const overlapStart = Math.max(session.startTimestamp, from);
+        const overlapEnd = Math.min(sessionEnd, to);
+        if (overlapEnd > overlapStart) {
+            summary.totalTimeMs += overlapEnd - overlapStart;
+        }
+    }
+    for (const [sessionId, list] of eventsBySession.entries()) {
+        const session = sessionsById.get(sessionId);
+        const sessionEnd = session?.endTimestamp ?? now;
+        const sorted = [...list].sort((a, b) => a.timestamp - b.timestamp);
+        for (let i = 0; i < sorted.length; i += 1) {
+            const current = sorted[i];
+            const next = sorted[i + 1];
+            const nextTs = Math.min(next?.timestamp ?? sessionEnd, to);
+            const duration = Math.max(0, Math.min(nextTs - current.timestamp, idleMs));
+            if (duration <= 0)
+                continue;
+            addToMap(summary.languages, current.language, duration);
+            addToMap(summary.projects, current.project, duration);
+            addToMap(summary.filesEdited, current.filePath, duration);
+            const eventDate = new Date(current.timestamp);
+            const hour = eventDate.getHours();
+            summary.activityByHour[hour] += duration;
+            addToMap(summary.activityByDay, toDateKey(eventDate), duration);
+        }
+    }
+    return summary;
+};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import chalk from "chalk";
+import Table from "cli-table3";
+import * as asciichart from "asciichart";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+import { loadConfig, promptInitConfig, saveConfig, } from "./config/config.js";
+import { openChrono } from "./storage/chrono.js";
+import { buildSummary } from "./analytics/queries.js";
+import { runWatcher } from "./tracker/watcher.js";
+import { readState, writeState, clearState } from "./utils/state.js";
+import { endOfDay, formatDuration, parseDateKey, startOfDay } from "./utils/time.js";
+const program = new Command();
+const formatBar = (value, total, size = 16) => {
+    if (total <= 0)
+        return " ".repeat(size);
+    const filled = Math.round((value / total) * size);
+    return `${"█".repeat(filled)}${" ".repeat(size - filled)}`;
+};
+const printSummary = (title, summary) => {
+    const total = summary.totalTimeMs;
+    console.log(chalk.bold(`\n${title}`));
+    console.log(`${chalk.cyan("Total:")} ${formatDuration(total)}`);
+    console.log(`${chalk.cyan("Files edited:")} ${summary.filesEdited.size}`);
+    const langEntries = [...summary.languages.entries()].sort((a, b) => b[1] - a[1]);
+    if (langEntries.length > 0) {
+        console.log(`\n${chalk.cyan("Languages")}`);
+        const langTable = new Table({
+            head: ["Language", "Time", "%"],
+        });
+        for (const [lang, duration] of langEntries) {
+            langTable.push([lang, formatDuration(duration), `${Math.round((duration / total) * 100)}%`]);
+        }
+        console.log(langTable.toString());
+    }
+    console.log(`\n${chalk.cyan("Activity")}`);
+    const series = summary.activityByHour.map((ms) => Math.round(ms / 60000));
+    if (series.some((v) => v > 0)) {
+        console.log(asciichart.plot(series, { height: 8 }));
+    }
+    else {
+        console.log("No activity recorded.");
+    }
+};
+const printBreakdown = (title, map, total) => {
+    console.log(chalk.bold(`\n${title}`));
+    const entries = [...map.entries()].sort((a, b) => b[1] - a[1]);
+    if (entries.length === 0) {
+        console.log("No activity recorded.");
+        return;
+    }
+    const table = new Table({ head: ["Name", "Time", "%", ""] });
+    for (const [name, duration] of entries) {
+        const percent = total > 0 ? duration / total : 0;
+        table.push([name, formatDuration(duration), `${Math.round(percent * 100)}%`, formatBar(duration, total)]);
+    }
+    console.log(table.toString());
+};
+const parseRange = (from, to) => {
+    if (!from || !to) {
+        throw new Error("Both --from and --to are required.");
+    }
+    const fromDate = startOfDay(parseDateKey(from));
+    const toDate = endOfDay(parseDateKey(to));
+    return { from: fromDate.getTime(), to: toDate.getTime() };
+};
+program
+    .name("hackhours")
+    .description("Offline local-first coding activity tracker")
+    .version("0.1.0");
+program
+    .command("init")
+    .description("Initialize HackHours configuration")
+    .action(async () => {
+    const config = await promptInitConfig();
+    saveConfig(config);
+    console.log(chalk.green("Saved configuration to ~/.hackhours/config.json"));
+});
+program
+    .command("start")
+    .description("Start background tracking")
+    .action(async () => {
+    const existing = readState();
+    if (existing) {
+        try {
+            process.kill(existing.pid, 0);
+            console.log(chalk.yellow("HackHours is already running."));
+            return;
+        }
+        catch {
+            clearState();
+        }
+    }
+    const node = process.execPath;
+    const cli = path.resolve(process.argv[1]);
+    const child = spawn(node, [cli, "daemon"], {
+        detached: true,
+        stdio: "ignore",
+    });
+    child.unref();
+    writeState({ pid: child.pid ?? 0, startedAt: Date.now() });
+    console.log(chalk.green("HackHours tracking started."));
+});
+program
+    .command("stop")
+    .description("Stop background tracking")
+    .action(() => {
+    const state = readState();
+    if (!state) {
+        console.log(chalk.yellow("HackHours is not running."));
+        return;
+    }
+    try {
+        process.kill(state.pid);
+        clearState();
+        console.log(chalk.green("HackHours tracking stopped."));
+    }
+    catch {
+        clearState();
+        console.log(chalk.yellow("HackHours was not running."));
+    }
+});
+program
+    .command("daemon")
+    .description("Run watcher in foreground (internal)")
+    .action(async () => {
+    const config = loadConfig();
+    const { collections } = await openChrono(config.dataDir);
+    const watcher = await runWatcher(config, collections);
+    const shutdown = async () => {
+        await watcher.stop();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+});
+program
+    .command("today")
+    .description("Show today's summary")
+    .action(async () => {
+    const config = loadConfig();
+    const { collections } = await openChrono(config.dataDir);
+    const now = new Date();
+    const from = startOfDay(now).getTime();
+    const to = endOfDay(now).getTime();
+    const summary = await buildSummary(collections, from, to, config.idleMinutes);
+    printSummary("HackHours – Today", summary);
+});
+program
+    .command("week")
+    .description("Show weekly summary")
+    .action(async () => {
+    const config = loadConfig();
+    const { collections } = await openChrono(config.dataDir);
+    const now = new Date();
+    const fromDate = new Date(now);
+    fromDate.setDate(fromDate.getDate() - 6);
+    const from = startOfDay(fromDate).getTime();
+    const to = endOfDay(now).getTime();
+    const summary = await buildSummary(collections, from, to, config.idleMinutes);
+    printSummary("HackHours – Last 7 Days", summary);
+});
+program
+    .command("month")
+    .description("Show monthly summary")
+    .action(async () => {
+    const config = loadConfig();
+    const { collections } = await openChrono(config.dataDir);
+    const now = new Date();
+    const fromDate = new Date(now);
+    fromDate.setDate(fromDate.getDate() - 29);
+    const from = startOfDay(fromDate).getTime();
+    const to = endOfDay(now).getTime();
+    const summary = await buildSummary(collections, from, to, config.idleMinutes);
+    printSummary("HackHours – Last 30 Days", summary);
+});
+program
+    .command("stats")
+    .description("Custom stats for a given range")
+    .requiredOption("--from <date>", "Start date (YYYY-MM-DD)")
+    .requiredOption("--to <date>", "End date (YYYY-MM-DD)")
+    .action(async (options) => {
+    const config = loadConfig();
+    const { collections } = await openChrono(config.dataDir);
+    const range = parseRange(options.from, options.to);
+    const summary = await buildSummary(collections, range.from, range.to, config.idleMinutes);
+    printSummary(`HackHours – ${options.from} to ${options.to}`, summary);
+});
+program
+    .command("languages")
+    .description("Language breakdown")
+    .option("--from <date>", "Start date (YYYY-MM-DD)")
+    .option("--to <date>", "End date (YYYY-MM-DD)")
+    .action(async (options) => {
+    const config = loadConfig();
+    const { collections } = await openChrono(config.dataDir);
+    let from;
+    let to;
+    if (options.from && options.to) {
+        const range = parseRange(options.from, options.to);
+        from = range.from;
+        to = range.to;
+    }
+    else {
+        const now = new Date();
+        const fromDate = new Date(now);
+        fromDate.setDate(fromDate.getDate() - 6);
+        from = startOfDay(fromDate).getTime();
+        to = endOfDay(now).getTime();
+    }
+    const summary = await buildSummary(collections, from, to, config.idleMinutes);
+    printBreakdown("Languages", summary.languages, summary.totalTimeMs);
+});
+program
+    .command("projects")
+    .description("Project breakdown")
+    .option("--from <date>", "Start date (YYYY-MM-DD)")
+    .option("--to <date>", "End date (YYYY-MM-DD)")
+    .action(async (options) => {
+    const config = loadConfig();
+    const { collections } = await openChrono(config.dataDir);
+    let from;
+    let to;
+    if (options.from && options.to) {
+        const range = parseRange(options.from, options.to);
+        from = range.from;
+        to = range.to;
+    }
+    else {
+        const now = new Date();
+        const fromDate = new Date(now);
+        fromDate.setDate(fromDate.getDate() - 6);
+        from = startOfDay(fromDate).getTime();
+        to = endOfDay(now).getTime();
+    }
+    const summary = await buildSummary(collections, from, to, config.idleMinutes);
+    printBreakdown("Projects", summary.projects, summary.totalTimeMs);
+});
+program
+    .command("files")
+    .description("File breakdown (top 10)")
+    .option("--from <date>", "Start date (YYYY-MM-DD)")
+    .option("--to <date>", "End date (YYYY-MM-DD)")
+    .action(async (options) => {
+    const config = loadConfig();
+    const { collections } = await openChrono(config.dataDir);
+    let from;
+    let to;
+    if (options.from && options.to) {
+        const range = parseRange(options.from, options.to);
+        from = range.from;
+        to = range.to;
+    }
+    else {
+        const now = new Date();
+        const fromDate = new Date(now);
+        fromDate.setDate(fromDate.getDate() - 6);
+        from = startOfDay(fromDate).getTime();
+        to = endOfDay(now).getTime();
+    }
+    const summary = await buildSummary(collections, from, to, config.idleMinutes);
+    const top = [...summary.filesEdited.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 10);
+    const total = summary.totalTimeMs;
+    const table = new Table({ head: ["File", "Time", "%"] });
+    for (const [file, duration] of top) {
+        table.push([file, formatDuration(duration), `${Math.round((duration / total) * 100)}%`]);
+    }
+    console.log(table.toString());
+});
+program.parseAsync(process.argv);

package/dist/config/config.d.ts

@@ -0,0 +1,11 @@
+export type HackHoursConfig = {
+    directories: string[];
+    idleMinutes: number;
+    exclude: string[];
+    dataDir: string;
+};
+export declare const getDefaultConfig: () => HackHoursConfig;
+export declare const ensureConfigDir: (configPath?: string) => void;
+export declare const loadConfig: (configPath?: string) => HackHoursConfig;
+export declare const saveConfig: (config: HackHoursConfig, configPath?: string) => void;
+export declare const promptInitConfig: () => Promise<HackHoursConfig>;

package/dist/config/config.js

@@ -0,0 +1,77 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import inquirer from "inquirer";
+import { DEFAULT_CONFIG_PATH, DEFAULT_DATA_DIR, DEFAULT_EXCLUDE, DEFAULT_IDLE_MINUTES, } from "./defaults.js";
+export const getDefaultConfig = () => ({
+    directories: [process.cwd()],
+    idleMinutes: DEFAULT_IDLE_MINUTES,
+    exclude: DEFAULT_EXCLUDE,
+    dataDir: DEFAULT_DATA_DIR,
+});
+export const ensureConfigDir = (configPath = DEFAULT_CONFIG_PATH) => {
+    const dir = path.dirname(configPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+};
+export const loadConfig = (configPath = DEFAULT_CONFIG_PATH) => {
+    if (!fs.existsSync(configPath)) {
+        return getDefaultConfig();
+    }
+    const raw = fs.readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    return {
+        ...getDefaultConfig(),
+        ...parsed,
+    };
+};
+export const saveConfig = (config, configPath = DEFAULT_CONFIG_PATH) => {
+    ensureConfigDir(configPath);
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");
+};
+export const promptInitConfig = async () => {
+    const defaultConfig = getDefaultConfig();
+    const answers = await inquirer.prompt([
+        {
+            type: "input",
+            name: "directories",
+            message: "Which directories should HackHours track? (comma-separated)",
+            default: defaultConfig.directories.join(", "),
+            filter: (input) => input
+                .split(",")
+                .map((v) => v.trim())
+                .filter(Boolean),
+        },
+        {
+            type: "number",
+            name: "idleMinutes",
+            message: "Idle timeout in minutes",
+            default: defaultConfig.idleMinutes,
+        },
+        {
+            type: "input",
+            name: "exclude",
+            message: "Exclude globs (comma-separated)",
+            default: defaultConfig.exclude.join(", "),
+            filter: (input) => input
+                .split(",")
+                .map((v) => v.trim())
+                .filter(Boolean),
+        },
+        {
+            type: "input",
+            name: "dataDir",
+            message: "Data directory",
+            default: defaultConfig.dataDir,
+            filter: (input) => input.trim(),
+        },
+    ]);
+    const expanded = answers.dataDir.replace(/^~\//, `${os.homedir()}/`);
+    return {
+        directories: answers.directories,
+        idleMinutes: answers.idleMinutes,
+        exclude: answers.exclude,
+        dataDir: expanded,
+    };
+};

package/dist/config/defaults.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_IDLE_MINUTES = 2;
+export declare const DEFAULT_CONFIG_PATH: string;
+export declare const DEFAULT_DATA_DIR: string;
+export declare const DEFAULT_EXCLUDE: string[];

package/dist/config/defaults.js

@@ -0,0 +1,17 @@
+import os from "node:os";
+import path from "node:path";
+export const DEFAULT_IDLE_MINUTES = 2;
+export const DEFAULT_CONFIG_PATH = path.join(os.homedir(), ".hackhours", "config.json");
+export const DEFAULT_DATA_DIR = path.join(os.homedir(), ".hackhours", "data");
+export const DEFAULT_EXCLUDE = [
+    "**/node_modules/**",
+    "**/.git/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/.turbo/**",
+    "**/.cache/**",
+    "**/.idea/**",
+    "**/.vscode/**",
+    "**/*.log",
+];

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./config/config.js";
+export * from "./storage/chrono.js";
+export * from "./tracker/watcher.js";
+export * from "./analytics/queries.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./config/config.js";
+export * from "./storage/chrono.js";
+export * from "./tracker/watcher.js";
+export * from "./analytics/queries.js";

package/dist/storage/chrono.d.ts

@@ -0,0 +1,11 @@
+import { AggregateDoc, EventDoc, SessionDoc } from "./schema.js";
+export type ChronoCollections = {
+    sessions: any;
+    events: any;
+    aggregates: any;
+};
+export declare const openChrono: (dataDir: string) => Promise<{
+    db: any;
+    collections: ChronoCollections;
+}>;
+export type { AggregateDoc, EventDoc, SessionDoc };

package/dist/storage/chrono.js

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import ChronoDB from "chronodb";
+import { aggregateSchema, eventSchema, sessionSchema, } from "./schema.js";
+export const openChrono = async (dataDir) => {
+    fs.mkdirSync(dataDir, { recursive: true });
+    let db;
+    try {
+        db = await ChronoDB.open({ path: dataDir, cloudSync: false });
+    }
+    catch (error) {
+        const prev = process.cwd();
+        process.chdir(dataDir);
+        try {
+            db = await ChronoDB.open({ cloudSync: false });
+        }
+        catch (inner) {
+            process.chdir(prev);
+            throw inner;
+        }
+    }
+    const sessions = db.col("sessions", {
+        schema: sessionSchema,
+        indexes: ["sessionId", "startTimestamp", "endTimestamp"],
+    });
+    const events = db.col("events", {
+        schema: eventSchema,
+        indexes: ["timestamp", "language", "project", "sessionId"],
+    });
+    const aggregates = db.col("aggregates", {
+        schema: aggregateSchema,
+        indexes: ["date"],
+    });
+    return {
+        db,
+        collections: { sessions, events, aggregates },
+    };
+};

package/dist/storage/queries.d.ts

@@ -0,0 +1,4 @@
+import { ChronoCollections, EventDoc, SessionDoc } from "./chrono.js";
+export declare const getSessionsInRange: (collections: ChronoCollections, from: number, to: number) => Promise<SessionDoc[]>;
+export declare const getEventsInRange: (collections: ChronoCollections, from: number, to: number) => Promise<EventDoc[]>;
+export declare const getAggregateByDate: (collections: ChronoCollections, date: string) => Promise<any>;

package/dist/storage/queries.js

@@ -0,0 +1,14 @@
+export const getSessionsInRange = async (collections, from, to) => {
+    const all = (await collections.sessions.getAll());
+    return all.filter((s) => {
+        const end = s.endTimestamp ?? s.startTimestamp;
+        return s.startTimestamp <= to && end >= from;
+    });
+};
+export const getEventsInRange = async (collections, from, to) => {
+    const all = (await collections.events.getAll());
+    return all.filter((e) => e.timestamp >= from && e.timestamp <= to);
+};
+export const getAggregateByDate = async (collections, date) => {
+    return collections.aggregates.getOne({ date });
+};

package/dist/storage/schema.d.ts

@@ -0,0 +1,77 @@
+export type SessionDoc = {
+    sessionId: string;
+    startTimestamp: number;
+    endTimestamp: number | null;
+    durationMs: number;
+};
+export type EventDoc = {
+    timestamp: number;
+    filePath: string;
+    language: string;
+    project: string;
+    sessionId: string;
+};
+export type AggregateDoc = {
+    date: string;
+    totalTimeMs: number;
+    filesEdited: string;
+    languagesUsed: string;
+};
+export declare const sessionSchema: {
+    sessionId: {
+        type: string;
+        distinct: boolean;
+    };
+    startTimestamp: {
+        type: string;
+        important: boolean;
+    };
+    endTimestamp: {
+        type: string;
+        nullable: boolean;
+    };
+    durationMs: {
+        type: string;
+        default: number;
+    };
+};
+export declare const eventSchema: {
+    timestamp: {
+        type: string;
+        important: boolean;
+    };
+    filePath: {
+        type: string;
+        important: boolean;
+    };
+    language: {
+        type: string;
+        important: boolean;
+    };
+    project: {
+        type: string;
+        important: boolean;
+    };
+    sessionId: {
+        type: string;
+        important: boolean;
+    };
+};
+export declare const aggregateSchema: {
+    date: {
+        type: string;
+        distinct: boolean;
+    };
+    totalTimeMs: {
+        type: string;
+        default: number;
+    };
+    filesEdited: {
+        type: string;
+        default: string;
+    };
+    languagesUsed: {
+        type: string;
+        default: string;
+    };
+};

package/dist/storage/schema.js

@@ -0,0 +1,19 @@
+export const sessionSchema = {
+    sessionId: { type: "string", distinct: true },
+    startTimestamp: { type: "number", important: true },
+    endTimestamp: { type: "number", nullable: true },
+    durationMs: { type: "number", default: 0 },
+};
+export const eventSchema = {
+    timestamp: { type: "number", important: true },
+    filePath: { type: "string", important: true },
+    language: { type: "string", important: true },
+    project: { type: "string", important: true },
+    sessionId: { type: "string", important: true },
+};
+export const aggregateSchema = {
+    date: { type: "string", distinct: true },
+    totalTimeMs: { type: "number", default: 0 },
+    filesEdited: { type: "string", default: "[]" },
+    languagesUsed: { type: "string", default: "[]" },
+};

package/dist/tracker/session.d.ts

@@ -0,0 +1,14 @@
+import { HackHoursConfig } from "../config/config.js";
+import { ChronoCollections } from "../storage/chrono.js";
+export declare class SessionManager {
+    private active;
+    private idleMs;
+    private config;
+    private collections;
+    constructor(config: HackHoursConfig, collections: ChronoCollections);
+    handleActivity(filePath: string): Promise<void>;
+    checkIdle(): Promise<void>;
+    stop(): Promise<void>;
+    private startSession;
+    private endSession;
+}

package/dist/tracker/session.js

@@ -0,0 +1,78 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { detectLanguage } from "../utils/language.js";
+import { resolveProjectRoot } from "../utils/project.js";
+import { minutesToMs, toDateKey } from "../utils/time.js";
+export class SessionManager {
+    constructor(config, collections) {
+        this.active = null;
+        this.config = config;
+        this.collections = collections;
+        this.idleMs = minutesToMs(config.idleMinutes);
+    }
+    async handleActivity(filePath) {
+        const now = Date.now();
+        if (!this.active) {
+            this.active = await this.startSession(now);
+        }
+        this.active.lastActivity = now;
+        const language = detectLanguage(filePath);
+        const projectRoot = resolveProjectRoot(filePath, this.config.directories);
+        await this.collections.events.add({
+            timestamp: now,
+            filePath: path.resolve(filePath),
+            language,
+            project: projectRoot,
+            sessionId: this.active.sessionId,
+        });
+    }
+    async checkIdle() {
+        if (!this.active)
+            return;
+        const now = Date.now();
+        if (now - this.active.lastActivity > this.idleMs) {
+            await this.endSession(this.active, this.active.lastActivity);
+            this.active = null;
+        }
+    }
+    async stop() {
+        if (!this.active)
+            return;
+        await this.endSession(this.active, this.active.lastActivity);
+        this.active = null;
+    }
+    async startSession(startTimestamp) {
+        const sessionId = crypto.randomUUID();
+        await this.collections.sessions.add({
+            sessionId,
+            startTimestamp,
+            endTimestamp: null,
+            durationMs: 0,
+        });
+        return {
+            sessionId,
+            startTimestamp,
+            lastActivity: startTimestamp,
+        };
+    }
+    async endSession(session, endTimestamp) {
+        const durationMs = Math.max(0, endTimestamp - session.startTimestamp);
+        await this.collections.sessions.updateMany({ sessionId: session.sessionId }, {
+            endTimestamp,
+            durationMs,
+        });
+        const dateKey = toDateKey(new Date(endTimestamp));
+        const existing = await this.collections.aggregates.getOne({ date: dateKey });
+        if (!existing) {
+            await this.collections.aggregates.add({
+                date: dateKey,
+                totalTimeMs: durationMs,
+                filesEdited: "[]",
+                languagesUsed: "[]",
+            });
+        }
+        else {
+            await this.collections.aggregates.updateMany({ date: dateKey }, { totalTimeMs: (existing.totalTimeMs ?? 0) + durationMs });
+        }
+    }
+}

package/dist/tracker/watcher.d.ts

@@ -0,0 +1,6 @@
+import { HackHoursConfig } from "../config/config.js";
+import { ChronoCollections } from "../storage/chrono.js";
+export type WatcherHandle = {
+    stop: () => Promise<void>;
+};
+export declare const runWatcher: (config: HackHoursConfig, collections: ChronoCollections) => Promise<WatcherHandle>;

package/dist/tracker/watcher.js

@@ -0,0 +1,25 @@
+import chokidar from "chokidar";
+import { SessionManager } from "./session.js";
+export const runWatcher = async (config, collections) => {
+    const sessionManager = new SessionManager(config, collections);
+    const watcher = chokidar.watch(config.directories, {
+        ignored: config.exclude,
+        ignoreInitial: true,
+        persistent: true,
+    });
+    const onActivity = (filePath) => {
+        sessionManager.handleActivity(filePath).catch(() => undefined);
+    };
+    watcher.on("add", onActivity);
+    watcher.on("change", onActivity);
+    const interval = setInterval(() => {
+        sessionManager.checkIdle().catch(() => undefined);
+    }, 10000);
+    return {
+        stop: async () => {
+            clearInterval(interval);
+            await watcher.close();
+            await sessionManager.stop();
+        },
+    };
+};

package/dist/utils/language.d.ts

@@ -0,0 +1 @@
+export declare const detectLanguage: (filePath: string) => string;

package/dist/utils/language.js

@@ -0,0 +1,42 @@
+import path from "node:path";
+const EXTENSION_MAP = {
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    ".js": "JavaScript",
+    ".jsx": "JavaScript",
+    ".mjs": "JavaScript",
+    ".cjs": "JavaScript",
+    ".py": "Python",
+    ".go": "Go",
+    ".rs": "Rust",
+    ".java": "Java",
+    ".kt": "Kotlin",
+    ".c": "C",
+    ".h": "C",
+    ".cpp": "C++",
+    ".hpp": "C++",
+    ".cs": "C#",
+    ".rb": "Ruby",
+    ".php": "PHP",
+    ".swift": "Swift",
+    ".dart": "Dart",
+    ".lua": "Lua",
+    ".sh": "Shell",
+    ".bash": "Shell",
+    ".zsh": "Shell",
+    ".ps1": "PowerShell",
+    ".json": "JSON",
+    ".yml": "YAML",
+    ".yaml": "YAML",
+    ".toml": "TOML",
+    ".md": "Markdown",
+    ".html": "HTML",
+    ".css": "CSS",
+    ".scss": "SCSS",
+    ".less": "LESS",
+    ".sql": "SQL",
+};
+export const detectLanguage = (filePath) => {
+    const ext = path.extname(filePath).toLowerCase();
+    return EXTENSION_MAP[ext] ?? "Other";
+};

package/dist/utils/project.d.ts

@@ -0,0 +1,2 @@
+export declare const resolveProjectRoot: (filePath: string, directories: string[]) => string;
+export declare const formatProjectName: (projectRoot: string) => string;

package/dist/utils/project.js

@@ -0,0 +1,10 @@
+import path from "node:path";
+export const resolveProjectRoot = (filePath, directories) => {
+    const normalized = path.resolve(filePath);
+    const match = directories
+        .map((dir) => path.resolve(dir))
+        .filter((dir) => normalized.startsWith(dir))
+        .sort((a, b) => b.length - a.length)[0];
+    return match ?? path.dirname(normalized);
+};
+export const formatProjectName = (projectRoot) => path.basename(projectRoot);

package/dist/utils/state.d.ts

@@ -0,0 +1,8 @@
+export type DaemonState = {
+    pid: number;
+    startedAt: number;
+};
+export declare const statePath: () => string;
+export declare const readState: () => DaemonState | null;
+export declare const writeState: (state: DaemonState) => void;
+export declare const clearState: () => void;

package/dist/utils/state.js

@@ -0,0 +1,25 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const statePath = () => path.join(os.homedir(), ".hackhours", "state.json");
+export const readState = () => {
+    const file = statePath();
+    if (!fs.existsSync(file))
+        return null;
+    const raw = fs.readFileSync(file, "utf-8");
+    return JSON.parse(raw);
+};
+export const writeState = (state) => {
+    const file = statePath();
+    const dir = path.dirname(file);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(file, JSON.stringify(state, null, 2), "utf-8");
+};
+export const clearState = () => {
+    const file = statePath();
+    if (fs.existsSync(file)) {
+        fs.unlinkSync(file);
+    }
+};

package/dist/utils/time.d.ts

@@ -0,0 +1,7 @@
+export declare const minutesToMs: (minutes: number) => number;
+export declare const startOfDay: (date: Date) => Date;
+export declare const endOfDay: (date: Date) => Date;
+export declare const toDateKey: (date: Date) => string;
+export declare const parseDateKey: (value: string) => Date;
+export declare const formatDuration: (ms: number) => string;
+export declare const formatPercent: (value: number) => string;

package/dist/utils/time.js

@@ -0,0 +1,35 @@
+export const minutesToMs = (minutes) => minutes * 60 * 1000;
+export const startOfDay = (date) => {
+    const d = new Date(date);
+    d.setHours(0, 0, 0, 0);
+    return d;
+};
+export const endOfDay = (date) => {
+    const d = new Date(date);
+    d.setHours(23, 59, 59, 999);
+    return d;
+};
+export const toDateKey = (date) => {
+    const year = date.getFullYear();
+    const month = `${date.getMonth() + 1}`.padStart(2, "0");
+    const day = `${date.getDate()}`.padStart(2, "0");
+    return `${year}-${month}-${day}`;
+};
+export const parseDateKey = (value) => {
+    const [year, month, day] = value.split("-").map(Number);
+    if (!year || !month || !day) {
+        throw new Error(`Invalid date: ${value}`);
+    }
+    return new Date(year, month - 1, day);
+};
+export const formatDuration = (ms) => {
+    if (ms <= 0)
+        return "0m";
+    const totalMinutes = Math.round(ms / 60000);
+    const hours = Math.floor(totalMinutes / 60);
+    const minutes = totalMinutes % 60;
+    if (hours === 0)
+        return `${minutes}m`;
+    return `${hours}h ${minutes}m`;
+};
+export const formatPercent = (value) => `${(value * 100).toFixed(0)}%`;

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "hackhours",
+  "version": "0.1.0",
+  "description": "Offline local-first coding activity tracker",
+  "type": "module",
+  "bin": {
+    "hackhours": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "completions"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "productivity",
+    "cli",
+    "tracking",
+    "offline"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "asciichart": "^1.5.25",
+    "chalk": "^5.3.0",
+    "chokidar": "^3.6.0",
+    "chronodb": "^1.0.0",
+    "cli-table3": "^0.6.3",
+    "commander": "^11.1.0",
+    "inquirer": "^9.2.20"
+  },
+  "devDependencies": {
+    "@types/asciichart": "^1.5.8",
+    "@types/inquirer": "^9.0.9",
+    "@types/node": "^20.11.30",
+    "tsx": "^4.7.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.4.0"
+  }
+}