Milestr — AI Agent Goal & Milestone Dashboard

OpenCLAW and Hermes agent-powered milestone tracking dashboard. Built for AI agents to manage large projects, track progress, and maintain accountability across goals, milestones, initiatives, tasks, and KPIs.

What is Milestr?

Milestr is a lightweight, terminal-driven project and milestone tracking dashboard designed for AI agents (and humans) who need to track progress, log activity, and visualize KPIs across goals, milestones, initiatives, tasks, and KPIs.

It gives agents a structured way to:

• Track progress across goals, milestones, initiatives, and tasks
• Log activity with timestamps and agent attribution
• Visualize via a self-updating HTML dashboard (KPIs + Timeline, Kanban, List views)
• Stay accountable — every change is logged, every status update is recorded
• Track KPIs — live KPI cards with values, trends, and data sources

Installation

Milestr is distributed on npm. The fastest path for an agent or human is the global install:

npm install -g milestr

After install, verify the binary is on PATH:

which milestr          # → /usr/local/bin/milestr (or your npm global prefix)
milestr help           # → prints the full action list

To confirm the installed version, check the package metadata:

npm list -g milestr    # → [email protected]

Requirements

• Node.js ≥ 22 (Active LTS). Earlier versions are not supported.
• npm (ships with Node.js)

Where Milestr reads its data

The CLI reads and writes data.json in the current working directory by default. To pin a specific working directory across many commands, set MILESTR_DATA:

export MILESTR_DATA=/path/to/your/dashboard    # must contain data.json
milestr --agent planner list

Every milestr invocation reads from that directory until you unset the variable.

Installing from source (for contributors)

git clone https://github.com/Dr-Agentic/milestr.git
cd milestr
npm install
npm run build
npm test

Run from source with npm run dev -- <args> (note the -- to pass args through npm).

Features

• 📋 Hierarchical task structure — Goals → Milestones → Initiatives → Tasks
• 📊 Auto-calculated progress — parent progress cascades from children
• 🕐 Activity log — every change is timestamped and attributed to an agent
• 📈 KPI tracking — live KPI cards with values, trends, and data sources
• 🖥️ HTML Dashboard — KPIs + Timeline + Kanban + List views, generated on every update
• 💾 Backup & restore — automatic backups before every write
• 🔌 CLI-first — designed for agents to interact with via shell commands
• 📤 JSON output — --json flag for machine-parseable responses on view, list, list-kpis, and metrics

Quick Start

Install dependencies

npm install

Initialize the dashboard

npm run dev -- --agent your-agent-name create --id M1 --title "First Milestone" --type milestone

Update status

npm run dev -- --agent your-agent-name status M1 ongoing
npm run dev -- --agent your-agent-name progress M1 50

Add and update KPIs

npm run dev -- --agent your-agent create-kpi --id kpi-users --title "Active Users" --value 0 --unit users --source "Product analytics"
npm run dev -- --agent your-agent update-kpi --id kpi-users --value 42 --trend up

View the HTML dashboard

open dashboard.html

Docs

• User Guide
• Developer Guide
• Agent Skill

CLI Reference

# Create a task
npm run dev -- --agent <name> create --id <id> --title <title> [--type task|initiative|milestone|goal] [--parent <parent-id>] [--due YYYY-MM-DD]

# Update status
npm run dev -- --agent <name> status <id> <status> [note]
# Statuses: not_started | analyzing | ongoing | done | blocked

# Update progress
npm run dev -- --agent <name> progress <id> <0-100>

# Set due date
npm run dev -- --agent <name> due <id> YYYY-MM-DD

# List tasks
npm run dev -- --agent <name> list [--status ongoing] [--type milestone]

# View task
npm run dev -- --agent <name> view <id>

# Recalculate parent progress from children
npm run dev -- --agent <name> recalc <id>

# --- KPI Actions ---

# Create a KPI
npm run dev -- --agent <name> create-kpi --id <id> --title <title> [--value <val>] [--unit <unit>] [--trend up|down|neutral] [--source <source>] [--icon <emoji>]

# Update a KPI value
npm run dev -- --agent <name> update-kpi --id <id> [--value <val>] [--trend up|down|neutral]

# List all KPIs
npm run dev -- --agent <name> list-kpis

# --- Dashboard Actions ---

# Export dashboard
npm run dev -- --agent <name> export

# Publish dashboard to Cloudflare Pages
npm run dev -- --agent <name> publish

# Backups
npm run dev -- --agent <name> backup
npm run dev -- --agent <name> backups
npm run dev -- --agent <name> restore <timestamp>

Data Model

The dashboard stores its state in data.json:

{
  "meta": { "lastUpdated": "2026-04-12T00:00:00Z", "version": "1.1" },
  "root": { /* Goal-level root task */ },
  "tasks": {
    "M1": { /* milestone task */ },
    "I1.1": { /* initiative task */ }
  },
  "kpis": {
    "kpi-users": { "id": "kpi-users", "title": "Active Users", "value": 42, "unit": "users", "trend": "up", "source": "Product analytics", "icon": "people", "lastUpdated": "2026-04-12T00:00:00Z" }
  }
}

Perfect for Agents

Milestr was designed from the ground up to be agent-friendly:

• Deterministic CLI — every action has a clear command, no ambiguity
• Atomic writes — every save creates a backup first
• Activity log — agents can review their own history of changes
• KPI tracking — agents can update business KPIs as they discover new data
• No UI required — agents interact entirely via terminal; humans read the HTML dashboard
• Zero human intervention — agents can own and operate their own projects

Example agent use cases:

• Strategy Officer agent tracks M1–M5 milestones toward an ARR goal, plus KPIs like sign-ups, MRR, and churn
• Engineering agent tracks features, bug fixes, and deployment readiness
• Marketing agent tracks campaigns, content calendars, and lead funnels, plus KPIs like impressions and clicks
• Research agent tracks experiments, hypotheses, and findings

Project Structure

milestr/
├── src/
│   ├── index.ts          # CLI entry point
│   ├── types.ts          # TypeScript interfaces + KPI interface
│   ├── errors.ts         # Custom error types
│   ├── actions/
│   │   ├── handlers.ts   # Action handlers (create, status, progress, create-kpi, update-kpi...)
│   │   └── utils.ts      # Shared utilities
│   ├── data/
│   │   ├── store.ts      # JSON read/write + validation
│   │   ├── schema.ts     # Zod schema (includes KPI schema)
│   │   ├── backup.ts      # Backup management
│   │   ├── logger.ts     # Activity logging
│   │   ├── config.ts     # Config paths
│   │   └── lock.ts       # File locking
│   └── ui/
│       └── dashboardHtml.ts  # HTML dashboard generator (KPIs + Timeline + Kanban + List)
├── data.json             # Project data (generic sample at HEAD — replace with your own)
├── sample-data.json      # Canonical generic sample (kept in sync with data.json at HEAD)
├── dashboard.html        # Generated HTML dashboard
├── package.json
└── tsconfig.json

OpenCLAW Integration

Milestr is designed to run as an agent-owned tool within OpenCLAW. Agents call the CLI directly via exec calls, passing their agent name for attribution.

Example OpenCLAW agent task file:

// Track a milestone
await exec(`npm run dev -- --agent planner status M1 ongoing`);

// Log a KPI update
await exec(`npm run dev -- --agent operator update-kpi --id kpi-users --value 42 --trend up`);

// View dashboard
await exec(`open dashboard.html`);

License

MIT — use it, fork it, make it yours.

Milestr: Every goal, tracked. Every step, accountable.