clawck 0.1.3 → 0.4.1

package/docs/skills/clawck-setup.md

@@ -0,0 +1,131 @@
+# Clawck Setup Guide
+
+Integrate Clawck generation time tracking into your AI agent platform. Clawck measures how long an AI agent's computation, reasoning, and response generation take per turn — it is NOT human time tracking.
+
+## Claude Code
+
+### 1. Add MCP Server
+
+Add to your `mcp_servers.json` (or `~/.claude/mcp_servers.json` for global):
+
+```json
+{
+  "clawck": {
+    "command": "npx",
+    "args": ["-y", "clawck", "mcp"],
+    "env": {}
+  }
+}
+```
+
+### 2. Add CLAUDE.md Instructions
+
+Add the following to your project's `CLAUDE.md` (or `~/.claude/CLAUDE.md` for global):
+
+```markdown
+## Generation Time Tracking (Clawck)
+
+You have Clawck tools via MCP that measure YOUR generation time — how long your computation, reasoning, tool calls, and response generation take. This is NOT human time tracking. You are timing your own AI processing.
+
+You MUST time every turn automatically:
+
+1. **Start of every turn**: Call `clawck_start_task` IMMEDIATELY when you receive a message, BEFORE doing any other work.
+2. **End of every turn**: Call `clawck_stop_task` as the LAST action before sending your reply.
+3. **Every turn**: Each user message = one generation cycle. A 5-message conversation = 5 time entries.
+4. **Errors**: Always stop the timer even on failure — use `status: "failed"`.
+5. **Forgot to start?** Use `clawck_log_task` with an estimated duration.
+```
+
+Run `clawck setup claude` to get the full snippet.
+
+## OpenClaw
+
+OpenClaw agents use behavioral files for persistent integration:
+
+### AGENT.md
+
+Add clawck rules to your `AGENT.md`. Run `clawck setup openclaw` for the snippet.
+
+### HEARTBEAT.md
+
+Add per-turn hooks to your `HEARTBEAT.md`. Run `clawck setup openclaw` for the snippet.
+
+### SOUL.md
+
+Add accountability identity to your `SOUL.md`:
+
+```markdown
+I track my own work time using Clawck. Every turn I clock in and out automatically.
+This is part of my accountability to the humans I work for — they deserve to know
+how their AI resources are being spent.
+```
+
+## Cursor / Cline / Windsurf
+
+These editors support MCP servers. Add the clawck MCP config to:
+
+- **Cursor**: `.cursor/mcp.json` in your project root
+- **Cline**: VS Code settings → Cline → MCP Servers
+- **Windsurf**: `.windsurf/mcp.json` in your project root
+
+The MCP config block is the same for all:
+
+```json
+{
+  "clawck": {
+    "command": "npx",
+    "args": ["-y", "clawck", "mcp"],
+    "env": {}
+  }
+}
+```
+
+## API Agents (Python / n8n / LangGraph)
+
+For agents that don't support MCP natively, use the Clawck REST API:
+
+### Start the server
+
+```bash
+clawck serve --port 3456
+```
+
+### Python wrapper
+
+```python
+import requests
+import time
+
+CLAWCK_URL = "http://localhost:3456/api"
+
+def clawck_start(task, project="", client="", category="code"):
+    r = requests.post(f"{CLAWCK_URL}/start", json={
+        "task": task, "project": project, "client": client, "category": category
+    })
+    return r.json()["id"]
+
+def clawck_stop(entry_id, status="completed", summary=""):
+    requests.post(f"{CLAWCK_URL}/stop", json={
+        "id": entry_id, "status": status, "summary": summary
+    })
+```
+
+### n8n / LangGraph
+
+Use HTTP Request nodes to call the REST API at `http://localhost:3456/api/start` and `/api/stop` at the beginning and end of each agent turn.
+
+## Quick Start CLI
+
+```bash
+# See all setup options
+clawck setup
+
+# Get CLAUDE.md snippet
+clawck setup claude
+
+# Get MCP config JSON
+clawck setup mcp
+
+# Get OpenClaw snippets
+clawck setup openclaw
+```

package/docs/skills/clawck-usage.md

@@ -0,0 +1,148 @@
+# Clawck Usage Protocol
+
+Detailed guide for AI agents using Clawck to measure their own generation time.
+
+## What Clawck Measures
+
+Clawck measures **your active generation/computation time** — the wall-clock duration from when you start processing a user message to when you finish generating your response. This is NOT human time tracking. Typical durations are seconds to minutes. Think of it as a stopwatch on your own CPU.
+
+The resulting data enables:
+- **Billing**: How much compute time each task consumed
+- **Cost analysis**: Tokens + cost per task/project/client
+- **Human-equivalent estimates**: How long this work would take a human (calculated from the `category`)
+- **ROI reporting**: Agent cost vs. human-equivalent cost
+
+## Generation Lifecycle
+
+Every agent turn follows this lifecycle:
+
+```
+User message received
+        │
+        ▼
+┌─ clawck_start_task ──────────┐
+│  (start generation timer)    │
+└──────────────────────────────┘
+        │
+        ▼
+┌─ Process request ────────────┐
+│  • Reason / plan             │
+│  • Call tools                │
+│  • Write code                │
+│  • Generate output           │
+│  (all ONE generation cycle)  │
+└──────────────────────────────┘
+        │
+        ▼
+┌─ clawck_stop_task ───────────┐
+│  (stop generation timer)     │
+└──────────────────────────────┘
+        │
+        ▼
+Send response to user
+```
+
+## Multi-Message Tracking
+
+Each turn in a conversation is timed independently:
+
+| Turn | User Says | Agent Times |
+|------|-----------|-------------|
+| 1 | "Fix the login bug" | start → generate → stop (entry 1) |
+| 2 | "Add tests for it" | start → generate → stop (entry 2) |
+| 3 | "Deploy to staging" | start → generate → stop (entry 3) |
+
+A 5-message session produces 5 time entries. This gives granular visibility into what each generation cycle cost.
+
+## Field Guidelines
+
+### task
+Describe what YOU (the agent) are doing, not what the user asked:
+- Good: "Refactor auth module to use JWT tokens"
+- Bad: "User asked me to fix authentication"
+
+### project
+The project being worked on. Infer from context, directory name, or ask once and reuse:
+- "website-rebuild", "grant-research", "api-v2"
+
+### client
+The client or organization. Infer from context or prior entries:
+- "acme-corp", "internal", "my-company"
+
+### category
+Classify the type of work. Available categories:
+- `code` — Writing, reviewing, or refactoring code
+- `research` — Searching, reading, analyzing information
+- `content` — Writing docs, emails, copy, blog posts
+- `analysis` — Data analysis, reporting, insights
+- `data_entry` — Data migration, formatting, entry
+- `communication` — Emails, messages, outreach
+- `testing` — Writing or running tests
+- `design` — UI/UX design, mockups, wireframes
+
+### summary (on stop)
+Brief description of what was accomplished:
+- "Fixed JWT token refresh logic and added error handling"
+- "Searched 3 grant databases, found 2 relevant opportunities"
+
+### tokens / cost (on stop)
+Report if your platform provides this data:
+- `tokens_in`: Input tokens consumed this turn
+- `tokens_out`: Output tokens generated this turn
+- `cost_usd`: Estimated cost in USD
+
+## Edge Cases
+
+### Errors / Failures
+Always stop the timer even when things go wrong:
+```
+clawck_stop_task({ id: "...", status: "failed", summary: "Build failed due to missing dependency" })
+```
+
+### Forgot to Start the Timer
+Use retroactive logging:
+```
+clawck_log_task({ task: "Debug API timeout", duration_minutes: 3, project: "api-v2", category: "code" })
+```
+
+### Long Generations
+If a turn takes unusually long (e.g., large codebase analysis), that's fine — one turn = one entry regardless of duration.
+
+### Idle Time Between Turns
+Do NOT track time between turns. Only measure your active generation time within a turn. The time between your response and the user's next message is NOT your computation — don't record it.
+
+### Sub-Tasks Within a Turn
+All work within one turn is a single entry. If you call 10 tools during one turn, that's still ONE generation cycle. Don't create separate entries for each tool call.
+
+## Examples
+
+### Basic Turn
+```
+1. Receive: "Add input validation to the signup form"
+2. clawck_start_task({ task: "Add input validation to signup form", project: "website", client: "acme-corp", category: "code" })
+   → Timer starts. Your generation begins.
+3. Read files, write code, run tests
+4. clawck_stop_task({ id: "abc-123", status: "completed", summary: "Added email format and password strength validation", tokens_out: 1500 })
+   → Timer stops. Your generation is complete.
+5. Send response
+```
+
+### Failed Task
+```
+1. Receive: "Deploy to production"
+2. clawck_start_task({ task: "Deploy to production", project: "api-v2", client: "acme-corp", category: "code" })
+3. Attempt deployment, encounter error
+4. clawck_stop_task({ id: "def-456", status: "failed", summary: "Deploy failed: missing ENV vars on production server" })
+5. Send error response to user
+```
+
+### Retroactive Log
+```
+1. Receive: "What was that error about?"
+2. Realize forgot to start timer on previous turn
+3. clawck_log_task({ task: "Diagnosed API timeout in payment service", duration_minutes: 2, project: "api-v2", category: "code" })
+4. clawck_start_task({ task: "Explain previous API timeout diagnosis", project: "api-v2", category: "communication" })
+5. Explain the error
+6. clawck_stop_task({ id: "ghi-789", status: "completed", summary: "Explained root cause of API timeout to user" })
+7. Send response
+```

package/docs/snippets/claude-md.txt

@@ -0,0 +1,33 @@
+## Generation Time Tracking (Clawck)
+
+If you have Clawck hooks configured (UserPromptSubmit/Stop), your generation time is tracked automatically — no action needed on your part.
+
+You also have Clawck MCP tools available for explicit control. Use these when you want to:
+- Set a more descriptive task name than the auto-captured prompt
+- Add specific project/client/category metadata
+- Log a retroactive entry with `clawck_log_task`
+
+### Available MCP Tools
+- `clawck_start_task` — Start a timer (overrides the hook's auto-start for this turn)
+- `clawck_stop_task` — Stop a timer with status and summary
+- `clawck_log_task` — Log a completed task retroactively
+- `clawck_status` — Check running tasks
+- `clawck_timesheet` — Get timesheet summary
+
+### When to use MCP tools explicitly
+- You do NOT need to call start/stop every turn if hooks are active
+- Use them when you have better context about what the task actually is
+- Always include project/client/category when you have that context
+
+### Field Guidelines
+- `task`: Describe what YOU are doing (e.g., "Refactor auth module"), not what the user asked.
+- `project` / `client`: Include if known from context or previous entries.
+- `category`: Classify the work type (code, research, content, analysis, etc.).
+- `summary`: Brief description of what was accomplished when stopping.
+- `tokens_in` / `tokens_out` / `cost_usd`: Report if available.
+
+### Important
+- Do NOT ask the user for permission to track. Just do it.
+- All tool calls within one turn are ONE generation cycle, not separate entries.
+- Do NOT skip tracking on "simple" turns — time everything.
+- Do NOT track time between turns — only measure your active generation.

package/docs/snippets/hooks-claude.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "clawck hook start"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "clawck hook stop"
+          }
+        ]
+      }
+    ]
+  }
+}

package/docs/snippets/hooks-cline.txt

@@ -0,0 +1,10 @@
+# Cline Hook Scripts
+# Place these as executable scripts in .clinerules/hooks/
+
+# --- .clinerules/hooks/TaskStart ---
+#!/bin/bash
+clawck hook start
+
+# --- .clinerules/hooks/PostToolUse ---
+#!/bin/bash
+clawck hook stop

package/docs/snippets/hooks-codex.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "turn-start": [
+      {
+        "type": "command",
+        "command": "clawck hook start"
+      }
+    ],
+    "agent-turn-complete": [
+      {
+        "type": "command",
+        "command": "clawck hook stop"
+      }
+    ]
+  }
+}

package/docs/snippets/hooks-cursor.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "pre_user_prompt": [
+      {
+        "type": "command",
+        "command": "clawck hook start"
+      }
+    ],
+    "stop": [
+      {
+        "type": "command",
+        "command": "clawck hook stop"
+      }
+    ]
+  }
+}

package/docs/snippets/hooks-gemini.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "BeforeAgent": [
+      {
+        "type": "command",
+        "command": "clawck hook start"
+      }
+    ],
+    "AfterAgent": [
+      {
+        "type": "command",
+        "command": "clawck hook stop"
+      }
+    ]
+  }
+}

package/docs/snippets/hooks-windsurf.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "pre_user_prompt": [
+      {
+        "type": "command",
+        "command": "clawck hook start"
+      }
+    ],
+    "post_agent": [
+      {
+        "type": "command",
+        "command": "clawck hook stop"
+      }
+    ]
+  }
+}

package/docs/snippets/mcp-config.json

@@ -0,0 +1,7 @@
+{
+  "clawck": {
+    "command": "npx",
+    "args": ["-y", "clawck", "mcp"],
+    "env": {}
+  }
+}

package/docs/snippets/openclaw-agent-md.txt

@@ -0,0 +1,18 @@
+## Generation Time Tracking (Clawck)
+
+You are responsible for measuring your own generation time using Clawck MCP tools. This is NOT human time tracking — you are timing how long YOUR computation, reasoning, and response generation take per turn. Think of it as a stopwatch on your own processing.
+
+### Rules
+- Start the timer (`clawck_start_task`) at the START of every generation turn.
+- Stop the timer (`clawck_stop_task`) at the END of every generation turn.
+- One turn = one time entry. Multiple tool calls within a turn are one generation cycle.
+- Always stop the timer on failure with `status: "failed"`.
+- If you forgot to start the timer, use `clawck_log_task` with an estimated duration.
+- Never skip timing. Never ask permission. Never track idle time between turns.
+
+### Fields
+- `task`: What you are doing this turn.
+- `project` / `client`: From context or prior entries.
+- `category`: code | research | content | analysis | data_entry | communication | testing | design
+- `summary`: What was accomplished (on stop).
+- Token counts and cost if available.

package/docs/snippets/openclaw-heartbeat-md.txt

@@ -0,0 +1,17 @@
+## Per-Turn Generation Timing (Clawck)
+
+### On Message Received
+1. Call `clawck_start_task` with task description, project, client, and category.
+2. Store the returned entry ID for stopping the timer later.
+3. This marks the START of your generation — the moment you begin processing.
+
+### On Response Complete
+1. Call `clawck_stop_task` with the entry ID, status, summary, and token/cost data.
+2. This marks the END of your generation — the moment you finish producing output.
+3. This MUST happen even if the turn resulted in an error.
+
+### On Error
+1. Call `clawck_stop_task` with `status: "failed"` and a summary of what went wrong.
+
+### Missed Timer Start
+1. Call `clawck_log_task` with estimated `duration_minutes` and task details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawck",
-  "version": "0.1.3",
+  "version": "0.4.1",
   "description": "⏱️🦀 Time tracking for AI agents. Toggl for the agentic era.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -38,8 +38,8 @@
   "homepage": "https://clawck.dev",
   "dependencies": {
     "better-sqlite3": "^12.6.2",
-    "chalk": "^5.3.0",
     "commander": "^12.0.0",
+    "pdfkit": "^0.15.0",
     "cors": "^2.8.5",
     "express": "^4.21.0",
     "uuid": "^10.0.0"
@@ -49,6 +49,7 @@
     "@types/cors": "^2.8.0",
     "@types/express": "^4.17.0",
     "@types/node": "^22.0.0",
+    "@types/pdfkit": "^0.13.0",
     "@types/supertest": "^7.2.0",
     "@types/uuid": "^10.0.0",
     "supertest": "^7.2.2",
@@ -61,6 +62,7 @@
   },
   "files": [
     "dist/",
+    "docs/",
     "README.md",
     "LICENSE"
   ]