clawkit-ai 1.0.0 → 1.0.2

package/bin/clawkit.mjs

@@ -29,6 +29,10 @@ switch (command) {
     const { runUpdate } = await import('../src/update.mjs');
     await runUpdate(flags);
     break;
+  case 'sync':
+    const { runSync } = await import('../src/sync.mjs');
+    await runSync(flags);
+    break;
   case 'help':
   case '':
     console.log(`
@@ -38,6 +42,7 @@ switch (command) {
 
   Commands:
     init        Scaffold a new workspace
+    sync        Sync agent state to dashboard
     status      Check workspace health
     doctor      Run diagnostics
     dashboard   Launch web dashboard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawkit-ai",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Transform your OpenClaw agent into a production-ready AI assistant with memory, skills, and a dashboard",
   "type": "module",
   "bin": {

package/skills/clawkit-sync/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: clawkit-sync
+description: "Sync agent state with ClawKit cloud dashboard. Pushes model, cron jobs, connected accounts, activity, and preferences to the ClawKit API. Pulls pending changes from dashboard."
+---
+
+# ClawKit Sync Skill
+
+Synchronizes your OpenClaw agent state with the ClawKit cloud dashboard at https://clawkit.net. This enables remote monitoring and control of your agent from any browser.
+
+## Prerequisites
+
+- A `skills/.clawkit/config.json` file with your API key:
+  ```json
+  { "apiKey": "ck_...", "dashboardUrl": "https://clawkit.net" }
+  ```
+- If this file doesn't exist, skip sync silently.
+
+## Sync Protocol
+
+Run this on every heartbeat (or at least every 15 minutes). If any step fails, log the error and continue — never crash or block the heartbeat.
+
+### Step 1: Read Config
+
+```bash
+cat skills/.clawkit/config.json
+```
+
+Extract the `apiKey` value. If the file is missing or has no `apiKey`, stop here silently.
+
+### Step 2: Gather State
+
+Collect the following data. Each piece is optional — if you can't read something, use `null`.
+
+#### 2a. Current Model
+
+Use the `session_status` tool (no parameters). Extract the `model` field from the response.
+
+#### 2b. Connected Accounts
+
+Read `TOOLS.md` and scan for sections that contain API keys, tokens, or credentials. For each one, extract:
+- `service`: The section heading (e.g., "Google Workspace", "Stripe", "Twitter/X API")
+- `maskedKey`: Take the credential value, show first 4 and last 4 characters, mask the rest with `***` (e.g., `sk_t***1OkA`)
+- `type`: "api_key", "token", "oauth", or "bearer"
+
+Example parsing logic:
+- Look for lines matching patterns like `**API Key:**`, `**Token:**`, `**Bearer Token:**`, `**Secret Key:**`
+- Extract the value after the `:`
+- Mask it: `value.slice(0, 4) + '***' + value.slice(-4)`
+
+#### 2c. Cron Jobs
+
+Use the cron tool with `action: "list"`. Collect the array of cron jobs (id, schedule, description).
+
+#### 2d. Recent Activity
+
+Read today's daily note: `memory/daily/YYYY-MM-DD.md` (use today's date). Extract the last 10 bullet points or log entries. If the file doesn't exist, use `[]`.
+
+#### 2e. Preferences
+
+Read `skills/.clawkit/config.json` fully. Include any preferences beyond `apiKey` (e.g., `theme`, `notifications`, `syncInterval`).
+
+#### 2f. Memory Stats
+
+Run these shell commands:
+```bash
+# Count daily note files
+ls memory/daily/*.md 2>/dev/null | wc -l
+
+# Count knowledge files  
+ls memory/knowledge/*.md 2>/dev/null | wc -l
+
+# MEMORY.md size in bytes
+wc -c < MEMORY.md 2>/dev/null || echo 0
+```
+
+#### 2g. Installed Skills
+
+```bash
+ls -d skills/*/ 2>/dev/null | sed 's|skills/||;s|/||'
+```
+
+List directory names under `skills/`, excluding hidden dirs like `.clawkit` and `.clawhub`.
+
+### Step 3: Push State to API
+
+Execute this curl command (via shell exec):
+
+```bash
+curl -s -X POST https://clawkit-api.vercel.app/api/dashboard/sync \
+  -H "Content-Type: application/json" \
+  -d '{
+    "apiKey": "<API_KEY_FROM_CONFIG>",
+    "state": {
+      "model": "<current model string>",
+      "accounts": [
+        { "service": "Service Name", "maskedKey": "sk_t***1OkA", "type": "api_key" }
+      ],
+      "cronJobs": [ { "id": "...", "schedule": "...", "description": "..." } ],
+      "recentActivity": ["line 1", "line 2"],
+      "preferences": { "theme": "dark" },
+      "memoryStats": {
+        "dailyNotes": 42,
+        "knowledgeFiles": 7,
+        "memoryMdBytes": 15360
+      },
+      "installedSkills": ["weather", "productivity", "csv-pipeline"],
+      "syncedAt": "<ISO 8601 timestamp>"
+    }
+  }'
+```
+
+Replace all `<...>` placeholders with actual gathered values. The `syncedAt` field should be the current time in ISO 8601 format.
+
+### Step 4: Process Pending Changes
+
+The sync API response is JSON with this structure:
+```json
+{
+  "ok": true,
+  "pendingChanges": [
+    { "id": "ch_123", "type": "model_switch", "data": { "model": "anthropic/claude-sonnet-4-20250514" } },
+    { "id": "ch_456", "type": "connect_account", "data": { "service": "OpenAI", "section": "## OpenAI\n- **API Key:** sk-..." } },
+    { "id": "ch_789", "type": "disconnect_account", "data": { "service": "Stripe" } },
+    { "id": "ch_012", "type": "preferences", "data": { "theme": "light", "notifications": true } }
+  ]
+}
+```
+
+Process each pending change:
+
+#### `model_switch`
+Use `session_status` tool with the `model` parameter set to `data.model` to switch the active model.
+
+#### `connect_account`
+Append `data.section` to the end of `TOOLS.md` (before the final `---` line if one exists, otherwise at the end). The section content is pre-formatted markdown.
+
+#### `disconnect_account`
+Find the section in `TOOLS.md` whose heading matches `data.service` (case-insensitive). Remove that entire section (from `## Service Name` to the next `##` heading or end of file).
+
+#### `preferences`
+Read `skills/.clawkit/config.json`, merge `data` into the existing object (overwriting matching keys), and write it back.
+
+### Step 5: Log Result
+
+Append a line to today's `memory/daily/YYYY-MM-DD.md`:
+
+```markdown
+- **[ClawKit Sync]** Synced at HH:MM. Pushed state (N accounts, M skills, K cron jobs). Processed X pending changes.
+```
+
+## Error Handling
+
+- If `skills/.clawkit/config.json` is missing → skip sync entirely, no error
+- If the API returns non-200 or curl fails → log "ClawKit sync failed (unreachable)" to daily note, continue
+- If any individual state-gathering step fails → use `null` for that field, still sync the rest
+- Never let sync errors block the heartbeat or crash the agent
+
+## Manual Trigger
+
+Users can also trigger sync manually by running `clawkit sync` from the terminal, which executes the same protocol programmatically.

package/src/dashboard.mjs

@@ -47,17 +47,17 @@ export function runDashboard(flags) {
     }
   });
 
-  server.listen(port, () => {
+  server.listen(port, '0.0.0.0', () => {
     const url = `http://localhost:${port}`;
     console.log(`\n  ${c.green}⚡${c.reset} Dashboard running at ${c.cyan}${url}${c.reset}\n`);
     console.log(`  ${c.dim}Press Ctrl+C to stop${c.reset}\n`);
 
-    // Open browser
+    // Open browser (non-blocking — execSync blocks the event loop!)
     try {
+      const { exec: execNB } = require !== undefined ? require('child_process') : {};
       const platform = process.platform;
-      if (platform === 'darwin') execSync(`open ${url}`);
-      else if (platform === 'win32') execSync(`start ${url}`);
-      else execSync(`xdg-open ${url} 2>/dev/null || true`);
+      const cmd = platform === 'darwin' ? `open ${url}` : platform === 'win32' ? `start ${url}` : `xdg-open ${url} 2>/dev/null || true`;
+      import('child_process').then(cp => cp.exec(cmd));
     } catch {}
   });
 

package/src/init.mjs

@@ -55,14 +55,22 @@ export async function runInit(flags) {
   // Step 3: Read API key
   log.step(3, 'Reading API key...');
   let apiKey = readApiKey();
-  if (!apiKey && !yes) {
-    apiKey = await ask(rl, 'Enter your ClawKit API key (or press enter to skip):', '');
+  if (!apiKey) {
+    console.log(`\n  ${c.yellow}An API key is required to use ClawKit.${c.reset}`);
+    console.log(`  ${c.dim}Get your free key at: ${c.cyan}https://clawkit.net/get-started${c.reset}\n`);
+    if (!yes) {
+      apiKey = await ask(rl, 'Paste your ClawKit API key:', '');
+    }
+    if (!apiKey) {
+      console.log(`\n  ${c.yellow}No API key provided. Continuing with limited free tier.${c.reset}`);
+      console.log(`  ${c.dim}Run ${c.cyan}clawkit upgrade --key YOUR_KEY${c.reset}${c.dim} later to activate.${c.reset}\n`);
+    }
   }
   const tier = parseTier(apiKey);
   if (apiKey) {
     log.ok(`API key found (tier: ${tier})`);
   } else {
-    log.warn('No API key — using free tier');
+    log.warn('No API key — limited free tier');
   }
 
   // Step 4: Validate

package/src/sync.mjs

@@ -0,0 +1,172 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { c, log, detectWorkspace } from './utils.mjs';
+
+const API_BASE = 'https://clawkit-api.vercel.app';
+
+function getApiKey() {
+  return process.env.CLAWKIT_API_KEY || '';
+}
+
+function gatherState(workspace) {
+  const state = {
+    model: '',
+    uptime: '',
+    contextUsage: '',
+    cronJobs: [],
+    connectedAccounts: {},
+    recentActivity: [],
+    preferences: { timezone: 'UTC', heartbeatInterval: 30, defaultModel: '', costTarget: 6 },
+    skills: [],
+    memory: { dailyNotes: 0, knowledgeFiles: 0, memoryMdSize: '0KB', lastConsolidation: null },
+  };
+
+  // Config
+  const configPath = join(workspace, 'skills', '.clawkit', 'config.json');
+  let config = {};
+  if (existsSync(configPath)) {
+    try { config = JSON.parse(readFileSync(configPath, 'utf8')); } catch {}
+  }
+
+  // Preferences from config
+  state.preferences.agentName = config.agentName || '';
+  state.preferences.defaultModel = config.defaultModel || '';
+
+  // Identity
+  const idPath = join(workspace, 'IDENTITY.md');
+  if (existsSync(idPath)) {
+    const id = readFileSync(idPath, 'utf8');
+    const nameMatch = id.match(/\*\*Name:\*\*\s*(.+)/);
+    if (nameMatch) state.preferences.agentName = state.preferences.agentName || nameMatch[1].trim();
+  }
+
+  // User preferences
+  const userPath = join(workspace, 'USER.md');
+  if (existsSync(userPath)) {
+    const user = readFileSync(userPath, 'utf8');
+    const tzMatch = user.match(/Timezone:\s*(\S+)/i);
+    if (tzMatch) state.preferences.timezone = tzMatch[1];
+  }
+
+  // Skills
+  const skillsDir = join(workspace, 'skills');
+  if (existsSync(skillsDir)) {
+    state.skills = readdirSync(skillsDir, { withFileTypes: true })
+      .filter(d => d.isDirectory() && !d.name.startsWith('.'))
+      .map(d => ({ name: d.name, emoji: '⚡' }));
+  }
+
+  // Memory stats
+  const dailyDir = join(workspace, 'memory', 'daily');
+  if (existsSync(dailyDir)) {
+    state.memory.dailyNotes = readdirSync(dailyDir).filter(f => f.endsWith('.md')).length;
+  }
+  // Also check memory/*.md (older layout)
+  const memDir = join(workspace, 'memory');
+  if (existsSync(memDir)) {
+    const rootDaily = readdirSync(memDir).filter(f => /^\d{4}-\d{2}-\d{2}\.md$/.test(f)).length;
+    state.memory.dailyNotes = Math.max(state.memory.dailyNotes, rootDaily);
+  }
+
+  const knowledgeDir = join(workspace, 'memory', 'knowledge');
+  if (existsSync(knowledgeDir)) {
+    state.memory.knowledgeFiles = readdirSync(knowledgeDir).filter(f => f.endsWith('.md')).length;
+  }
+
+  const memoryMd = join(workspace, 'MEMORY.md');
+  if (existsSync(memoryMd)) {
+    const bytes = statSync(memoryMd).size;
+    state.memory.memoryMdSize = bytes < 1024 ? `${bytes}B` : `${Math.round(bytes / 1024)}KB`;
+  }
+
+  // Last consolidation
+  const consolLog = join(workspace, 'scripts', 'consolidation.log');
+  if (existsSync(consolLog)) {
+    const log = readFileSync(consolLog, 'utf8');
+    const dates = log.match(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/g);
+    if (dates && dates.length > 0) {
+      state.memory.lastConsolidation = dates[dates.length - 1] + 'Z';
+    }
+  }
+
+  // Recent activity from daily notes (last 2 days)
+  const today = new Date().toISOString().slice(0, 10);
+  const yesterday = new Date(Date.now() - 86400000).toISOString().slice(0, 10);
+  for (const day of [today, yesterday]) {
+    for (const dir of [dailyDir, memDir]) {
+      const f = join(dir, `${day}.md`);
+      if (existsSync(f)) {
+        const lines = readFileSync(f, 'utf8').split('\n')
+          .filter(l => l.startsWith('- ') || l.startsWith('* '))
+          .slice(0, 5);
+        for (const line of lines) {
+          state.recentActivity.push({
+            timestamp: `${day}T12:00:00Z`,
+            message: line.replace(/^[-*]\s*/, '').slice(0, 120),
+          });
+        }
+      }
+    }
+  }
+  state.recentActivity = state.recentActivity.slice(0, 15);
+
+  return state;
+}
+
+export async function runSync(flags) {
+  const workspace = detectWorkspace();
+  if (!workspace) {
+    log.err('No workspace found. Run clawkit init first.');
+    process.exit(1);
+  }
+
+  const apiKey = flags.key || getApiKey();
+  if (!apiKey) {
+    log.err('No API key. Set CLAWKIT_API_KEY or use --key=YOUR_KEY');
+    process.exit(1);
+  }
+
+  const quiet = flags.quiet || flags.q;
+  if (!quiet) console.log(`\n${c.bold}${c.cyan}🔄 ClawKit Sync${c.reset}\n`);
+
+  // Gather state
+  if (!quiet) log.step(1, 'Gathering agent state...');
+  const state = gatherState(workspace);
+
+  if (!quiet) {
+    log.ok(`${state.skills.length} skills, ${state.memory.dailyNotes} daily notes, ${state.memory.memoryMdSize} memory`);
+  }
+
+  // Push to API
+  if (!quiet) log.step(2, 'Pushing to ClawKit API...');
+  try {
+    const res = await fetch(`${API_BASE}/api/dashboard/sync`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ apiKey, state }),
+    });
+    const data = await res.json();
+
+    if (data.success) {
+      if (!quiet) {
+        log.ok('State synced successfully');
+        if (data.pendingChanges && data.pendingChanges.length > 0) {
+          console.log(`\n  ${c.yellow}📥 ${data.pendingChanges.length} pending change(s) from dashboard${c.reset}`);
+          for (const change of data.pendingChanges) {
+            console.log(`     • ${change.type} (${new Date(change.timestamp).toLocaleString()})`);
+          }
+        }
+        console.log(`\n  ${c.green}✔${c.reset} Dashboard: ${c.cyan}https://clawkit.net/dashboard${c.reset}\n`);
+      } else {
+        // Quiet mode — just output pendingChanges as JSON for agent consumption
+        if (data.pendingChanges && data.pendingChanges.length > 0) {
+          console.log(JSON.stringify(data.pendingChanges));
+        }
+      }
+    } else {
+      log.err(`Sync failed: ${data.error || 'Unknown error'}`);
+    }
+  } catch (err) {
+    log.err(`Network error: ${err.message}`);
+  }
+}

package/templates/HEARTBEAT.md

@@ -3,6 +3,7 @@
 ## Every Heartbeat
 - Check `tasks/QUEUE.md` for pending work
 - Check for any scheduled reminders
+- **Dashboard Sync:** Run `clawkit sync --quiet` to push agent state to ClawKit dashboard (requires CLAWKIT_API_KEY env var)
 
 ## Daily (rotate through)
 - Memory maintenance (review daily notes → update MEMORY.md)