clawck 0.1.3 → 0.4.1

package/README.md

@@ -1,23 +1,11 @@
-# ⏱️🦀 Clawck
+# Clawck v0.4
 
 **Time tracking for AI agents. Toggl for the agentic era.**
 
-Clawck is an open-source tool that tracks how long AI agents spend on tasks, projects, and client work — then shows you how much human-equivalent time and money they saved.
+Clawck is an open-source tool that tracks how long AI agents spend on tasks, projects, and client work - then shows you how much human-equivalent time and money they saved.
 
 Every service business runs on timesheets. AI agent businesses will too.
 
----
-
-## Why Clawck?
-
-AI agents are doing real work — writing code, researching grants, generating content, analyzing data. But nobody's tracking *how long* that work takes or *how much value* it delivers.
-
-Clawck answers the questions your clients, managers, and finance teams are already asking:
-
-- **"What did the AI actually do today?"** → A clear timesheet showing every task, duration, and outcome
-- **"Is this worth what we're paying?"** → Human-equivalent hours and cost savings calculated automatically  
-- **"Which agent is the most productive?"** → Per-agent breakdowns across projects and clients
-
 ## Quick Start
 
 ```bash
@@ -27,37 +15,75 @@ npm install -g clawck
 # Initialize
 clawck init
 
-# Seed with sample data (to see the dashboard)
+# Seed with sample data
 clawck seed --count 30
 
 # Start the server + dashboard
 clawck serve
-# → Dashboard at http://localhost:3456
+# Open http://localhost:3456
+
+# Generate an interactive HTML report
+clawck report --format html
 ```
 
-## How It Works
+## Features
+
+- **Time tracking** - Start/stop timers or log completed tasks retroactively
+- **Human-equivalent calculations** - Configurable multipliers estimate how long a human would take
+- **Tracking patterns** - Reusable task templates (code-review, research, testing, etc.)
+- **Approval workflow** - Mark entries as approved for billing/invoicing
+- **Reports** - Terminal, PDF, and interactive HTML reports with calendar, table, Gantt, and CSV views
+- **Dashboard** - Real-time web dashboard with stats, entries, and breakdowns
+- **MCP server** - Works with Claude Code, Cline, Cursor, Windsurf via stdio
+- **REST API** - Full CRUD API for any agent framework
+- **Multi-agent sync** - Pull from remote instances or push via ingest endpoint
+- **Webhooks** - Notify on task completion, failure, or idle alerts
+- **Platform hooks** - Auto-track via Claude Code hooks, Gemini, Cursor, etc.
+- **PDF reports** - Professional timesheet PDFs with entry details table
+- **CSV/JSON export** - Export data for external tools
+
+## Getting Started
 
 ### 1. Agents clock in and out
 
-**Via MCP (Claude Code, Cline, Cursor, Windsurf):**
+**Via platform hooks (recommended — Claude Code, Cursor, Gemini, Windsurf, Codex):**
 
-Add to your MCP config (`~/.claude/mcp_servers.json` or similar):
+Hooks fire automatically on every turn — no agent cooperation needed.
+
+Claude Code — add to `~/.claude/settings.json`:
 
 ```json
 {
-  "clawck": {
-    "command": "npx",
-    "args": ["-y", "clawck", "mcp"]
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          { "type": "command", "command": "clawck hook start" }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "clawck hook stop" }
+        ]
+      }
+    ]
   }
 }
 ```
 
-Now your agent has access to:
-- `clawck_start_task` — Start a timer
-- `clawck_stop_task` — Stop a timer
-- `clawck_log_task` — Log a completed task retroactively
-- `clawck_status` — See what's running
-- `clawck_timesheet` — Get a summary report
+Or run `clawck hooks install claude` for the full config.
+
+**Via MCP (optional — for explicit agent control):**
+
+Add to `~/.claude/mcp_servers.json` (or equivalent for Cline, Cursor, Windsurf):
+
+```json
+{ "clawck": { "command": "npx", "args": ["-y", "clawck", "mcp"] } }
+```
+
+This gives agents `clawck_start_task`, `clawck_stop_task`, etc. for granular control. Add CLAUDE.md instructions (run `clawck setup claude`) to tell the agent to use them.
 
 **Via REST API:**
 
@@ -65,48 +91,31 @@ Now your agent has access to:
 # Start a task
 curl -X POST http://localhost:3456/api/start \
   -H "Content-Type: application/json" \
-  -d '{"task": "Research grant opportunities", "project": "grant-research", "client": "acme-corp", "category": "research", "agent": "cubi-research-01"}'
+  -d '{"task": "Research grant opportunities", "project": "grant-research", "client": "acme-corp", "category": "research", "agent": "research-agent-01"}'
 
 # Stop a task
 curl -X POST http://localhost:3456/api/stop \
   -H "Content-Type: application/json" \
-  -d '{"id": "entry-uuid-here", "status": "completed", "summary": "Found 12 matching grants", "tokens_in": 15000, "tokens_out": 3000}'
+  -d '{"id": "entry-uuid-here", "status": "completed", "summary": "Found 12 matching grants"}'
 ```
 
-**Via the SDK (in your own code):**
+**Via the SDK:**
 
 ```typescript
 import { Clawck } from 'clawck';
 
-const clawck = new Clawck({
-  default_client: 'acme-corp',
-  default_agent: 'my-agent',
-});
-
-const entry = clawck.start({
-  task: 'Analyze Q3 customer data',
-  project: 'analytics',
-  category: 'analysis',
-});
-
+const clawck = new Clawck({ default_client: 'acme-corp', default_agent: 'my-agent' });
+const entry = clawck.start({ task: 'Analyze Q3 data', project: 'analytics', category: 'analysis' });
 // ... agent does work ...
-
-clawck.stop({
-  id: entry.id,
-  status: 'completed',
-  tokens_in: 25000,
-  tokens_out: 8000,
-  cost_usd: 0.12,
-  summary: 'Identified 3 key churn drivers',
-});
+clawck.stop({ id: entry.id, status: 'completed', tokens_in: 25000, cost_usd: 0.12 });
 ```
 
 ### 2. Clawck calculates human-equivalent value
 
-Every entry has a **category** (research, content, code, data_entry, design, etc.) and Clawck applies configurable multipliers to estimate how long a human would take:
+Every entry has a **category** and Clawck applies configurable multipliers:
 
-| Category | Agent → Human Multiplier | Human Rate |
-|----------|--------------------------|------------|
+| Category | Multiplier | Human Rate |
+|----------|-----------|------------|
 | Research | 12x | $50/hr |
 | Content | 10x | $45/hr |
 | Code | 6x | $75/hr |
@@ -114,83 +123,140 @@ Every entry has a **category** (research, content, code, data_entry, design, etc
 | Design | 5x | $60/hr |
 | Analysis | 10x | $55/hr |
 | Testing | 8x | $65/hr |
+| Planning | 6x | $50/hr |
+| Communication | 8x | $40/hr |
+| Other | 8x | $50/hr |
 
-So if an agent spends 30 minutes on research, Clawck reports it as **6 hours of human-equivalent work** and **$300 in estimated value**.
+30 minutes of agent research = **6 hours human-equivalent** = **$300 estimated value**.
 
-### 3. View the dashboard
+> **Note:** These multipliers are configurable starting estimates. They represent
+> roughly how many hours of equivalent human work one hour of agent work produces
+> for each category. Adjust them based on your team's actual experience.
+> See `docs/benchmarks-sources.md` for industry timing data to help calibrate.
 
-Open `http://localhost:3456` to see:
+### 3. View results
 
-- 📊 **Stats cards** — Agent hours, human-equiv hours, cost, active tasks
-- 💚 **Savings banner** — Total estimated value delivered
-- 📋 **Time entries** — Every task with duration, category, and status
-- 📁 **By Project** — Hours breakdown per project with visual bars
-- 🤖 **By Agent** — Per-agent productivity and success rates
-- 🏷️ **By Category** — Where time is going across work types
+- **Dashboard** at `http://localhost:3456` - stats, entries, breakdowns by project/agent/category
+- **Terminal** - `clawck report` for quick summaries
+- **HTML** - `clawck report --format html` - interactive report with calendar, sortable table, Gantt chart, CSV export
+- **PDF** - `clawck report --format pdf` - printable timesheet with entry details
 
-## Multi-Agent Aggregation
+## Tracking Patterns
 
-Running 10 agents across multiple machines? Clawck merges them:
+Patterns are reusable templates for common task types. They set default values for category, project, client, agent, and tags.
 
-**Option A: Central collector pulls from remote instances**
+**Built-in patterns:** `default`, `code-review`, `research`, `content-creation`, `testing`
 
-```yaml
-# .clawck/config.json
-{
-  "remote_sources": [
-    { "name": "research-agent", "url": "http://cubi-01:3456/api/entries" },
-    { "name": "writer-agent", "url": "http://cubi-02:3456/api/entries" },
-    { "name": "coder-agent", "url": "http://cubi-03:3456/api/entries" }
-  ],
-  "sync_interval": 60
-}
+```bash
+# List available patterns
+clawck pattern list
+
+# Use a pattern when starting a task
+clawck start "Review auth module" --pattern code-review
+
+# Add a custom pattern
+clawck pattern add --name deploy --category code --project ops --tags deploy release
+
+# Set a default pattern
+clawck pattern use research
 ```
 
-**Option B: Agents push to a central instance**
+Patterns merge as defaults - any explicit flags you pass override the pattern's values.
+
+## Approval Workflow
+
+Entries can be approved for billing, invoicing, or quality control.
 
 ```bash
-# From any agent, POST entries to central Clawck
-curl -X POST http://central-clawck:3456/api/ingest \
-  -H "Content-Type: application/json" \
-  -d '[{"task": "...", "agent": "cubi-01", ...}]'
+# Approve an entry (supports 8-char ID prefix)
+clawck approve a1b2c3d4
+
+# View only approved entries
+clawck entries --approved
+
+# View unapproved entries
+clawck entries --unapproved
+
+# Filter in list view too
+clawck list --approved
 ```
 
-Entries merge cleanly by UUID — no conflicts, no duplicates.
+The API also supports approval: `POST /api/entries/:id/approve`.
+
+## Reports
+
+### Terminal
+
+```bash
+clawck report                        # Last 7 days
+clawck report --days 30 --detailed   # With individual entries
+clawck report --client acme-corp     # Filter by client
+```
+
+### HTML (interactive)
+
+```bash
+clawck report --format html -o report.html
+```
+
+The HTML report includes four tabs:
+- **Calendar** - Color-coded day grid showing entry count and hours
+- **Table** - Sortable table of all entries with full details
+- **Gantt** - Timeline visualization of tasks grouped by date
+- **CSV** - Copyable CSV data for spreadsheets
+
+### PDF
+
+```bash
+clawck report --format pdf -o report.pdf
+```
+
+Professional timesheet PDF with summary stats, breakdowns by project/agent/category, and an entry details table.
 
 ## CLI Commands
 
 ```bash
-clawck init                          # Create .clawck/ directory with config
-clawck serve                         # Start API + dashboard (default: port 3456)
-clawck serve --port 8080             # Custom port
-clawck mcp                           # Start MCP server on stdio
+# Setup
+clawck init                              # Create .clawck/ directory with config
+clawck serve [--port 8080]               # Start API + dashboard
+clawck mcp                               # Start MCP server on stdio
+clawck seed [--count 50]                 # Generate test data
 
 # Time tracking
-clawck start <task>                  # Start a timer
-clawck stop <id>                     # Stop a timer
-clawck log <task> --duration 30      # Log a completed task retroactively
+clawck start <task> [--pattern <name>]   # Start a timer
+clawck stop <id>                         # Stop a timer
+clawck log <task> --duration 30          # Log a completed task
 
 # Viewing entries
-clawck status                        # Show running tasks and stats
-clawck list                          # List entries in a table (last 7 days)
-clawck list --days 30 --project web  # Filter by days/project/client/agent
-clawck get <id>                      # Show a single entry
-clawck entries --status running      # Query with filters
-
-# Reports & export
-clawck report                        # Timesheet summary (last 7 days)
-clawck report --days 30 --detailed   # With individual entries
-clawck export --format csv --days 30 # Export as CSV (also: json)
+clawck status                            # Show running tasks and stats
+clawck list [--days 30] [--approved]     # List entries in a table
+clawck get <id>                          # Show a single entry
+clawck entries [--status running]        # Query with filters
+
+# Reports and export
+clawck report [--format terminal|pdf|html] [--output path]
+clawck export [--format csv|json] [--days 30]
 
-# Editing & deleting
-clawck edit <id> --task "New name"   # Edit fields (task, project, client, agent, etc.)
-clawck delete <id>                   # Delete an entry (supports 8-char prefix)
+# Patterns
+clawck pattern list                      # Show tracking patterns
+clawck pattern add --name <n> [opts]     # Add a custom pattern
+clawck pattern use <name>                # Set default pattern
 
-# Testing
-clawck seed --count 50               # Generate test data
+# Approval
+clawck approve <id>                      # Approve an entry
+
+# Editing and deleting
+clawck edit <id> --task "New name"       # Edit fields
+clawck delete <id>                       # Delete an entry (8-char prefix OK)
+
+# Hooks
+clawck hooks install <platform>          # Show hook config for a platform
+clawck hooks status                      # Check installed hooks
+clawck setup [claude|mcp|openclaw]       # Output integration snippets
 
 # Global options
-clawck --json <command>              # Output as JSON (for scripting)
+clawck --json <command>                  # JSON output for scripting
+clawck -d <path> <command>               # Custom data directory
 ```
 
 ## Configuration
@@ -202,8 +268,10 @@ Edit `.clawck/config.json`:
   "port": 3456,
   "default_client": "acme-corp",
   "default_project": "general",
-  "default_agent": "cubi-01",
+  "default_agent": "agent-01",
   "default_model": "claude-sonnet-4-20250514",
+  "default_source": "clawck",
+  "default_pattern": "default",
   "human_equivalents": {
     "research": { "multiplier": 12, "human_rate_usd": 50 },
     "content": { "multiplier": 10, "human_rate_usd": 45 },
@@ -215,11 +283,20 @@ Edit `.clawck/config.json`:
     "planning": { "multiplier": 6, "human_rate_usd": 50 },
     "communication": { "multiplier": 8, "human_rate_usd": 40 },
     "other": { "multiplier": 8, "human_rate_usd": 50 }
-  }
+  },
+  "patterns": [
+    { "name": "default", "description": "General task tracking", "category": "other" },
+    { "name": "code-review", "description": "Code review and refactoring", "category": "code", "tags": ["review"] },
+    { "name": "research", "description": "Research and analysis", "category": "research" },
+    { "name": "content-creation", "description": "Content writing", "category": "content" },
+    { "name": "testing", "description": "Writing and running tests", "category": "testing" }
+  ],
+  "remote_sources": [],
+  "webhooks": []
 }
 ```
 
-Clawck validates config on load. Invalid values (e.g., non-numeric port, malformed human_equivalents) will show a clear error message.
+Config is validated on load. Invalid values produce clear error messages.
 
 ## REST API
 
@@ -229,6 +306,7 @@ Clawck validates config on load. Invalid values (e.g., non-numeric port, malform
 | `POST` | `/api/stop` | Stop a running task |
 | `POST` | `/api/log` | Log a completed task retroactively |
 | `PATCH` | `/api/entries/:id` | Update an entry |
+| `POST` | `/api/entries/:id/approve` | Approve an entry |
 | `GET` | `/api/entries` | Query entries (with filters) |
 | `GET` | `/api/entries/:id` | Get a single entry |
 | `GET` | `/api/running` | Get currently running tasks |
@@ -240,107 +318,106 @@ Clawck validates config on load. Invalid values (e.g., non-numeric port, malform
 | `GET` | `/api/health` | Health check |
 | `GET` | `/api/stats` | Quick stats |
 
+## Multi-Agent Aggregation
+
+Running agents across multiple machines? Clawck merges them:
+
+**Pull mode** - central collector fetches from remote instances:
+
+```json
+{
+  "remote_sources": [
+    { "name": "research-agent", "url": "http://agent-01:3456/api/entries" },
+    { "name": "writer-agent", "url": "http://agent-02:3456/api/entries" }
+  ],
+  "sync_interval": 60
+}
+```
+
+**Push mode** - agents POST entries to a central instance:
+
+```bash
+curl -X POST http://central-clawck:3456/api/ingest \
+  -H "Content-Type: application/json" \
+  -d '[{"task": "...", "agent": "agent-01", ...}]'
+```
+
+Entries merge by UUID - no conflicts, no duplicates.
+
 ## Architecture
 
 ```
 clawck/
   src/
-    core/          → Schema, database (SQLite), entry manager
-    server/        → REST API (Express) + MCP server (stdio)
-    dashboard/     → Single-file HTML dashboard
-    cli/           → Command-line interface
-    adapters/      → Framework integrations (future)
+    core/          - Types, database (SQLite), entry manager, patterns
+    server/        - REST API (Express) + MCP server (stdio)
+    dashboard/     - Single-file HTML dashboard
+    reports/       - PDF and HTML report generators
+    cli/           - Command-line interface
+    hooks/         - Platform hook integrations
   .clawck/
-    config.json    → Your configuration
-    clawck.db      → SQLite database (auto-created)
+    config.json    - Your configuration
+    clawck.db      - SQLite database (auto-created)
 ```
 
 **Design principles:**
-- **Zero external dependencies** — SQLite is embedded, no Redis/Postgres/Docker needed
-- **One process** — API, dashboard, and MCP all run from the same `clawck serve`
-- **Append-first writes** — Entries are created and updated; deletion available via CLI
-- **UUID-based merging** — Multi-agent data combines without conflicts
-- **Configurable multipliers** — Human-equivalent estimates are transparent and adjustable
-
-## ClawckSpec v0.1
-
-Clawck implements an open schema for agent work entries. Any tool can emit ClawckSpec-compatible entries:
-
-```json
-{
-  "id": "550e8400-e29b-41d4-a716-446655440000",
-  "agent": "cubi-research-01",
-  "model": "claude-sonnet-4-20250514",
-  "client": "acme-corp",
-  "project": "grant-research",
-  "task": "Find NEA grants matching sustainability criteria",
-  "category": "research",
-  "start": "2026-03-07T10:00:00Z",
-  "end": "2026-03-07T10:47:00Z",
-  "status": "completed",
-  "tokens_in": 12400,
-  "tokens_out": 3200,
-  "cost_usd": 0.0852,
-  "tool_calls": 8,
-  "summary": "Found 12 matching grants totaling $2.4M in available funding",
-  "tags": ["grants", "sustainability"],
-  "source": "clawck-mcp",
-  "spec_version": "0.1.0"
-}
-```
+- **Zero infrastructure** - SQLite embedded, no Redis/Postgres/Docker needed
+- **One process** - API, dashboard, and MCP all run from `clawck serve`
+- **Append-first** - Entries are created and updated; deletion available via CLI
+- **UUID-based merging** - Multi-agent data combines without conflicts
+- **Configurable** - Human-equivalent multipliers are transparent and adjustable
 
 ## Integrations
 
-### Claude Code
-Add to `~/.claude/mcp_servers.json`:
+**Platform hooks (recommended)** - Auto-track via `clawck hooks install claude|cursor|cline|windsurf|gemini|codex`
+
+**Claude Code MCP** - Add to `~/.claude/mcp_servers.json` for explicit agent control:
 ```json
 { "clawck": { "command": "npx", "args": ["-y", "clawck", "mcp"] } }
 ```
 
-### OpenClaw
-Instrument at the harness level — auto-start/stop entries on task dispatch.
+**n8n** - POST to `/api/start` and `/api/stop` from HTTP Request nodes.
 
-### n8n
-POST to `/api/start` and `/api/stop` from HTTP Request nodes.
-
-### LangGraph / CrewAI / Any Python Framework
+**Python frameworks (LangGraph, CrewAI, etc.):**
 ```python
 import requests
-
-# Start
-r = requests.post("http://localhost:3456/api/start", json={
-    "task": "Analyze data", "project": "analytics", "agent": "my-agent"
-})
+r = requests.post("http://localhost:3456/api/start", json={"task": "Analyze data", "agent": "my-agent"})
 entry_id = r.json()["id"]
-
-# Stop
-requests.post("http://localhost:3456/api/stop", json={
-    "id": entry_id, "status": "completed"
-})
+requests.post("http://localhost:3456/api/stop", json={"id": entry_id, "status": "completed"})
 ```
 
+## Help / Troubleshooting
+
+- `clawck --help` for CLI usage
+- `clawck setup` for agent integration snippets
+- `clawck hooks status` to check hook installations
+- Data directory defaults to `.clawck/` in your working directory. Override with `-d <path>` or `CLAWCK_DIR` env var.
+
 ## Roadmap
 
+- [x] PDF report export
+- [x] Webhooks (task completion, failure, idle alerts)
+- [x] Claude Code hooks adapter
+- [x] Tracking patterns
+- [x] Approval workflow
+- [x] HTML interactive reports
 - [ ] Python SDK (`pip install clawck`)
 - [ ] Auto-instrumentation (monkey-patch LLM client libraries)
-- [ ] PDF report export
 - [ ] Email digest (weekly summary to clients)
-- [ ] Webhooks (notify on task completion)
-- [ ] Claude Code hooks adapter
 - [ ] OpenTelemetry exporter
-- [ ] "Powered by Clawck" embeddable widget
+- [ ] Embeddable widget
 
 ## Contributing
 
 Contributions welcome! Especially:
-- **Adapters** — New framework integrations
-- **Dashboard** — UI improvements and features
-- **Multipliers** — Better human-equivalent estimates backed by data
+- **Adapters** - New framework integrations
+- **Dashboard** - UI improvements and features
+- **Multipliers** - Better human-equivalent estimates backed by data
 
 ## License
 
-MIT — use it, fork it, build on it.
+MIT
 
 ---
 
-Built by [CubiCrew](https://cubicrew.com) · Created by [Vince Quarles](https://github.com/vincequarles)
+Built by [CubiCrew](https://cubicrew.com) - Created by [Vince Quarles](https://github.com/vincequarles)