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.
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, Tree, 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
Milestr is distributed on npm. The fastest path for an agent or human is the global install:
npm install -g milestrAfter install, verify the binary is on PATH:
which milestr # → /usr/local/bin/milestr (or your npm global prefix)
milestr help # → prints the full action listTo confirm the installed version, check the package metadata:
npm list -g milestr # → milestr@1.1.1- Node.js ≥ 22 (Active LTS). Earlier versions are not supported.
- npm (ships with Node.js)
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 listEvery milestr invocation reads from that directory until you unset the variable.
git clone https://github.com/Dr-Agentic/milestr.git
cd milestr
npm install
npm run build
npm testRun from source with npm run dev -- <args> (note the -- to pass args through npm).
- 📋 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 + Tree + 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 —
--jsonflag for machine-parseable responses onview,list,list-kpis, andmetrics
npm installnpm run dev -- --agent your-agent-name create --id M1 --title "First Milestone" --type milestonenpm run dev -- --agent your-agent-name status M1 ongoing
npm run dev -- --agent your-agent-name progress M1 50npm 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 upopen dashboard.htmlThe dashboard ships with five views:
- KPIs — live KPI cards with values, trends, and sources
- Timeline — milestones rendered as a horizontal lane with progress bars
- Tree — right-to-left hierarchical tree of goals → milestones → initiatives → tasks, with progressive disclosure (click a node to expand, click its title to zoom in,
Escto zoom out,+/-to expand/collapse all) - Kanban — tasks grouped by status (not_started / analyzing / ongoing / done / blocked)
- List — flat task list with id, title, status, progress, and parent
# 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
# Append a free-text entry to a task's activity log
npm run dev -- --agent <name> log <id> "<message>"
# 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>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" }
}
}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
- 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
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
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`);MIT — use it, fork it, make it yours.
Milestr: Every goal, tracked. Every step, accountable.