{"id":"1cb28fe6-be8a-45eb-a0fa-7192f05ee01e","entityType":"agent","slug":"clawhub-brian-mwirigi-costhq","name":"CostHQ","canonicalUrl":"https://www.xpersona.co/agent/clawhub-brian-mwirigi-costhq","canonicalPath":"/agent/clawhub-brian-mwirigi-costhq","generatedAt":"2026-10-10T01:43:26.717Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T05:34:47.557Z","emptyReason":null},"description":"Track agent session costs, file changes, and git commits with CostHQ. Enforces budget limits, tracks local models, and provides Enterprise SOC2 audit trails... Skill: CostHQ Owner: brian-mwirigi Summary: Track agent session costs, file changes, and git commits with CostHQ. Enforces budget limits, tracks local models, and provides Enterprise SOC2 audit trails... Tags: latest:4.0.0 Version history: v4.0.0 | 2026-06-09T18:27:46.036Z | user - Added Semantic Caching Proxy to intercept and cache API calls, reducing repeated costs. - Introduced granular session termination via the","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 4.3K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17935t6g2g6grny1r9yk1eze986zjyt:costhq","sourceUrl":"https://clawhub.ai/brian-mwirigi/costhq","homepage":"https://clawhub.ai/brian-mwirigi/skills/costhq","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/brian-mwirigi/costhq","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/brian-mwirigi/skills/costhq","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":73,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Track agent session costs, file changes, and git commits with CostHQ. Enforces budget limits, tracks local models, and provides Enterprise SOC2 audit trails... "},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:34:47.557Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:34:47.557Z","emptyReason":null},"stars":null,"forks":null,"downloads":4334,"packageName":null,"latestVersion":"4.0.0","tractionLabel":"4.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T05:34:47.556Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T05:34:47.557Z","lastCrawledAt":"2026-10-09T05:34:47.556Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T05:34:47.556Z","lastVerifiedAt":null,"highlights":[{"version":"4.0.0","createdAt":"2026-06-09T18:27:46.036Z","changelog":"- Added Semantic Caching Proxy to intercept and cache API calls, reducing repeated costs. - Introduced granular session termination via the dashboard's Command Center. - Dashboard overview now includes Semantic Caching Proxy controls and real-time CLI execution. - Updated documentation and removed redundant skill-card.md file. - No changes to command-line usage or agent workflow.","fileCount":3,"zipByteSize":4259},{"version":"3.0.0","createdAt":"2026-06-02T15:00:52.822Z","changelog":"- Removed the deprecated skill-card.md file. - Updated description for v3.3.0: highlights Enterprise SOC2 audit logging and local model (Ollama, vLLM) tracking. - Added instructions for logging local models using --local and --duration, and registering GPU hourly rates in the dashboard. - Detailed SOC2 tamper-evident audit chain (Enterprise only) now mentioned in features and commands. - Clarified dashboard sections for compliance, local models, and Pro/Enterprise features. - Other minor clarifications and streamlined workflow guidance.","fileCount":3,"zipByteSize":3776},{"version":"2.5.3","createdAt":"2026-05-30T17:12:38.656Z","changelog":"- Complete rebrand to CostHQ. - Introduced Emerald Glassmorphism Dashboard. - Pro Tier now locked in as a submodule. - Updated documentation to reflect branding and new dashboard features.","fileCount":3,"zipByteSize":5157},{"version":"2.5.2","createdAt":"2026-05-29T10:22:10.736Z","changelog":"- Renamed the skill from \"codesession\" to \"costhq\". - Updated all references, links, and metadata to use the new \"costhq\" branding and GitHub/npm URLs. - Added information on new features: Console UI dashboard and unlocked Pro architecture. - Updated documentation and examples to match CostHQ v3.0.3. - Removed outdated or redundant files, including the old skill-card.","fileCount":3,"zipByteSize":5200},{"version":"2.5.1","createdAt":"2026-03-07T14:47:27.227Z","changelog":"**Summary:** v2.5.1 introduces one-line session runs, new dashboard features, and multi-project context. - Added `cs run ` for streamlined session tracking, proxying, and cost summary in a single step - Introduced `cs today` for multi-project session context - Dashboard gains a Help tab for easier guidance - Maintains support for Codex pricing, with security and stability fixes - Documentation and descriptions updated to reflect new capabilities","fileCount":3,"zipByteSize":5558},{"version":"2.4.0","createdAt":"2026-02-28T22:13:27.264Z","changelog":"Codex pricing (codex-mini-latest, gpt-5.1-codex-max, gpt-5.1-codex-mini, gpt-5.3-codex), security fixes, stability improvements","fileCount":2,"zipByteSize":4059},{"version":"2.3.0","createdAt":"2026-02-26T19:53:08.189Z","changelog":"- Skill description and documentation updated for v2.3.0, including expanded compatibility and feature coverage. - References updated to include integration with Claude Code, OpenClaw, Codex, GPT, Cursor, Windsurf, and Cline. - Added mentions of new features: MCP server support and enhanced integration options. - Removed the redundant _meta.json file.","fileCount":2,"zipByteSize":4020},{"version":"2.2.0","createdAt":"2026-02-17T15:25:04.261Z","changelog":"Add MCP server for Claude Code integration","fileCount":2,"zipByteSize":3925}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17935t6g2g6grny1r9yk1eze986zjyt:costhq","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-brian-mwirigi-costhq/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-brian-mwirigi-costhq/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-brian-mwirigi-costhq/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-brian-mwirigi-costhq/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-brian-mwirigi-costhq/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-brian-mwirigi-costhq/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T01:43:26.713Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-brian-mwirigi-costhq/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-brian-mwirigi-costhq/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-brian-mwirigi-costhq/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-brian-mwirigi-costhq/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T05:34:47.557Z","emptyReason":null},"readme":"Skill: CostHQ\n\nOwner: brian-mwirigi\n\nSummary: Track agent session costs, file changes, and git commits with CostHQ. Enforces budget limits, tracks local models, and provides Enterprise SOC2 audit trails...\n\nTags: latest:4.0.0\n\nVersion history:\n\nv4.0.0 | 2026-06-09T18:27:46.036Z | user\n\n- Added Semantic Caching Proxy to intercept and cache API calls, reducing repeated costs.\n- Introduced granular session termination via the dashboard's Command Center.\n- Dashboard overview now includes Semantic Caching Proxy controls and real-time CLI execution.\n- Updated documentation and removed redundant skill-card.md file.\n- No changes to command-line usage or agent workflow.\n\nv3.0.0 | 2026-06-02T15:00:52.822Z | user\n\n- Removed the deprecated skill-card.md file.\n- Updated description for v3.3.0: highlights Enterprise SOC2 audit logging and local model (Ollama, vLLM) tracking.\n- Added instructions for logging local models using --local and --duration, and registering GPU hourly rates in the dashboard.\n- Detailed SOC2 tamper-evident audit chain (Enterprise only) now mentioned in features and commands.\n- Clarified dashboard sections for compliance, local models, and Pro/Enterprise features.\n- Other minor clarifications and streamlined workflow guidance.\n\nv2.5.3 | 2026-05-30T17:12:38.656Z | user\n\n- Complete rebrand to CostHQ.\n- Introduced Emerald Glassmorphism Dashboard.\n- Pro Tier now locked in as a submodule.\n- Updated documentation to reflect branding and new dashboard features.\n\nv2.5.2 | 2026-05-29T10:22:10.736Z | auto\n\n- Renamed the skill from \"codesession\" to \"costhq\".\n- Updated all references, links, and metadata to use the new \"costhq\" branding and GitHub/npm URLs.\n- Added information on new features: Console UI dashboard and unlocked Pro architecture.\n- Updated documentation and examples to match CostHQ v3.0.3.\n- Removed outdated or redundant files, including the old skill-card.\n\nv2.5.1 | 2026-03-07T14:47:27.227Z | auto\n\n**Summary:** v2.5.1 introduces one-line session runs, new dashboard features, and multi-project context.\n\n- Added `cs run ` for streamlined session tracking, proxying, and cost summary in a single step\n- Introduced `cs today` for multi-project session context\n- Dashboard gains a Help tab for easier guidance\n- Maintains support for Codex pricing, with security and stability fixes\n- Documentation and descriptions updated to reflect new capabilities\n\nv2.4.0 | 2026-02-28T22:13:27.264Z | user\n\nCodex pricing (codex-mini-latest, gpt-5.1-codex-max, gpt-5.1-codex-mini, gpt-5.3-codex), security fixes, stability improvements\n\nv2.3.0 | 2026-02-26T19:53:08.189Z | auto\n\n- Skill description and documentation updated for v2.3.0, including expanded compatibility and feature coverage.\n- References updated to include integration with Claude Code, OpenClaw, Codex, GPT, Cursor, Windsurf, and Cline.\n- Added mentions of new features: MCP server support and enhanced integration options.\n- Removed the redundant _meta.json file.\n\nv2.2.0 | 2026-02-17T15:25:04.261Z | user\n\nAdd MCP server for Claude Code integration\n\nv2.1.0 | 2026-02-16T04:09:29.260Z | user\n\nParallel session support for multi-agent workflows, donate page, auto-log bug fixes\n\nv2.0.1 | 2026-02-15T16:21:08.873Z | user\n\nRemove M-Pesa from donate page, add sponsor links, fix 3 critical auto-log bugs (token loss, TTY hang, position corruption)\n\nv2.0.0 | 2026-02-15T11:34:25.204Z | user\n\nAlerts dashboard, start fresh, insights page, alarm mode, bug fixes\n\nv1.9.8 | 2026-02-13T07:26:27.132Z | user\n\nBug fixes, removed postinstall script, version sync\n\nv1.9.5 | 2026-02-12T14:21:48.326Z | user\n\nAdd GitHub star CTAs to README, post-install message, and dashboard sidebar\n\nv1.9.4 | 2026-02-12T11:57:50.432Z | user\n\nFix CSV export missing agent data, implement CODESESSION_AGENT_NAME env var fallback, add session ID validation on diff-stats endpoint\n\nv1.9.3 | 2026-02-11T19:48:05.939Z | user\n\nFix SPA routing on page refresh - /sessions /models /insights now work on refresh\n\nv1.9.2 | 2026-02-11T17:05:05.391Z | user\n\nUpdated documentation with agent name tracking examples\n\nv1.9.1 | 2026-02-11T16:59:25.858Z | auto\n\n- No changes detected in this release; documentation and features remain unchanged.\n- Version bump to 1.9.1 with no file or SKILL.md modifications.\n\nv1.8.8 | 2026-02-11T09:25:17.971Z | auto\n\nNo changes detected in this release.\n\n- Version 1.8.8 contains no file changes from the previous release.\n\nv1.8.7 | 2026-02-11T06:50:54.673Z | auto\n\n- No user-visible changes in this version.\n- No file changes detected from the previous release.\n\nv1.8.6 | 2026-02-11T06:49:36.035Z | auto\n\n- No changes detected in this version; the SKILL.md file remains unchanged.\n- This release maintains all previous features and usage instructions.\n\nv1.8.5 | 2026-02-10T19:11:49.003Z | auto\n\n- Added an \"Update check\" section with instructions for periodically verifying if codesession-cli is up to date and non-blocking user notifications for updates.\n- No changes to functionality or usage instructions; documentation update only.\n\nv1.8.4 | 2026-02-09T22:15:30.838Z | auto\n\n- Added explicit installation requirements for C/C++ build tools and platform-specific setup instructions.\n- Clarified the difference between agent/JSON mode and interactive mode for starting sessions.\n- Updated all example commands to consistently use --json for structured agent output.\n- Emphasized that agents should always use --json and that session creation does not require a long-running process.\n- Improved explanations of how file and commit tracking works in JSON/agent mode.\n- Removed the emoji from the metadata section.\n\nv1.8.3 | 2026-02-09T22:10:25.348Z | auto\n\n- No user-visible changes in this release.\n- No file changes detected; documentation and functionality remain the same.\n\nv1.8.2 | 2026-02-09T19:51:24.367Z | auto\n\n- No file changes detected in this version.\n- No updates or modifications were made to the skill's documentation or implementation.\n\nv1.8.1 | 2026-02-09T17:37:54.152Z | auto\n\n- No user-visible changes in this release.\n- Version bump only; no file changes detected.\n\nv1.8.0 | 2026-02-09T17:27:33.490Z | auto\n\nNo changes detected in this version (1.8.0). No updates or modifications applied.\n\nv1.7.1 | 2026-02-09T17:16:42.843Z | auto\n\n- No code or documentation changes in this release.\n- Version bump to 1.7.1 without modifications.\n\nv1.6.5 | 2026-02-09T16:58:01.909Z | auto\n\n- Documentation in SKILL.md has been reformatted for improved clarity and conciseness.\n- No changes to code or functionality.\n\nv1.6.4 | 2026-02-09T16:55:43.000Z | auto\n\n- Added documentation for the new web dashboard (`cs dashboard`), including usage instructions and analytics features.\n- Updated description to mention detailed session analytics with a web dashboard.\n- Expanded instructions for workflow and usage, now referencing dashboard review.\n- Added details about dashboard features: overview, sessions, models, insights.\n- Minor clarifications and enhancements throughout the documentation.\n\nv1.6.3 | 2026-02-09T16:05:39.612Z | user\n\nAdded Installation section with npm install instructions and requirements\n\nv1.6.2 | 2026-02-09T16:04:16.288Z | user\n\nAdded installation instructions to SKILL.md\n\nv1.6.1 | 2026-02-09T15:59:26.783Z | auto\n\nv1.6.1 ā€” No code or documentation changes in this release.\n\n- No file changes were detected between this and the previous version.\n- Functionality and documentation remain the same as v1.6.0.\n\nv1.6.0 | 2026-02-09T15:56:13.037Z | auto\n\n- Added _meta.json file for enhanced metadata management.\n- SKILL.md cleaned up: removed redundant sections and simplified content for clarity.\n- No changes to commands or core workflow instructions.\n\nv1.5.1 | 2026-02-09T12:33:55.141Z | user\n\nImprove discoverability: add synonym line for vector search\n\nv1.5.0 | 2026-02-09T11:56:37.945Z | user\n\nv1.5.0\n\nArchive index:\n\nArchive v4.0.0: 3 files, 4259 bytes\n\nFiles: skill-card.md (2464b), SKILL.md (5653b), _meta.json (125b)\n\nFile v4.0.0:SKILL.md\n\n---\nname: costhq\nlicense: MIT-0\ndescription: Track agent session costs, file changes, and git commits with CostHQ. Enforces budget limits, tracks local models, and provides Enterprise SOC2 audit trails via a web dashboard. v3.3.0 - Enterprise SOC2 Audit Logging and Local Models.\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/brian-mwirigi/costhq\", \"requires\": {\"bins\": [\"cs\"]}, \"install\": [{\"id\": \"npm\", \"kind\": \"node\", \"package\": \"costhq\", \"bins\": [\"cs\"], \"label\": \"Install costhq (npm)\"}]}}\n---\n\n# Session Cost Tracking (CostHQ)\n\nTrack agent session costs, file changes, and git commits. Enforces budget limits, tracks local models (Ollama, vLLM), and provides detailed session analytics with a full web dashboard and tamper-evident SOC2 audit logging for Enterprise users.\n\n**Latest: v4.0.0** - Added Semantic Caching Proxy and Granular Session Termination.\n\nšŸ“¦ [npm](https://www.npmjs.com/package/costhq) ā€¢ ā­ [GitHub](https://github.com/brian-mwirigi/costhq) ā€¢ šŸ“ [Changelog](https://github.com/brian-mwirigi/costhq/blob/main/CHANGELOG.md)\n\n## Installation\n\n```bash\n# 1. Install the CLI globally from npm\nnpm install -g costhq\n\n# 2. Install the OpenClaw skill\nclawhub install costhq\n```\n\nAfter installing, the `cs` command is available globally. The OpenClaw agent will automatically use it to track sessions.\n\n> **Requirements:** Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).\n>\n> | OS | Install build tools |\n> |---|---|\n> | **Ubuntu/Debian** | `sudo apt-get install -y build-essential python3` |\n> | **macOS** | `xcode-select --install` |\n> | **Windows** | `npm install -g windows-build-tools` or install Visual Studio Build Tools |\n> | **Alpine** | `apk add build-base python3` |\n>\n> Data is stored locally at `~/.costhq/sessions.db` (or `~/.CostHQ`).\n\n## When to use\n\n- **Always** start a tracked session at the beginning of a multi-step task\n- **Always** log AI usage after each API call you make\n- **Always** end the session when the task is complete\n- Use `cs dashboard` to review session data, set up local models, or verify the audit trail (Enterprise).\n\n## Commands\n\n### Start tracking\n```bash\n# Agent mode (always use --json for structured output):\ncs start \"task description\" --json --close-stale\n\n# Resume if a session was left open (e.g. after a crash):\ncs start \"task description\" --json --resume\n```\n\n### Log AI usage (after each API call)\n```bash\n# Standard cloud model (cost auto-calculated):\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json\n\n# Local model with compute duration (NEW in v3.3.0):\n# Use --duration in seconds (120) or string (2m30s). Cost is based on registered $/hr rate.\ncs log-ai -p ollama -m llama3 --tokens 4500 --duration 2m30s --local --json\n\n# With all fields:\ncs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent \"Research Agent\" --json\n```\n\n**Agent Name:** Use `--agent \"Agent Name\"` to track which agent performed the work.\n**Local Models:** You can track self-hosted models (Ollama, llama.cpp, vLLM) by registering a GPU hourly rate in the dashboard. Use `--duration` and `--local` when logging.\n\n### Check current status\n```bash\ncs status --json\n```\n\n### End session and get summary\n```bash\ncs end -n \"completion notes\" --json\n```\nEnding the session automatically logs an audit event (Enterprise) and scans git for files/commits.\n\n### Web Dashboard\n```bash\ncs dashboard\n```\nThe dashboard shows:\n- **Overview** ā€” KPIs, daily trends, cost velocity, and the Semantic Caching Proxy toggle.\n- **Command Center** ā€” Real-time CLI execution and granular termination of individual sessions.\n- **Sessions** ā€” searchable/sortable table, per-session details.\n- **Local Models** ā€” Register compute rates ($/hr) for Ollama, vLLM, etc.\n- **Compliance** ā€” View the tamper-evident cryptographic SOC2 audit chain and configure Team Identities (Enterprise only).\n- **Pro Ops** ā€” Manage licensing, PDF exports, and sync features.\n\n### Semantic Caching Proxy\nTo save money, CostHQ includes a Semantic Caching Proxy that intercepts API calls and returns cached responses for identical requests:\n```bash\ncs proxy start --port 3739\n```\nOr toggle it directly from the **Overview** page in the dashboard. Route your tools via `OPENAI_BASE_URL=http://127.0.0.1:3739/openai/v1`.\n\n### View historical stats and details\n```bash\ncs show --json --files --commits\ncs stats --json\ncs export --format json --limit 10\n```\n\n### Add notes / annotations\n```bash\ncs note \"Tests passing, moving to cleanup\" --json\n```\n\n## Agent Workflow\n\nAgents should **always** use `--json` on every command for structured, parseable output.\n\n1. At task start: `cs start \"Fix authentication bug\" --json --close-stale`\n2. Add context notes: `cs note \"analyzing auth flow\" --json`\n3. After each AI call: `cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 800 --completion-tokens 200 --agent \"Bug Fixer\" --json`\n4. If using a local model: `cs log-ai -p ollama -m mistral --tokens 1000 --duration 45s --local --json`\n5. At task end: `cs end -n \"Fixed the auth bug\" --json`\n\n## Budget & Pricing\n- Standard pricing is configurable via `cs pricing set my-model 5.00 15.00`.\n- Local model pricing (compute-based) is configured in the `cs dashboard` under **Local Models**.\n- Check `cs status --json` before expensive operations.\n\n## Important\n- **Always** use `--json` on every command ā€” agents must use structured output.\n- Use `--close-stale` on `cs start` to clear crashed sessions.\n- In Enterprise mode, a cryptographic hash chain automatically logs session starts, ends, data resets, and AI usage.\n\nFile v4.0.0:_meta.json\n\n{\n \"ownerId\": \"kn756bc007k4jgde4rdmc008d580tqt4\",\n \"slug\": \"costhq\",\n \"version\": \"4.0.0\",\n \"publishedAt\": 1781029666036\n}\n\nFile v4.0.0:skill-card.md\n\n## Description:\n\nTrack agent session costs, file changes, and git commits with CostHQ, including budget limits, local model tracking, dashboard analytics, and Enterprise SOC2 audit trails.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[brian-mwirigi](https://clawhub.ai/user/brian-mwirigi)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and engineering teams use CostHQ to track agent task sessions, log AI usage costs, review file and commit activity, manage budgets, and inspect activity through a local dashboard.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: CostHQ can record agent activity, usage details, file changes, commits, and repository metadata.\n\nMitigation: Install only in repositories where this monitoring is acceptable, prefer a pinned reviewed npm package version, and review collected session data before using it for audit or reporting.\n\nRisk: The Semantic Caching Proxy intercepts API calls and may cache prompts or responses.\n\nMitigation: Avoid routing secrets, customer data, or regulated prompts through the proxy until retention, cache purge, and access-control behavior are clear.\n\nRisk: Dashboard command controls can affect active tracked sessions and execute CostHQ CLI operations.\n\nMitigation: Restrict dashboard access to trusted users and avoid running installation or CostHQ commands with elevated privileges unless required.\n\n## Reference(s):\n\n- [CostHQ ClawHub Listing](https://clawhub.ai/brian-mwirigi/skills/costhq)\n- [CostHQ GitHub Repository](https://github.com/brian-mwirigi/costhq)\n- [CostHQ npm Package](https://www.npmjs.com/package/costhq)\n- [CostHQ Changelog](https://github.com/brian-mwirigi/costhq/blob/main/CHANGELOG.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown with bash command examples and JSON-oriented CLI guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Commands are expected to use --json and may read or write local CostHQ session data.]\n\n## Skill Version(s):\n\n4.0.0 (source: server release metadata; artifact heading also states Latest v4.0.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v3.0.0: 3 files, 3776 bytes\n\nFiles: skill-card.md (1965b), SKILL.md (5188b), _meta.json (125b)\n\nFile v3.0.0:SKILL.md\n\n---\nname: costhq\nlicense: MIT-0\ndescription: Track agent session costs, file changes, and git commits with CostHQ. Enforces budget limits, tracks local models, and provides Enterprise SOC2 audit trails via a web dashboard. v3.3.0 - Enterprise SOC2 Audit Logging and Local Models.\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/brian-mwirigi/costhq\", \"requires\": {\"bins\": [\"cs\"]}, \"install\": [{\"id\": \"npm\", \"kind\": \"node\", \"package\": \"costhq\", \"bins\": [\"cs\"], \"label\": \"Install costhq (npm)\"}]}}\n---\n\n# Session Cost Tracking (CostHQ)\n\nTrack agent session costs, file changes, and git commits. Enforces budget limits, tracks local models (Ollama, vLLM), and provides detailed session analytics with a full web dashboard and tamper-evident SOC2 audit logging for Enterprise users.\n\n**Latest: v3.3.0** - Added Enterprise SOC2 Audit Trails and Local Models (compute-time costing).\n\nšŸ“¦ [npm](https://www.npmjs.com/package/costhq) ā€¢ ā­ [GitHub](https://github.com/brian-mwirigi/costhq) ā€¢ šŸ“ [Changelog](https://github.com/brian-mwirigi/costhq/blob/main/CHANGELOG.md)\n\n## Installation\n\n```bash\n# 1. Install the CLI globally from npm\nnpm install -g costhq\n\n# 2. Install the OpenClaw skill\nclawhub install costhq\n```\n\nAfter installing, the `cs` command is available globally. The OpenClaw agent will automatically use it to track sessions.\n\n> **Requirements:** Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).\n>\n> | OS | Install build tools |\n> |---|---|\n> | **Ubuntu/Debian** | `sudo apt-get install -y build-essential python3` |\n> | **macOS** | `xcode-select --install` |\n> | **Windows** | `npm install -g windows-build-tools` or install Visual Studio Build Tools |\n> | **Alpine** | `apk add build-base python3` |\n>\n> Data is stored locally at `~/.costhq/sessions.db` (or `~/.CostHQ`).\n\n## When to use\n\n- **Always** start a tracked session at the beginning of a multi-step task\n- **Always** log AI usage after each API call you make\n- **Always** end the session when the task is complete\n- Use `cs dashboard` to review session data, set up local models, or verify the audit trail (Enterprise).\n\n## Commands\n\n### Start tracking\n```bash\n# Agent mode (always use --json for structured output):\ncs start \"task description\" --json --close-stale\n\n# Resume if a session was left open (e.g. after a crash):\ncs start \"task description\" --json --resume\n```\n\n### Log AI usage (after each API call)\n```bash\n# Standard cloud model (cost auto-calculated):\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json\n\n# Local model with compute duration (NEW in v3.3.0):\n# Use --duration in seconds (120) or string (2m30s). Cost is based on registered $/hr rate.\ncs log-ai -p ollama -m llama3 --tokens 4500 --duration 2m30s --local --json\n\n# With all fields:\ncs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent \"Research Agent\" --json\n```\n\n**Agent Name:** Use `--agent \"Agent Name\"` to track which agent performed the work.\n**Local Models:** You can track self-hosted models (Ollama, llama.cpp, vLLM) by registering a GPU hourly rate in the dashboard. Use `--duration` and `--local` when logging.\n\n### Check current status\n```bash\ncs status --json\n```\n\n### End session and get summary\n```bash\ncs end -n \"completion notes\" --json\n```\nEnding the session automatically logs an audit event (Enterprise) and scans git for files/commits.\n\n### Web Dashboard\n```bash\ncs dashboard\n```\nThe dashboard shows:\n- **Overview** ā€” KPIs, daily trends, cost velocity.\n- **Sessions** ā€” searchable/sortable table, per-session details.\n- **Local Models** ā€” Register compute rates ($/hr) for Ollama, vLLM, etc.\n- **Compliance** ā€” View the tamper-evident cryptographic SOC2 audit chain and configure Team Identities (Enterprise only).\n- **Pro Ops** ā€” Manage licensing, PDF exports, and sync features.\n\n### View historical stats and details\n```bash\ncs show --json --files --commits\ncs stats --json\ncs export --format json --limit 10\n```\n\n### Add notes / annotations\n```bash\ncs note \"Tests passing, moving to cleanup\" --json\n```\n\n## Agent Workflow\n\nAgents should **always** use `--json` on every command for structured, parseable output.\n\n1. At task start: `cs start \"Fix authentication bug\" --json --close-stale`\n2. Add context notes: `cs note \"analyzing auth flow\" --json`\n3. After each AI call: `cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 800 --completion-tokens 200 --agent \"Bug Fixer\" --json`\n4. If using a local model: `cs log-ai -p ollama -m mistral --tokens 1000 --duration 45s --local --json`\n5. At task end: `cs end -n \"Fixed the auth bug\" --json`\n\n## Budget & Pricing\n- Standard pricing is configurable via `cs pricing set my-model 5.00 15.00`.\n- Local model pricing (compute-based) is configured in the `cs dashboard` under **Local Models**.\n- Check `cs status --json` before expensive operations.\n\n## Important\n- **Always** use `--json` on every command ā€” agents must use structured output.\n- Use `--close-stale` on `cs start` to clear crashed sessions.\n- In Enterprise mode, a cryptographic hash chain automatically logs session starts, ends, data resets, and AI usage.\n\nFile v3.0.0:_meta.json\n\n{\n \"ownerId\": \"kn756bc007k4jgde4rdmc008d580tqt4\",\n \"slug\": \"costhq\",\n \"version\": \"3.0.0\",\n \"publishedAt\": 1780412452822\n}\n\nFile v3.0.0:skill-card.md\n\n## Description:
\nTrack agent session costs, file changes, and git commits with CostHQ; enforce budget limits, track local models, and provide Enterprise SOC2 audit trails through a web dashboard.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[brian-mwirigi](https://clawhub.ai/user/brian-mwirigi)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and engineering agents use CostHQ to start and end tracked work sessions, log AI model usage, monitor budget status, and review session cost and audit data.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: Cost and activity tracking can record session metadata, file changes, git commits, and local dashboard data that may be sensitive in some repositories.
\nMitigation: Use the skill only where intentional tracking is appropriate, and confirm storage location, retention behavior, export exposure, and deletion or disablement options before use in sensitive workspaces.
\n\n\n## Reference(s):
\n- [CostHQ ClawHub page](https://clawhub.ai/brian-mwirigi/costhq)
\n- [CostHQ homepage](https://github.com/brian-mwirigi/costhq)
\n- [CostHQ npm package](https://www.npmjs.com/package/costhq)
\n\n\n## Skill Output:
\n**Output Type(s):** [Shell commands, Configuration, Guidance, JSON]
\n**Output Format:** [Markdown with inline bash commands and JSON-oriented command guidance]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Agent commands should use --json for structured output.]
\n\n## Skill Version(s):
\n3.0.0 (source: server-resolved release metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v2.5.3: 3 files, 5157 bytes\n\nFiles: skill-card.md (2198b), SKILL.md (8439b), _meta.json (125b)\n\nFile v2.5.3:SKILL.md\n\n---\r\nname: costhq\nlicense: MIT-0\r\ndescription: Track agent session costs, file changes, and git commits with costhq. Enforces budget limits and provides detailed session analytics with a web dashboard. v3.2.0 - Complete rebrand to CostHQ, Emerald Glassmorphism Dashboard, Pro Tier locked in Submodule.\r\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/brian-mwirigi/costhq\", \"requires\": {\"bins\": [\"cs\"]}, \"install\": [{\"id\": \"npm\", \"kind\": \"node\", \"package\": \"costhq\", \"bins\": [\"cs\"], \"label\": \"Install costhq (npm)\"}]}}\r\n---\r\n\r\n# Session Cost Tracking (costhq)\r\n\r\nTrack agent session costs, file changes, and git commits. Enforces budget limits and provides detailed session analytics with a full web dashboard.\r\n\r\n**Latest: v3.2.0** - Complete rebrand to CostHQ, Emerald Glassmorphism Dashboard, Pro Tier locked in Submodule.\r\n\r\nšŸ“¦ [npm](https://www.npmjs.com/package/costhq) ā€¢ ā­ [GitHub](https://github.com/brian-mwirigi/costhq) ā€¢ šŸ“ [Changelog](https://github.com/brian-mwirigi/costhq/blob/main/CHANGELOG.md)\r\n\r\n## Installation\r\n\r\n```bash\r\n# 1. Install the CLI globally from npm\r\nnpm install -g costhq\r\n\r\n# 2. Install the OpenClaw skill\r\nclawhub install costhq\r\n```\r\n\r\nAfter installing, the `cs` command is available globally. The OpenClaw agent will automatically use it to track sessions.\r\n\r\n> **Requirements:** Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).\r\n>\r\n> | OS | Install build tools |\r\n> |---|---|\r\n> | **Ubuntu/Debian** | `sudo apt-get install -y build-essential python3` |\r\n> | **macOS** | `xcode-select --install` |\r\n> | **Windows** | `npm install -g windows-build-tools` or install Visual Studio Build Tools |\r\n> | **Alpine** | `apk add build-base python3` |\r\n>\r\n> Data is stored locally at `~/.CostHQ/sessions.db`.\r\n\r\n## When to use\r\n\r\n- **Always** start a tracked session at the beginning of a multi-step task\r\n- **Always** log AI usage after each API call you make\r\n- **Always** end the session when the task is complete\r\n- Check budget before expensive operations\r\n- Use `cs dashboard` to review session data in a browser\r\n\r\n## Commands\r\n\r\n### Start tracking\r\n```bash\r\n# Agent mode (always use --json for structured output):\r\ncs start \"task description\" --json --close-stale\r\n\r\n# Resume if a session was left open (e.g. after a crash):\r\ncs start \"task description\" --json --resume\r\n\r\n# Human/interactive mode (stays running with live file watcher):\r\ncs start \"task description\"\r\n```\r\n\r\n> **Agent mode vs interactive mode:** With `--json`, the session is created in the database, JSON is printed, and the process exits immediately -- the session stays \"active\" and tracks git changes when you run `cs end`. Without `--json`, the process stays running with a live file watcher and git commit poller until you press Ctrl+C or run `cs end` in another terminal.\r\n\r\n### Log AI usage (after each API call)\r\n```bash\r\n# With granular tokens (cost auto-calculated from built-in pricing):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json\r\n\r\n# With agent name tracking (NEW in v1.9.1):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Code Review Bot\" --json\r\n\r\n# With manual cost:\r\ncs log-ai -p anthropic -m claude-opus-4-6 -t 15000 -c 0.30 --json\r\n\r\n# With all fields:\r\ncs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent \"Research Agent\" --json\r\n```\r\nProviders: `anthropic`, `openai`, `google`, `mistral`, `deepseek`\r\nCost is auto-calculated from a configurable pricing table (17+ built-in models). Use `cs pricing list --json` to see known models. If a model is unknown, provide `-c ` manually.\r\n\r\n**Agent Name (optional):** Use `--agent \"Agent Name\"` to track which agent performed the work. Perfect for multi-agent systems, A/B testing, and cost attribution. Agent names appear in the dashboard and can be used to filter/analyze costs per agent.\r\n\r\n### Check current status\r\n```bash\r\ncs status --json\r\n```\r\nReturns JSON with current session cost, tokens, files changed, duration. All JSON responses include `schemaVersion` and `CostHQVersion` fields.\r\n\r\n### End session and get summary\r\n```bash\r\ncs end -n \"completion notes\" --json\r\n```\r\nWhen ending, CostHQ automatically scans git for all files changed and commits made since the session started -- even if `--json` mode was used (no live watcher needed).\r\n\r\n### Web Dashboard\r\n```bash\r\ncs dashboard\r\n# Opens http://localhost:3737 with full analytics UI\r\n\r\ncs dashboard --port 4000 # custom port\r\ncs dashboard --no-open # don't auto-open browser\r\n```\r\n\r\nThe dashboard shows:\r\n- **Overview** ā€” KPIs, daily cost/token trends, spend projections, cost velocity\r\n- **Sessions** ā€” searchable/sortable table, per-session detail with timeline, files, commits, AI calls, notes\r\n- **Models** ā€” per-model & per-provider cost breakdown, token ratios, usage charts\r\n- **Insights** ā€” file hotspots, activity heatmap, project breakdown, pricing table\r\n- **Alerts** ā€” set daily/total/per-session cost thresholds with alarm mode (sound + browser notifications)\r\n- **Start Fresh** ā€” reset all session data from the sidebar\r\n\r\n### View session details\r\n```bash\r\ncs show --json --files --commits\r\n```\r\n\r\n### View historical stats\r\n```bash\r\ncs stats --json\r\n```\r\n\r\n### Export sessions\r\n```bash\r\ncs export --format json --limit 10\r\ncs export --format csv\r\n```\r\n\r\n### Add notes / annotations\r\n```bash\r\ncs note \"Starting refactor phase\"\r\ncs note \"Tests passing, moving to cleanup\"\r\n```\r\nTimestamped annotations appear in `cs show --json` under `annotations`.\r\n\r\n### Recover stale sessions\r\n```bash\r\ncs recover --max-age 12\r\n```\r\nAuto-ends any active sessions older than 12 hours.\r\n\r\n## Agent Workflow\r\n\r\nAgents should **always** use `--json` on every command for structured, parseable output.\r\n\r\n1. At task start: `cs start \"Fix authentication bug\" --json --close-stale`\r\n2. Add context notes: `cs note \"analyzing auth flow\" --json`\r\n3. After each AI call: `cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Bug Fixer\" --json`\r\n4. Check spend: `cs status --json` -- read `aiCost` field\r\n5. At task end: `cs end -n \"Fixed the auth bug, added tests\" --json`\r\n6. Review past sessions: `cs dashboard`\r\n\r\n**Tip:** Use the `--agent` flag to identify your agent's work, especially useful in multi-agent systems where different agents handle different tasks (e.g., \"Code Review Bot\", \"Test Writer\", \"Documentation Agent\").\r\n\r\n## Pricing\r\n\r\nPricing is configurable. Run `cs pricing list` to see all known model prices. Override or add models:\r\n\r\n```bash\r\n# Plain model key\r\ncs pricing set my-model 5.00 15.00\r\n\r\n# Provider-namespaced key (avoids collisions)\r\ncs pricing set gpt-4o 2.50 10.00 --provider openai\r\n```\r\n\r\nIf the model isn't in the pricing table, you must provide `-c ` when logging.\r\n\r\n## Budget awareness\r\n\r\nIf the user has set a budget or you detect high spending:\r\n- Check `cs status --json` before expensive operations\r\n- Warn the user if `aiCost` exceeds $5.00 in a single session\r\n- Suggest cheaper models if costs are escalating\r\n\r\n## Important\r\n\r\n- Use `--close-stale` on `cs start` to avoid \"session_active\" errors from prior crashes\r\n- If `cs` is not installed, skip session tracking ā€” don't block the user's task\r\n- **Always** use `--json` on every command ā€” agents must use structured output\r\n- With `--json`, `cs start` creates the session and exits (no long-running process needed)\r\n- Sessions are scoped by **git root** ā€” running from a subdirectory still matches the repo-level session\r\n- On errors in `--json` mode, exit code is always `1` and the response has `{ \"error\": { \"code\": \"...\", \"message\": \"...\" } }`\r\n- Check `schemaVersion` in JSON responses to detect breaking changes\r\n\r\n## Update check\r\n\r\nPeriodically check if the CLI is up to date (e.g. at session start or once per day):\r\n\r\n```bash\r\n# Compare installed version to latest on npm:\r\ncs --version # installed version\r\nnpm view costhq version # latest on npm\r\n```\r\n\r\nIf the installed version is behind, notify the user:\r\n> \"costhq update available: v3.0.2 -> v3.0.3. Run `npm install -g costhq` to update.\"\r\n\r\nDon't block the workflow for an update ā€” just inform and continue.\r\n\r\n## JSON output\r\n\r\nAll commands support `--json` for machine-readable output. Use this when you need to parse session data programmatically.\n\nFile v2.5.3:_meta.json\n\n{\n \"ownerId\": \"kn756bc007k4jgde4rdmc008d580tqt4\",\n \"slug\": \"costhq\",\n \"version\": \"2.5.3\",\n \"publishedAt\": 1780161158656\n}\n\nFile v2.5.3:skill-card.md\n\n## Description:
\nCostHQ helps agents track session costs, file changes, git commits, budget status, and session analytics through a local CLI and web dashboard.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[brian-mwirigi](https://clawhub.ai/user/brian-mwirigi)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and agent operators use CostHQ to monitor task-level AI spending, repository activity, notes, and budget status during agent sessions. It is useful when teams need local cost attribution and session analytics for agent-assisted engineering work.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: CostHQ stores local session history, changed-file paths, git commit metadata, AI usage entries, notes, and costs in ~/.CostHQ/sessions.db.
\nMitigation: Use it only where that local audit trail is acceptable, especially for sensitive repositories.
\nRisk: Reset and Start Fresh workflows can remove local session history.
\nMitigation: Export or back up session data before using reset features when retention matters.
\n\n\n## Reference(s):
\n- [CostHQ on ClawHub](https://clawhub.ai/brian-mwirigi/costhq)
\n- [CostHQ GitHub repository](https://github.com/brian-mwirigi/costhq)
\n- [CostHQ npm package](https://www.npmjs.com/package/costhq)
\n- [CostHQ changelog](https://github.com/brian-mwirigi/costhq/blob/main/CHANGELOG.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [Shell commands, Configuration, Guidance, JSON]
\n**Output Format:** [Markdown with inline bash commands and JSON-oriented CLI guidance]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Agent-facing commands should use --json so CostHQ responses remain structured and parseable.]
\n\n## Skill Version(s):
\n2.5.3 (source: server release metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v2.5.2: 3 files, 5200 bytes\n\nFiles: skill-card.md (2416b), SKILL.md (8385b), _meta.json (125b)\n\nFile v2.5.2:SKILL.md\n\n---\r\nname: costhq\nlicense: MIT-0\r\ndescription: Track agent session costs, file changes, and git commits with costhq. Enforces budget limits and provides detailed session analytics with a web dashboard. v3.0.3 - Added Console UI, Pro features unlocked, updated NPM links.\r\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/brian-mwirigi/costhq\", \"requires\": {\"bins\": [\"cs\"]}, \"install\": [{\"id\": \"npm\", \"kind\": \"node\", \"package\": \"costhq\", \"bins\": [\"cs\"], \"label\": \"Install costhq (npm)\"}]}}\r\n---\r\n\r\n# Session Cost Tracking (costhq)\r\n\r\nTrack agent session costs, file changes, and git commits. Enforces budget limits and provides detailed session analytics with a full web dashboard.\r\n\r\n**Latest: v3.0.3** - Console dashboard UI, unlocked Pro architecture, updated NPM links.\r\n\r\nšŸ“¦ [npm](https://www.npmjs.com/package/costhq) ā€¢ ā­ [GitHub](https://github.com/brian-mwirigi/costhq) ā€¢ šŸ“ [Changelog](https://github.com/brian-mwirigi/costhq/blob/main/CHANGELOG.md)\r\n\r\n## Installation\r\n\r\n```bash\r\n# 1. Install the CLI globally from npm\r\nnpm install -g costhq\r\n\r\n# 2. Install the OpenClaw skill\r\nclawhub install costhq\r\n```\r\n\r\nAfter installing, the `cs` command is available globally. The OpenClaw agent will automatically use it to track sessions.\r\n\r\n> **Requirements:** Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).\r\n>\r\n> | OS | Install build tools |\r\n> |---|---|\r\n> | **Ubuntu/Debian** | `sudo apt-get install -y build-essential python3` |\r\n> | **macOS** | `xcode-select --install` |\r\n> | **Windows** | `npm install -g windows-build-tools` or install Visual Studio Build Tools |\r\n> | **Alpine** | `apk add build-base python3` |\r\n>\r\n> Data is stored locally at `~/.CostHQ/sessions.db`.\r\n\r\n## When to use\r\n\r\n- **Always** start a tracked session at the beginning of a multi-step task\r\n- **Always** log AI usage after each API call you make\r\n- **Always** end the session when the task is complete\r\n- Check budget before expensive operations\r\n- Use `cs dashboard` to review session data in a browser\r\n\r\n## Commands\r\n\r\n### Start tracking\r\n```bash\r\n# Agent mode (always use --json for structured output):\r\ncs start \"task description\" --json --close-stale\r\n\r\n# Resume if a session was left open (e.g. after a crash):\r\ncs start \"task description\" --json --resume\r\n\r\n# Human/interactive mode (stays running with live file watcher):\r\ncs start \"task description\"\r\n```\r\n\r\n> **Agent mode vs interactive mode:** With `--json`, the session is created in the database, JSON is printed, and the process exits immediately -- the session stays \"active\" and tracks git changes when you run `cs end`. Without `--json`, the process stays running with a live file watcher and git commit poller until you press Ctrl+C or run `cs end` in another terminal.\r\n\r\n### Log AI usage (after each API call)\r\n```bash\r\n# With granular tokens (cost auto-calculated from built-in pricing):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json\r\n\r\n# With agent name tracking (NEW in v1.9.1):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Code Review Bot\" --json\r\n\r\n# With manual cost:\r\ncs log-ai -p anthropic -m claude-opus-4-6 -t 15000 -c 0.30 --json\r\n\r\n# With all fields:\r\ncs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent \"Research Agent\" --json\r\n```\r\nProviders: `anthropic`, `openai`, `google`, `mistral`, `deepseek`\r\nCost is auto-calculated from a configurable pricing table (17+ built-in models). Use `cs pricing list --json` to see known models. If a model is unknown, provide `-c ` manually.\r\n\r\n**Agent Name (optional):** Use `--agent \"Agent Name\"` to track which agent performed the work. Perfect for multi-agent systems, A/B testing, and cost attribution. Agent names appear in the dashboard and can be used to filter/analyze costs per agent.\r\n\r\n### Check current status\r\n```bash\r\ncs status --json\r\n```\r\nReturns JSON with current session cost, tokens, files changed, duration. All JSON responses include `schemaVersion` and `CostHQVersion` fields.\r\n\r\n### End session and get summary\r\n```bash\r\ncs end -n \"completion notes\" --json\r\n```\r\nWhen ending, CostHQ automatically scans git for all files changed and commits made since the session started -- even if `--json` mode was used (no live watcher needed).\r\n\r\n### Web Dashboard\r\n```bash\r\ncs dashboard\r\n# Opens http://localhost:3737 with full analytics UI\r\n\r\ncs dashboard --port 4000 # custom port\r\ncs dashboard --no-open # don't auto-open browser\r\n```\r\n\r\nThe dashboard shows:\r\n- **Overview** ā€” KPIs, daily cost/token trends, spend projections, cost velocity\r\n- **Sessions** ā€” searchable/sortable table, per-session detail with timeline, files, commits, AI calls, notes\r\n- **Models** ā€” per-model & per-provider cost breakdown, token ratios, usage charts\r\n- **Insights** ā€” file hotspots, activity heatmap, project breakdown, pricing table\r\n- **Alerts** ā€” set daily/total/per-session cost thresholds with alarm mode (sound + browser notifications)\r\n- **Start Fresh** ā€” reset all session data from the sidebar\r\n\r\n### View session details\r\n```bash\r\ncs show --json --files --commits\r\n```\r\n\r\n### View historical stats\r\n```bash\r\ncs stats --json\r\n```\r\n\r\n### Export sessions\r\n```bash\r\ncs export --format json --limit 10\r\ncs export --format csv\r\n```\r\n\r\n### Add notes / annotations\r\n```bash\r\ncs note \"Starting refactor phase\"\r\ncs note \"Tests passing, moving to cleanup\"\r\n```\r\nTimestamped annotations appear in `cs show --json` under `annotations`.\r\n\r\n### Recover stale sessions\r\n```bash\r\ncs recover --max-age 12\r\n```\r\nAuto-ends any active sessions older than 12 hours.\r\n\r\n## Agent Workflow\r\n\r\nAgents should **always** use `--json` on every command for structured, parseable output.\r\n\r\n1. At task start: `cs start \"Fix authentication bug\" --json --close-stale`\r\n2. Add context notes: `cs note \"analyzing auth flow\" --json`\r\n3. After each AI call: `cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Bug Fixer\" --json`\r\n4. Check spend: `cs status --json` -- read `aiCost` field\r\n5. At task end: `cs end -n \"Fixed the auth bug, added tests\" --json`\r\n6. Review past sessions: `cs dashboard`\r\n\r\n**Tip:** Use the `--agent` flag to identify your agent's work, especially useful in multi-agent systems where different agents handle different tasks (e.g., \"Code Review Bot\", \"Test Writer\", \"Documentation Agent\").\r\n\r\n## Pricing\r\n\r\nPricing is configurable. Run `cs pricing list` to see all known model prices. Override or add models:\r\n\r\n```bash\r\n# Plain model key\r\ncs pricing set my-model 5.00 15.00\r\n\r\n# Provider-namespaced key (avoids collisions)\r\ncs pricing set gpt-4o 2.50 10.00 --provider openai\r\n```\r\n\r\nIf the model isn't in the pricing table, you must provide `-c ` when logging.\r\n\r\n## Budget awareness\r\n\r\nIf the user has set a budget or you detect high spending:\r\n- Check `cs status --json` before expensive operations\r\n- Warn the user if `aiCost` exceeds $5.00 in a single session\r\n- Suggest cheaper models if costs are escalating\r\n\r\n## Important\r\n\r\n- Use `--close-stale` on `cs start` to avoid \"session_active\" errors from prior crashes\r\n- If `cs` is not installed, skip session tracking ā€” don't block the user's task\r\n- **Always** use `--json` on every command ā€” agents must use structured output\r\n- With `--json`, `cs start` creates the session and exits (no long-running process needed)\r\n- Sessions are scoped by **git root** ā€” running from a subdirectory still matches the repo-level session\r\n- On errors in `--json` mode, exit code is always `1` and the response has `{ \"error\": { \"code\": \"...\", \"message\": \"...\" } }`\r\n- Check `schemaVersion` in JSON responses to detect breaking changes\r\n\r\n## Update check\r\n\r\nPeriodically check if the CLI is up to date (e.g. at session start or once per day):\r\n\r\n```bash\r\n# Compare installed version to latest on npm:\r\ncs --version # installed version\r\nnpm view costhq version # latest on npm\r\n```\r\n\r\nIf the installed version is behind, notify the user:\r\n> \"costhq update available: v3.0.2 -> v3.0.3. Run `npm install -g costhq` to update.\"\r\n\r\nDon't block the workflow for an update ā€” just inform and continue.\r\n\r\n## JSON output\r\n\r\nAll commands support `--json` for machine-readable output. Use this when you need to parse session data programmatically.\n\nFile v2.5.2:_meta.json\n\n{\n \"ownerId\": \"kn756bc007k4jgde4rdmc008d580tqt4\",\n \"slug\": \"costhq\",\n \"version\": \"2.5.2\",\n \"publishedAt\": 1780050130736\n}\n\nFile v2.5.2:skill-card.md\n\n## Description:
\nTrack agent session costs, file changes, and git commits with CostHQ, enforcing budget limits and providing detailed session analytics through a web dashboard.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[brian-mwirigi](https://clawhub.ai/user/brian-mwirigi)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and agent operators use this skill to install and invoke the CostHQ CLI for tracking AI usage costs, session activity, changed files, commits, and budget status during agent work.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The skill installs and relies on a globally available third-party npm CLI.
\nMitigation: Review the npm package before global installation and install it only when local CostHQ tracking is desired.
\nRisk: CostHQ stores session costs, AI usage, changed files, commits, notes, and analytics locally, which may expose sensitive repository metadata.
\nMitigation: Avoid using it in repositories where filenames or commit metadata are sensitive unless local tracking is acceptable.
\nRisk: The dashboard includes a Start Fresh reset that can remove tracked records.
\nMitigation: Export any records that need to be retained before using dashboard reset features.
\n\n\n## Reference(s):
\n- [CostHQ ClawHub Page](https://clawhub.ai/brian-mwirigi/costhq)
\n- [CostHQ GitHub Repository](https://github.com/brian-mwirigi/costhq)
\n- [CostHQ npm Package](https://www.npmjs.com/package/costhq)
\n- [CostHQ Changelog](https://github.com/brian-mwirigi/costhq/blob/main/CHANGELOG.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [Guidance, Shell commands, Configuration instructions]
\n**Output Format:** [Markdown with inline bash code blocks and JSON command-output guidance]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [The skill instructs agents to use structured JSON output from the CostHQ CLI when tracking sessions.]
\n\n## Skill Version(s):
\n2.5.2 (source: server release metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v2.5.1: 3 files, 5558 bytes\n\nFiles: skill-card.md (2192b), SKILL.md (9439b), _meta.json (125b)\n\nFile v2.5.1:SKILL.md\n\n---\r\nname: codesession\r\ndescription: codesession (codesession-cli, code session, code-session) ā€” Track AI agent session costs, tokens, file changes, and git commits. Works with Claude Code, OpenClaw, Codex, GPT, Cursor, Windsurf, Cline & any AI agent. Budget enforcement, auto-pricing, MCP server, web dashboard, alerts, insights. v2.5.1.\r\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/brian-mwirigi/codesession-cli\", \"requires\": {\"bins\": [\"cs\"]}, \"install\": [{\"id\": \"npm\", \"kind\": \"node\", \"package\": \"codesession-cli\", \"bins\": [\"cs\"], \"label\": \"Install codesession-cli (npm)\"}]}}\r\n---\r\n\r\n# Session Cost Tracking (codesession-cli)\r\n\r\nTrack agent session costs, file changes, and git commits. Enforces budget limits and provides detailed session analytics with a full web dashboard.\r\n\r\n**Latest: v2.5.1** - `cs run ` wraps everything in one step (session + proxy + run + cost summary). `cs today` for multi-project context. Dashboard Help tab, Codex pricing, security fixes.\r\n\r\nšŸ“¦ [npm](https://www.npmjs.com/package/codesession-cli) ā€¢ ā­ [GitHub](https://github.com/brian-mwirigi/codesession-cli) ā€¢ šŸ“ [Changelog](https://github.com/brian-mwirigi/codesession-cli/blob/main/CHANGELOG.md)\r\n\r\n## Installation\r\n\r\n```bash\r\n# 1. Install the CLI globally from npm\r\nnpm install -g codesession-cli\r\n\r\n# 2. Install the OpenClaw skill\r\nclawhub install codesession\r\n```\r\n\r\nAfter installing, the `cs` command is available globally. The OpenClaw agent will automatically use it to track sessions.\r\n\r\n> **Requirements:** Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).\r\n>\r\n> | OS | Install build tools |\r\n> |---|---|\r\n> | **Ubuntu/Debian** | `sudo apt-get install -y build-essential python3` |\r\n> | **macOS** | `xcode-select --install` |\r\n> | **Windows** | `npm install -g windows-build-tools` or install Visual Studio Build Tools |\r\n> | **Alpine** | `apk add build-base python3` |\r\n>\r\n> Data is stored locally at `~/.codesession/sessions.db`.\r\n\r\n## When to use\r\n\r\n- **Always** start a tracked session at the beginning of a multi-step task\r\n- **Always** log AI usage after each API call you make\r\n- **Always** end the session when the task is complete\r\n- Check budget before expensive operations\r\n- Use `cs dashboard` to review session data in a browser\r\n\r\n## Commands\r\n\r\n### Start tracking\r\n```bash\r\n# Agent mode (always use --json for structured output):\r\ncs start \"task description\" --json --close-stale\r\n\r\n# Resume if a session was left open (e.g. after a crash):\r\ncs start \"task description\" --json --resume\r\n\r\n# Human/interactive mode (stays running with live file watcher):\r\ncs start \"task description\"\r\n```\r\n\r\n> **Agent mode vs interactive mode:** With `--json`, the session is created in the database, JSON is printed, and the process exits immediately -- the session stays \"active\" and tracks git changes when you run `cs end`. Without `--json`, the process stays running with a live file watcher and git commit poller until you press Ctrl+C or run `cs end` in another terminal.\r\n\r\n### Log AI usage (after each API call)\r\n```bash\r\n# With granular tokens (cost auto-calculated from built-in pricing):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json\r\n\r\n# With agent name tracking (NEW in v1.9.1):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Code Review Bot\" --json\r\n\r\n# With manual cost:\r\ncs log-ai -p anthropic -m claude-opus-4-6 -t 15000 -c 0.30 --json\r\n\r\n# With all fields:\r\ncs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent \"Research Agent\" --json\r\n```\r\nProviders: `anthropic`, `openai`, `google`, `mistral`, `deepseek`\r\nCost is auto-calculated from a configurable pricing table (21+ built-in models including Codex). Use `cs pricing list --json` to see known models. If a model is unknown, provide `-c ` manually.\r\n\r\n**Agent Name (optional):** Use `--agent \"Agent Name\"` to track which agent performed the work. Perfect for multi-agent systems, A/B testing, and cost attribution. Agent names appear in the dashboard and can be used to filter/analyze costs per agent.\r\n\r\n### Check current status\r\n```bash\r\ncs status --json\r\n```\r\nReturns JSON with current session cost, tokens, files changed, duration. All JSON responses include `schemaVersion` and `codesessionVersion` fields.\r\n\r\n### End session and get summary\r\n```bash\r\ncs end -n \"completion notes\" --json\r\n```\r\nWhen ending, codesession automatically scans git for all files changed and commits made since the session started -- even if `--json` mode was used (no live watcher needed).\r\n\r\n### Web Dashboard\r\n```bash\r\ncs dashboard\r\n# Opens http://localhost:3737 with full analytics UI\r\n\r\ncs dashboard --port 4000 # custom port\r\ncs dashboard --no-open # don't auto-open browser\r\n```\r\n\r\nThe dashboard shows:\r\n- **Overview** ā€” KPIs, daily cost/token trends, spend projections, cost velocity\r\n- **Sessions** ā€” searchable/sortable table, per-session detail with timeline, files, commits, AI calls, notes\r\n- **Models** ā€” per-model & per-provider cost breakdown, token ratios, usage charts\r\n- **Insights** ā€” file hotspots, activity heatmap, project breakdown, pricing table\r\n- **Alerts** ā€” set daily/total/per-session cost thresholds with alarm mode (sound + browser notifications)\r\n- **Start Fresh** ā€” reset all session data from the sidebar\r\n\r\n### View session details\r\n```bash\r\ncs show --json --files --commits\r\n```\r\n\r\n### View historical stats\r\n```bash\r\ncs stats --json\r\n```\r\n\r\n### Export sessions\r\n```bash\r\ncs export --format json --limit 10\r\ncs export --format csv\r\n```\r\n\r\n### Add notes / annotations\r\n```bash\r\ncs note \"Starting refactor phase\"\r\ncs note \"Tests passing, moving to cleanup\"\r\n```\r\nTimestamped annotations appear in `cs show --json` under `annotations`.\r\n\r\n### Recover stale sessions\r\n```bash\r\ncs recover --max-age 12\r\n```\r\nAuto-ends any active sessions older than 12 hours.\r\n\r\n## Agent Workflow\r\n\r\nAgents should **always** use `--json` on every command for structured, parseable output.\r\n\r\n1. At task start: `cs start \"Fix authentication bug\" --json --close-stale`\r\n2. Add context notes: `cs note \"analyzing auth flow\" --json`\r\n3. After each AI call: `cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Bug Fixer\" --json`\r\n4. Check spend: `cs status --json` -- read `aiCost` field\r\n5. At task end: `cs end -n \"Fixed the auth bug, added tests\" --json`\r\n6. Review past sessions: `cs dashboard`\r\n\r\n**Tip:** Use the `--agent` flag to identify your agent's work, especially useful in multi-agent systems where different agents handle different tasks (e.g., \"Code Review Bot\", \"Test Writer\", \"Documentation Agent\").\r\n\r\n## Pricing\r\n\r\nPricing is configurable. Run `cs pricing list` to see all known model prices. Override or add models:\r\n\r\n```bash\r\n# Plain model key\r\ncs pricing set my-model 5.00 15.00\r\n\r\n# Provider-namespaced key (avoids collisions)\r\ncs pricing set gpt-4o 2.50 10.00 --provider openai\r\n```\r\n\r\nIf the model isn't in the pricing table, you must provide `-c ` when logging.\r\n\r\n## Proxy mode & cs run (v2.5.0)\r\n\r\nThe fastest way to track any agent run:\r\n\r\n```bash\r\ncs run python my_agent.py\r\n# or: cs run --name \"fix auth\" node agent.js\r\n```\r\n\r\nThis starts a session, launches the proxy, runs your command, then ends the session and prints a cost summary. No extra terminals, no env vars to export.\r\n\r\nIf you prefer manual control, start the proxy in one terminal and set env vars:\r\n\r\n```bash\r\ncs proxy --session \"my task\" # auto-starts a session too\r\n# then in your agent shell:\r\nexport ANTHROPIC_BASE_URL=http://127.0.0.1:3739\r\nexport OPENAI_BASE_URL=http://127.0.0.1:3739/v1\r\n```\r\n\r\nThe proxy binds to `127.0.0.1` only. It never stores prompt text or API keys ā€” only token counts are written to the session.\r\n\r\n## Budget awareness\r\n\r\nIf the user has set a budget or you detect high spending:\r\n- Check `cs status --json` before expensive operations\r\n- Warn the user if `aiCost` exceeds $5.00 in a single session\r\n- Suggest cheaper models if costs are escalating\r\n\r\n## Important\r\n\r\n- Use `--close-stale` on `cs start` to avoid \"session_active\" errors from prior crashes\r\n- If `cs` is not installed, skip session tracking ā€” don't block the user's task\r\n- **Always** use `--json` on every command ā€” agents must use structured output\r\n- With `--json`, `cs start` creates the session and exits (no long-running process needed)\r\n- Sessions are scoped by **git root** ā€” running from a subdirectory still matches the repo-level session\r\n- On errors in `--json` mode, exit code is always `1` and the response has `{ \"error\": { \"code\": \"...\", \"message\": \"...\" } }`\r\n- Check `schemaVersion` in JSON responses to detect breaking changes\r\n\r\n## Update check\r\n\r\nPeriodically check if the CLI is up to date (e.g. at session start or once per day):\r\n\r\n```bash\r\n# Compare installed version to latest on npm:\r\ncs --version # installed version\r\nnpm view codesession-cli version # latest on npm\r\n```\r\n\r\nIf the installed version is behind, notify the user:\r\n> \"codesession-cli update available: v1.9.4 -> v2.0.0. Run `npm install -g codesession-cli` to update.\"\r\n\r\nDon't block the workflow for an update ā€” just inform and continue.\r\n\r\n## JSON output\r\n\r\nAll commands support `--json` for machine-readable output. Use this when you need to parse session data programmatically.\n\nFile v2.5.1:_meta.json\n\n{\n \"ownerId\": \"kn756bc007k4jgde4rdmc008d580tqt4\",\n \"slug\": \"costhq\",\n \"version\": \"2.5.1\",\n \"publishedAt\": 1772894847227\n}\n\nFile v2.5.1:skill-card.md\n\n## Description:
\ncodesession (codesession-cli, code session, code-session) tracks AI agent session costs, tokens, file changes, and git commits across Claude Code, OpenClaw, Codex, GPT, Cursor, Windsurf, Cline, and other AI agents.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[brian-mwirigi](https://clawhub.ai/user/brian-mwirigi)
\n\n### License/Terms of Use:
\n\n\n## Use Case:
\nDevelopers and AI coding agents use this skill to track session costs, token usage, changed files, git commits, and notes while working across agent tools. It also guides agents toward structured JSON command output, budget checks, dashboard review, and session recovery.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The CLI records local session metadata including changed files, commits, notes, token counts, costs, and agent names.
\nMitigation: Use it only in repositories where this local tracking is acceptable, review stored session data before sharing exports, and back up data before using reset features.
\n\n\n## Reference(s):
\n- [Codesession ClawHub listing](https://clawhub.ai/brian-mwirigi/codesession)
\n- [codesession-cli homepage](https://github.com/brian-mwirigi/codesession-cli)
\n- [codesession-cli npm package](https://www.npmjs.com/package/codesession-cli)
\n- [codesession-cli changelog](https://github.com/brian-mwirigi/codesession-cli/blob/main/CHANGELOG.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [guidance, shell commands, configuration]
\n**Output Format:** [Markdown with bash command examples and JSON-oriented command guidance]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Commands normally use --json for machine-readable agent workflows.]
\n\n## Skill Version(s):
\n2.5.1 (source: release metadata and target metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v2.4.0: 2 files, 4059 bytes\n\nFiles: SKILL.md (8659b), _meta.json (125b)\n\nFile v2.4.0:SKILL.md\n\n---\r\nname: codesession\r\ndescription: codesession (codesession-cli, code session, code-session) ā€” Track AI agent session costs, tokens, file changes, and git commits. Works with Claude Code, OpenClaw, Codex, GPT, Cursor, Windsurf, Cline & any AI agent. Budget enforcement, auto-pricing, MCP server, web dashboard, alerts, insights. v2.4.0.\r\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/brian-mwirigi/codesession-cli\", \"requires\": {\"bins\": [\"cs\"]}, \"install\": [{\"id\": \"npm\", \"kind\": \"node\", \"package\": \"codesession-cli\", \"bins\": [\"cs\"], \"label\": \"Install codesession-cli (npm)\"}]}}\r\n---\r\n\r\n# Session Cost Tracking (codesession-cli)\r\n\r\nTrack agent session costs, file changes, and git commits. Enforces budget limits and provides detailed session analytics with a full web dashboard.\r\n\r\n**Latest: v2.4.0** - Codex pricing (`codex-mini-latest`, `gpt-5.1-codex-max`, `gpt-5.1-codex-mini`, `gpt-5.3-codex`), security fixes, stability improvements.\r\n\r\nšŸ“¦ [npm](https://www.npmjs.com/package/codesession-cli) ā€¢ ā­ [GitHub](https://github.com/brian-mwirigi/codesession-cli) ā€¢ šŸ“ [Changelog](https://github.com/brian-mwirigi/codesession-cli/blob/main/CHANGELOG.md)\r\n\r\n## Installation\r\n\r\n```bash\r\n# 1. Install the CLI globally from npm\r\nnpm install -g codesession-cli\r\n\r\n# 2. Install the OpenClaw skill\r\nclawhub install codesession\r\n```\r\n\r\nAfter installing, the `cs` command is available globally. The OpenClaw agent will automatically use it to track sessions.\r\n\r\n> **Requirements:** Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).\r\n>\r\n> | OS | Install build tools |\r\n> |---|---|\r\n> | **Ubuntu/Debian** | `sudo apt-get install -y build-essential python3` |\r\n> | **macOS** | `xcode-select --install` |\r\n> | **Windows** | `npm install -g windows-build-tools` or install Visual Studio Build Tools |\r\n> | **Alpine** | `apk add build-base python3` |\r\n>\r\n> Data is stored locally at `~/.codesession/sessions.db`.\r\n\r\n## When to use\r\n\r\n- **Always** start a tracked session at the beginning of a multi-step task\r\n- **Always** log AI usage after each API call you make\r\n- **Always** end the session when the task is complete\r\n- Check budget before expensive operations\r\n- Use `cs dashboard` to review session data in a browser\r\n\r\n## Commands\r\n\r\n### Start tracking\r\n```bash\r\n# Agent mode (always use --json for structured output):\r\ncs start \"task description\" --json --close-stale\r\n\r\n# Resume if a session was left open (e.g. after a crash):\r\ncs start \"task description\" --json --resume\r\n\r\n# Human/interactive mode (stays running with live file watcher):\r\ncs start \"task description\"\r\n```\r\n\r\n> **Agent mode vs interactive mode:** With `--json`, the session is created in the database, JSON is printed, and the process exits immediately -- the session stays \"active\" and tracks git changes when you run `cs end`. Without `--json`, the process stays running with a live file watcher and git commit poller until you press Ctrl+C or run `cs end` in another terminal.\r\n\r\n### Log AI usage (after each API call)\r\n```bash\r\n# With granular tokens (cost auto-calculated from built-in pricing):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json\r\n\r\n# With agent name tracking (NEW in v1.9.1):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Code Review Bot\" --json\r\n\r\n# With manual cost:\r\ncs log-ai -p anthropic -m claude-opus-4-6 -t 15000 -c 0.30 --json\r\n\r\n# With all fields:\r\ncs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent \"Research Agent\" --json\r\n```\r\nProviders: `anthropic`, `openai`, `google`, `mistral`, `deepseek`\r\nCost is auto-calculated from a configurable pricing table (21+ built-in models including Codex). Use `cs pricing list --json` to see known models. If a model is unknown, provide `-c ` manually.\r\n\r\n**Agent Name (optional):** Use `--agent \"Agent Name\"` to track which agent performed the work. Perfect for multi-agent systems, A/B testing, and cost attribution. Agent names appear in the dashboard and can be used to filter/analyze costs per agent.\r\n\r\n### Check current status\r\n```bash\r\ncs status --json\r\n```\r\nReturns JSON with current session cost, tokens, files changed, duration. All JSON responses include `schemaVersion` and `codesessionVersion` fields.\r\n\r\n### End session and get summary\r\n```bash\r\ncs end -n \"completion notes\" --json\r\n```\r\nWhen ending, codesession automatically scans git for all files changed and commits made since the session started -- even if `--json` mode was used (no live watcher needed).\r\n\r\n### Web Dashboard\r\n```bash\r\ncs dashboard\r\n# Opens http://localhost:3737 with full analytics UI\r\n\r\ncs dashboard --port 4000 # custom port\r\ncs dashboard --no-open # don't auto-open browser\r\n```\r\n\r\nThe dashboard shows:\r\n- **Overview** ā€” KPIs, daily cost/token trends, spend projections, cost velocity\r\n- **Sessions** ā€” searchable/sortable table, per-session detail with timeline, files, commits, AI calls, notes\r\n- **Models** ā€” per-model & per-provider cost breakdown, token ratios, usage charts\r\n- **Insights** ā€” file hotspots, activity heatmap, project breakdown, pricing table\r\n- **Alerts** ā€” set daily/total/per-session cost thresholds with alarm mode (sound + browser notifications)\r\n- **Start Fresh** ā€” reset all session data from the sidebar\r\n\r\n### View session details\r\n```bash\r\ncs show --json --files --commits\r\n```\r\n\r\n### View historical stats\r\n```bash\r\ncs stats --json\r\n```\r\n\r\n### Export sessions\r\n```bash\r\ncs export --format json --limit 10\r\ncs export --format csv\r\n```\r\n\r\n### Add notes / annotations\r\n```bash\r\ncs note \"Starting refactor phase\"\r\ncs note \"Tests passing, moving to cleanup\"\r\n```\r\nTimestamped annotations appear in `cs show --json` under `annotations`.\r\n\r\n### Recover stale sessions\r\n```bash\r\ncs recover --max-age 12\r\n```\r\nAuto-ends any active sessions older than 12 hours.\r\n\r\n## Agent Workflow\r\n\r\nAgents should **always** use `--json` on every command for structured, parseable output.\r\n\r\n1. At task start: `cs start \"Fix authentication bug\" --json --close-stale`\r\n2. Add context notes: `cs note \"analyzing auth flow\" --json`\r\n3. After each AI call: `cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Bug Fixer\" --json`\r\n4. Check spend: `cs status --json` -- read `aiCost` field\r\n5. At task end: `cs end -n \"Fixed the auth bug, added tests\" --json`\r\n6. Review past sessions: `cs dashboard`\r\n\r\n**Tip:** Use the `--agent` flag to identify your agent's work, especially useful in multi-agent systems where different agents handle different tasks (e.g., \"Code Review Bot\", \"Test Writer\", \"Documentation Agent\").\r\n\r\n## Pricing\r\n\r\nPricing is configurable. Run `cs pricing list` to see all known model prices. Override or add models:\r\n\r\n```bash\r\n# Plain model key\r\ncs pricing set my-model 5.00 15.00\r\n\r\n# Provider-namespaced key (avoids collisions)\r\ncs pricing set gpt-4o 2.50 10.00 --provider openai\r\n```\r\n\r\nIf the model isn't in the pricing table, you must provide `-c ` when logging.\r\n\r\n## Budget awareness\r\n\r\nIf the user has set a budget or you detect high spending:\r\n- Check `cs status --json` before expensive operations\r\n- Warn the user if `aiCost` exceeds $5.00 in a single session\r\n- Suggest cheaper models if costs are escalating\r\n\r\n## Important\r\n\r\n- Use `--close-stale` on `cs start` to avoid \"session_active\" errors from prior crashes\r\n- If `cs` is not installed, skip session tracking ā€” don't block the user's task\r\n- **Always** use `--json` on every command ā€” agents must use structured output\r\n- With `--json`, `cs start` creates the session and exits (no long-running process needed)\r\n- Sessions are scoped by **git root** ā€” running from a subdirectory still matches the repo-level session\r\n- On errors in `--json` mode, exit code is always `1` and the response has `{ \"error\": { \"code\": \"...\", \"message\": \"...\" } }`\r\n- Check `schemaVersion` in JSON responses to detect breaking changes\r\n\r\n## Update check\r\n\r\nPeriodically check if the CLI is up to date (e.g. at session start or once per day):\r\n\r\n```bash\r\n# Compare installed version to latest on npm:\r\ncs --version # installed version\r\nnpm view codesession-cli version # latest on npm\r\n```\r\n\r\nIf the installed version is behind, notify the user:\r\n> \"codesession-cli update available: v1.9.4 -> v2.0.0. Run `npm install -g codesession-cli` to update.\"\r\n\r\nDon't block the workflow for an update ā€” just inform and continue.\r\n\r\n## JSON output\r\n\r\nAll commands support `--json` for machine-readable output. Use this when you need to parse session data programmatically.\n\nFile v2.4.0:_meta.json\n\n{\n \"ownerId\": \"kn756bc007k4jgde4rdmc008d580tqt4\",\n \"slug\": \"costhq\",\n \"version\": \"2.4.0\",\n \"publishedAt\": 1772316807264\n}\n\nArchive v2.3.0: 2 files, 4020 bytes\n\nFiles: SKILL.md (8588b), _meta.json (125b)\n\nFile v2.3.0:SKILL.md\n\n---\r\nname: codesession\r\ndescription: codesession (codesession-cli, code session, code-session) ā€” Track AI agent session costs, tokens, file changes, and git commits. Works with Claude Code, OpenClaw, Codex, GPT, Cursor, Windsurf, Cline & any AI agent. Budget enforcement, auto-pricing, MCP server, web dashboard, alerts, insights. v2.3.0.\r\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/brian-mwirigi/codesession-cli\", \"requires\": {\"bins\": [\"cs\"]}, \"install\": [{\"id\": \"npm\", \"kind\": \"node\", \"package\": \"codesession-cli\", \"bins\": [\"cs\"], \"label\": \"Install codesession-cli (npm)\"}]}}\r\n---\r\n\r\n# Session Cost Tracking (codesession-cli)\r\n\r\nTrack agent session costs, file changes, and git commits. Enforces budget limits and provides detailed session analytics with a full web dashboard.\r\n\r\n**Latest: v2.2.0** - Claude Code MCP plugin, alerts dashboard, start fresh, insights page, alarm mode.\r\n\r\nšŸ“¦ [npm](https://www.npmjs.com/package/codesession-cli) ā€¢ ā­ [GitHub](https://github.com/brian-mwirigi/codesession-cli) ā€¢ šŸ“ [Changelog](https://github.com/brian-mwirigi/codesession-cli/blob/main/CHANGELOG.md)\r\n\r\n## Installation\r\n\r\n```bash\r\n# 1. Install the CLI globally from npm\r\nnpm install -g codesession-cli\r\n\r\n# 2. Install the OpenClaw skill\r\nclawhub install codesession\r\n```\r\n\r\nAfter installing, the `cs` command is available globally. The OpenClaw agent will automatically use it to track sessions.\r\n\r\n> **Requirements:** Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).\r\n>\r\n> | OS | Install build tools |\r\n> |---|---|\r\n> | **Ubuntu/Debian** | `sudo apt-get install -y build-essential python3` |\r\n> | **macOS** | `xcode-select --install` |\r\n> | **Windows** | `npm install -g windows-build-tools` or install Visual Studio Build Tools |\r\n> | **Alpine** | `apk add build-base python3` |\r\n>\r\n> Data is stored locally at `~/.codesession/sessions.db`.\r\n\r\n## When to use\r\n\r\n- **Always** start a tracked session at the beginning of a multi-step task\r\n- **Always** log AI usage after each API call you make\r\n- **Always** end the session when the task is complete\r\n- Check budget before expensive operations\r\n- Use `cs dashboard` to review session data in a browser\r\n\r\n## Commands\r\n\r\n### Start tracking\r\n```bash\r\n# Agent mode (always use --json for structured output):\r\ncs start \"task description\" --json --close-stale\r\n\r\n# Resume if a session was left open (e.g. after a crash):\r\ncs start \"task description\" --json --resume\r\n\r\n# Human/interactive mode (stays running with live file watcher):\r\ncs start \"task description\"\r\n```\r\n\r\n> **Agent mode vs interactive mode:** With `--json`, the session is created in the database, JSON is printed, and the process exits immediately -- the session stays \"active\" and tracks git changes when you run `cs end`. Without `--json`, the process stays running with a live file watcher and git commit poller until you press Ctrl+C or run `cs end` in another terminal.\r\n\r\n### Log AI usage (after each API call)\r\n```bash\r\n# With granular tokens (cost auto-calculated from built-in pricing):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json\r\n\r\n# With agent name tracking (NEW in v1.9.1):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Code Review Bot\" --json\r\n\r\n# With manual cost:\r\ncs log-ai -p anthropic -m claude-opus-4-6 -t 15000 -c 0.30 --json\r\n\r\n# With all fields:\r\ncs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent \"Research Agent\" --json\r\n```\r\nProviders: `anthropic`, `openai`, `google`, `mistral`, `deepseek`\r\nCost is auto-calculated from a configurable pricing table (17+ built-in models). Use `cs pricing list --json` to see known models. If a model is unknown, provide `-c ` manually.\r\n\r\n**Agent Name (optional):** Use `--agent \"Agent Name\"` to track which agent performed the work. Perfect for multi-agent systems, A/B testing, and cost attribution. Agent names appear in the dashboard and can be used to filter/analyze costs per agent.\r\n\r\n### Check current status\r\n```bash\r\ncs status --json\r\n```\r\nReturns JSON with current session cost, tokens, files changed, duration. All JSON responses include `schemaVersion` and `codesessionVersion` fields.\r\n\r\n### End session and get summary\r\n```bash\r\ncs end -n \"completion notes\" --json\r\n```\r\nWhen ending, codesession automatically scans git for all files changed and commits made since the session started -- even if `--json` mode was used (no live watcher needed).\r\n\r\n### Web Dashboard\r\n```bash\r\ncs dashboard\r\n# Opens http://localhost:3737 with full analytics UI\r\n\r\ncs dashboard --port 4000 # custom port\r\ncs dashboard --no-open # don't auto-open browser\r\n```\r\n\r\nThe dashboard shows:\r\n- **Overview** ā€” KPIs, daily cost/token trends, spend projections, cost velocity\r\n- **Sessions** ā€” searchable/sortable table, per-session detail with timeline, files, commits, AI calls, notes\r\n- **Models** ā€” per-model & per-provider cost breakdown, token ratios, usage charts\r\n- **Insights** ā€” file hotspots, activity heatmap, project breakdown, pricing table\r\n- **Alerts** ā€” set daily/total/per-session cost thresholds with alarm mode (sound + browser notifications)\r\n- **Start Fresh** ā€” reset all session data from the sidebar\r\n\r\n### View session details\r\n```bash\r\ncs show --json --files --commits\r\n```\r\n\r\n### View historical stats\r\n```bash\r\ncs stats --json\r\n```\r\n\r\n### Export sessions\r\n```bash\r\ncs export --format json --limit 10\r\ncs export --format csv\r\n```\r\n\r\n### Add notes / annotations\r\n```bash\r\ncs note \"Starting refactor phase\"\r\ncs note \"Tests passing, moving to cleanup\"\r\n```\r\nTimestamped annotations appear in `cs show --json` under `annotations`.\r\n\r\n### Recover stale sessions\r\n```bash\r\ncs recover --max-age 12\r\n```\r\nAuto-ends any active sessions older than 12 hours.\r\n\r\n## Agent Workflow\r\n\r\nAgents should **always** use `--json` on every command for structured, parseable output.\r\n\r\n1. At task start: `cs start \"Fix authentication bug\" --json --close-stale`\r\n2. Add context notes: `cs note \"analyzing auth flow\" --json`\r\n3. After each AI call: `cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Bug Fixer\" --json`\r\n4. Check spend: `cs status --json` -- read `aiCost` field\r\n5. At task end: `cs end -n \"Fixed the auth bug, added tests\" --json`\r\n6. Review past sessions: `cs dashboard`\r\n\r\n**Tip:** Use the `--agent` flag to identify your agent's work, especially useful in multi-agent systems where different agents handle different tasks (e.g., \"Code Review Bot\", \"Test Writer\", \"Documentation Agent\").\r\n\r\n## Pricing\r\n\r\nPricing is configurable. Run `cs pricing list` to see all known model prices. Override or add models:\r\n\r\n```bash\r\n# Plain model key\r\ncs pricing set my-model 5.00 15.00\r\n\r\n# Provider-namespaced key (avoids collisions)\r\ncs pricing set gpt-4o 2.50 10.00 --provider openai\r\n```\r\n\r\nIf the model isn't in the pricing table, you must provide `-c ` when logging.\r\n\r\n## Budget awareness\r\n\r\nIf the user has set a budget or you detect high spending:\r\n- Check `cs status --json` before expensive operations\r\n- Warn the user if `aiCost` exceeds $5.00 in a single session\r\n- Suggest cheaper models if costs are escalating\r\n\r\n## Important\r\n\r\n- Use `--close-stale` on `cs start` to avoid \"session_active\" errors from prior crashes\r\n- If `cs` is not installed, skip session tracking ā€” don't block the user's task\r\n- **Always** use `--json` on every command ā€” agents must use structured output\r\n- With `--json`, `cs start` creates the session and exits (no long-running process needed)\r\n- Sessions are scoped by **git root** ā€” running from a subdirectory still matches the repo-level session\r\n- On errors in `--json` mode, exit code is always `1` and the response has `{ \"error\": { \"code\": \"...\", \"message\": \"...\" } }`\r\n- Check `schemaVersion` in JSON responses to detect breaking changes\r\n\r\n## Update check\r\n\r\nPeriodically check if the CLI is up to date (e.g. at session start or once per day):\r\n\r\n```bash\r\n# Compare installed version to latest on npm:\r\ncs --version # installed version\r\nnpm view codesession-cli version # latest on npm\r\n```\r\n\r\nIf the installed version is behind, notify the user:\r\n> \"codesession-cli update available: v1.9.4 -> v2.0.0. Run `npm install -g codesession-cli` to update.\"\r\n\r\nDon't block the workflow for an update ā€” just inform and continue.\r\n\r\n## JSON output\r\n\r\nAll commands support `--json` for machine-readable output. Use this when you need to parse session data programmatically.\n\nFile v2.3.0:_meta.json\n\n{\n \"ownerId\": \"kn756bc007k4jgde4rdmc008d580tqt4\",\n \"slug\": \"costhq\",\n \"version\": \"2.3.0\",\n \"publishedAt\": 1772135588189\n}\n\nArchive v2.2.0: 2 files, 3925 bytes\n\nFiles: _meta.json (125b), SKILL.md (8479b)\n\nFile v2.2.0:SKILL.md\n\n---\r\nname: codesession\r\ndescription: Track agent session costs, file changes, and git commits with codesession-cli. Enforces budget limits and provides detailed session analytics with a web dashboard. v2.0.0 - Alerts dashboard, start fresh, insights page.\r\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/brian-mwirigi/codesession-cli\", \"requires\": {\"bins\": [\"cs\"]}, \"install\": [{\"id\": \"npm\", \"kind\": \"node\", \"package\": \"codesession-cli\", \"bins\": [\"cs\"], \"label\": \"Install codesession-cli (npm)\"}]}}\r\n---\r\n\r\n# Session Cost Tracking (codesession-cli)\r\n\r\nTrack agent session costs, file changes, and git commits. Enforces budget limits and provides detailed session analytics with a full web dashboard.\r\n\r\n**Latest: v2.0.0** - Alerts dashboard, start fresh, insights page, alarm mode.\r\n\r\nšŸ“¦ [npm](https://www.npmjs.com/package/codesession-cli) ā€¢ ā­ [GitHub](https://github.com/brian-mwirigi/codesession-cli) ā€¢ šŸ“ [Changelog](https://github.com/brian-mwirigi/codesession-cli/blob/main/CHANGELOG.md)\r\n\r\n## Installation\r\n\r\n```bash\r\n# 1. Install the CLI globally from npm\r\nnpm install -g codesession-cli\r\n\r\n# 2. Install the OpenClaw skill\r\nclawhub install codesession\r\n```\r\n\r\nAfter installing, the `cs` command is available globally. The OpenClaw agent will automatically use it to track sessions.\r\n\r\n> **Requirements:** Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).\r\n>\r\n> | OS | Install build tools |\r\n> |---|---|\r\n> | **Ubuntu/Debian** | `sudo apt-get install -y build-essential python3` |\r\n> | **macOS** | `xcode-select --install` |\r\n> | **Windows** | `npm install -g windows-build-tools` or install Visual Studio Build Tools |\r\n> | **Alpine** | `apk add build-base python3` |\r\n>\r\n> Data is stored locally at `~/.codesession/sessions.db`.\r\n\r\n## When to use\r\n\r\n- **Always** start a tracked session at the beginning of a multi-step task\r\n- **Always** log AI usage after each API call you make\r\n- **Always** end the session when the task is complete\r\n- Check budget before expensive operations\r\n- Use `cs dashboard` to review session data in a browser\r\n\r\n## Commands\r\n\r\n### Start tracking\r\n```bash\r\n# Agent mode (always use --json for structured output):\r\ncs start \"task description\" --json --close-stale\r\n\r\n# Resume if a session was left open (e.g. after a crash):\r\ncs start \"task description\" --json --resume\r\n\r\n# Human/interactive mode (stays running with live file watcher):\r\ncs start \"task description\"\r\n```\r\n\r\n> **Agent mode vs interactive mode:** With `--json`, the session is created in the database, JSON is printed, and the process exits immediately -- the session stays \"active\" and tracks git changes when you run `cs end`. Without `--json`, the process stays running with a live file watcher and git commit poller until you press Ctrl+C or run `cs end` in another terminal.\r\n\r\n### Log AI usage (after each API call)\r\n```bash\r\n# With granular tokens (cost auto-calculated from built-in pricing):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json\r\n\r\n# With agent name tracking (NEW in v1.9.1):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Code Review Bot\" --json\r\n\r\n# With manual cost:\r\ncs log-ai -p anthropic -m claude-opus-4-6 -t 15000 -c 0.30 --json\r\n\r\n# With all fields:\r\ncs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent \"Research Agent\" --json\r\n```\r\nProviders: `anthropic`, `openai`, `google`, `mistral`, `deepseek`\r\nCost is auto-calculated from a configurable pricing table (17+ built-in models). Use `cs pricing list --json` to see known models. If a model is unknown, provide `-c ` manually.\r\n\r\n**Agent Name (optional):** Use `--agent \"Agent Name\"` to track which agent performed the work. Perfect for multi-agent systems, A/B testing, and cost attribution. Agent names appear in the dashboard and can be used to filter/analyze costs per agent.\r\n\r\n### Check current status\r\n```bash\r\ncs status --json\r\n```\r\nReturns JSON with current session cost, tokens, files changed, duration. All JSON responses include `schemaVersion` and `codesessionVersion` fields.\r\n\r\n### End session and get summary\r\n```bash\r\ncs end -n \"completion notes\" --json\r\n```\r\nWhen ending, codesession automatically scans git for all files changed and commits made since the session started -- even if `--json` mode was used (no live watcher needed).\r\n\r\n### Web Dashboard\r\n```bash\r\ncs dashboard\r\n# Opens http://localhost:3737 with full analytics UI\r\n\r\ncs dashboard --port 4000 # custom port\r\ncs dashboard --no-open # don't auto-open browser\r\n```\r\n\r\nThe dashboard shows:\r\n- **Overview** ā€” KPIs, daily cost/token trends, spend projections, cost velocity\r\n- **Sessions** ā€” searchable/sortable table, per-session detail with timeline, files, commits, AI calls, notes\r\n- **Models** ā€” per-model & per-provider cost breakdown, token ratios, usage charts\r\n- **Insights** ā€” file hotspots, activity heatmap, project breakdown, pricing table\r\n- **Alerts** ā€” set daily/total/per-session cost thresholds with alarm mode (sound + browser notifications)\r\n- **Start Fresh** ā€” reset all session data from the sidebar\r\n\r\n### View session details\r\n```bash\r\ncs show --json --files --commits\r\n```\r\n\r\n### View historical stats\r\n```bash\r\ncs stats --json\r\n```\r\n\r\n### Export sessions\r\n```bash\r\ncs export --format json --limit 10\r\ncs export --format csv\r\n```\r\n\r\n### Add notes / annotations\r\n```bash\r\ncs note \"Starting refactor phase\"\r\ncs note \"Tests passing, moving to cleanup\"\r\n```\r\nTimestamped annotations appear in `cs show --json` under `annotations`.\r\n\r\n### Recover stale sessions\r\n```bash\r\ncs recover --max-age 12\r\n```\r\nAuto-ends any active sessions older than 12 hours.\r\n\r\n## Agent Workflow\r\n\r\nAgents should **always** use `--json` on every command for structured, parseable output.\r\n\r\n1. At task start: `cs start \"Fix authentication bug\" --json --close-stale`\r\n2. Add context notes: `cs note \"analyzing auth flow\" --json`\r\n3. After each AI call: `cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Bug Fixer\" --json`\r\n4. Check spend: `cs status --json` -- read `aiCost` field\r\n5. At task end: `cs end -n \"Fixed the auth bug, added tests\" --json`\r\n6. Review past sessions: `cs dashboard`\r\n\r\n**Tip:** Use the `--agent` flag to identify your agent's work, especially useful in multi-agent systems where different agents handle different tasks (e.g., \"Code Review Bot\", \"Test Writer\", \"Documentation Agent\").\r\n\r\n## Pricing\r\n\r\nPricing is configurable. Run `cs pricing list` to see all known model prices. Override or add models:\r\n\r\n```bash\r\n# Plain model key\r\ncs pricing set my-model 5.00 15.00\r\n\r\n# Provider-namespaced key (avoids collisions)\r\ncs pricing set gpt-4o 2.50 10.00 --provider openai\r\n```\r\n\r\nIf the model isn't in the pricing table, you must provide `-c ` when logging.\r\n\r\n## Budget awareness\r\n\r\nIf the user has set a budget or you detect high spending:\r\n- Check `cs status --json` before expensive operations\r\n- Warn the user if `aiCost` exceeds $5.00 in a single session\r\n- Suggest cheaper models if costs are escalating\r\n\r\n## Important\r\n\r\n- Use `--close-stale` on `cs start` to avoid \"session_active\" errors from prior crashes\r\n- If `cs` is not installed, skip session tracking ā€” don't block the user's task\r\n- **Always** use `--json` on every command ā€” agents must use structured output\r\n- With `--json`, `cs start` creates the session and exits (no long-running process needed)\r\n- Sessions are scoped by **git root** ā€” running from a subdirectory still matches the repo-level session\r\n- On errors in `--json` mode, exit code is always `1` and the response has `{ \"error\": { \"code\": \"...\", \"message\": \"...\" } }`\r\n- Check `schemaVersion` in JSON responses to detect breaking changes\r\n\r\n## Update check\r\n\r\nPeriodically check if the CLI is up to date (e.g. at session start or once per day):\r\n\r\n```bash\r\n# Compare installed version to latest on npm:\r\ncs --version # installed version\r\nnpm view codesession-cli version # latest on npm\r\n```\r\n\r\nIf the installed version is behind, notify the user:\r\n> \"codesession-cli update available: v1.9.4 -> v2.0.0. Run `npm install -g codesession-cli` to update.\"\r\n\r\nDon't block the workflow for an update ā€” just inform and continue.\r\n\r\n## JSON output\r\n\r\nAll commands support `--json` for machine-readable output. Use this when you need to parse session data programmatically.\n\nFile v2.2.0:_meta.json\n\n{\n \"ownerId\": \"kn756bc007k4jgde4rdmc008d580tqt4\",\n \"slug\": \"costhq\",\n \"version\": \"2.2.0\",\n \"publishedAt\": 1771341904261\n}\n\nArchive v2.1.0: 2 files, 3923 bytes\n\nFiles: _meta.json (125b), SKILL.md (8479b)\n\nFile v2.1.0:SKILL.md\n\n---\r\nname: codesession\r\ndescription: Track agent session costs, file changes, and git commits with codesession-cli. Enforces budget limits and provides detailed session analytics with a web dashboard. v2.0.0 - Alerts dashboard, start fresh, insights page.\r\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/brian-mwirigi/codesession-cli\", \"requires\": {\"bins\": [\"cs\"]}, \"install\": [{\"id\": \"npm\", \"kind\": \"node\", \"package\": \"codesession-cli\", \"bins\": [\"cs\"], \"label\": \"Install codesession-cli (npm)\"}]}}\r\n---\r\n\r\n# Session Cost Tracking (codesession-cli)\r\n\r\nTrack agent session costs, file changes, and git commits. Enforces budget limits and provides detailed session analytics with a full web dashboard.\r\n\r\n**Latest: v2.0.0** - Alerts dashboard, start fresh, insights page, alarm mode.\r\n\r\nšŸ“¦ [npm](https://www.npmjs.com/package/codesession-cli) ā€¢ ā­ [GitHub](https://github.com/brian-mwirigi/codesession-cli) ā€¢ šŸ“ [Changelog](https://github.com/brian-mwirigi/codesession-cli/blob/main/CHANGELOG.md)\r\n\r\n## Installation\r\n\r\n```bash\r\n# 1. Install the CLI globally from npm\r\nnpm install -g codesession-cli\r\n\r\n# 2. Install the OpenClaw skill\r\nclawhub install codesession\r\n```\r\n\r\nAfter installing, the `cs` command is available globally. The OpenClaw agent will automatically use it to track sessions.\r\n\r\n> **Requirements:** Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).\r\n>\r\n> | OS | Install build tools |\r\n> |---|---|\r\n> | **Ubuntu/Debian** | `sudo apt-get install -y build-essential python3` |\r\n> | **macOS** | `xcode-select --install` |\r\n> | **Windows** | `npm install -g windows-build-tools` or install Visual Studio Build Tools |\r\n> | **Alpine** | `apk add build-base python3` |\r\n>\r\n> Data is stored locally at `~/.codesession/sessions.db`.\r\n\r\n## When to use\r\n\r\n- **Always** start a tracked session at the beginning of a multi-step task\r\n- **Always** log AI usage after each API call you make\r\n- **Always** end the session when the task is complete\r\n- Check budget before expensive operations\r\n- Use `cs dashboard` to review session data in a browser\r\n\r\n## Commands\r\n\r\n### Start tracking\r\n```bash\r\n# Agent mode (always use --json for structured output):\r\ncs start \"task description\" --json --close-stale\r\n\r\n# Resume if a session was left open (e.g. after a crash):\r\ncs start \"task description\" --json --resume\r\n\r\n# Human/interactive mode (stays running with live file watcher):\r\ncs start \"task description\"\r\n```\r\n\r\n> **Agent mode vs interactive mode:** With `--json`, the session is created in the database, JSON is printed, and the process exits immediately -- the session stays \"active\" and tracks git changes when you run `cs end`. Without `--json`, the process stays running with a live file watcher and git commit poller until you press Ctrl+C or run `cs end` in another terminal.\r\n\r\n### Log AI usage (after each API call)\r\n```bash\r\n# With granular tokens (cost auto-calculated from built-in pricing):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json\r\n\r\n# With agent name tracking (NEW in v1.9.1):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Code Review Bot\" --json\r\n\r\n# With manual cost:\r\ncs log-ai -p anthropic -m claude-opus-4-6 -t 15000 -c 0.30 --json\r\n\r\n# With all fields:\r\ncs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent \"Research Agent\" --json\r\n```\r\nProviders: `anthropic`, `openai`, `google`, `mistral`, `deepseek`\r\nCost is auto-calculated from a configurable pricing table (17+ built-in models). Use `cs pricing list --json` to see known models. If a model is unknown, provide `-c ` manually.\r\n\r\n**Agent Name (optional):** Use `--agent \"Agent Name\"` to track which agent performed the work. Perfect for multi-agent systems, A/B testing, and cost attribution. Agent names appear in the dashboard and can be used to filter/analyze costs per agent.\r\n\r\n### Check current status\r\n```bash\r\ncs status --json\r\n```\r\nReturns JSON with current session cost, tokens, files changed, duration. All JSON responses include `schemaVersion` and `codesessionVersion` fields.\r\n\r\n### End session and get summary\r\n```bash\r\ncs end -n \"completion notes\" --json\r\n```\r\nWhen ending, codesession automatically scans git for all files changed and commits made since the session started -- even if `--json` mode was used (no live watcher needed).\r\n\r\n### Web Dashboard\r\n```bash\r\ncs dashboard\r\n# Opens http://localhost:3737 with full analytics UI\r\n\r\ncs dashboard --port 4000 # custom port\r\ncs dashboard --no-open # don't auto-open browser\r\n```\r\n\r\nThe dashboard shows:\r\n- **Overview** ā€” KPIs, daily cost/token trends, spend projections, cost velocity\r\n- **Sessions** ā€” searchable/sortable table, per-session detail with timeline, files, commits, AI calls, notes\r\n- **Models** ā€” per-model & per-provider cost breakdown, token ratios, usage charts\r\n- **Insights** ā€” file hotspots, activity heatmap, project breakdown, pricing table\r\n- **Alerts** ā€” set daily/total/per-session cost thresholds with alarm mode (sound + browser notifications)\r\n- **Start Fresh** ā€” reset all session data from the sidebar\r\n\r\n### View session details\r\n```bash\r\ncs show --json --files --commits\r\n```\r\n\r\n### View historical stats\r\n```bash\r\ncs stats --json\r\n```\r\n\r\n### Export sessions\r\n```bash\r\ncs export --format json --limit 10\r\ncs export --format csv\r\n```\r\n\r\n### Add notes / annotations\r\n```bash\r\ncs note \"Starting refactor phase\"\r\ncs note \"Tests passing, moving to cleanup\"\r\n```\r\nTimestamped annotations appear in `cs show --json` under `annotations`.\r\n\r\n### Recover stale sessions\r\n```bash\r\ncs recover --max-age 12\r\n```\r\nAuto-ends any active sessions older than 12 hours.\r\n\r\n## Agent Workflow\r\n\r\nAgents should **always** use `--json` on every command for structured, parseable output.\r\n\r\n1. At task start: `cs start \"Fix authentication bug\" --json --close-stale`\r\n2. Add context notes: `cs note \"analyzing auth flow\" --json`\r\n3. After each AI call: `cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Bug Fixer\" --json`\r\n4. Check spend: `cs status --json` -- read `aiCost` field\r\n5. At task end: `cs end -n \"Fixed the auth bug, added tests\" --json`\r\n6. Review past sessions: `cs dashboard`\r\n\r\n**Tip:** Use the `--agent` flag to identify your agent's work, especially useful in multi-agent systems where different agents handle different tasks (e.g., \"Code Review Bot\", \"Test Writer\", \"Documentation Agent\").\r\n\r\n## Pricing\r\n\r\nPricing is configurable. Run `cs pricing list` to see all known model prices. Override or add models:\r\n\r\n```bash\r\n# Plain model key\r\ncs pricing set my-model 5.00 15.00\r\n\r\n# Provider-namespaced key (avoids collisions)\r\ncs pricing set gpt-4o 2.50 10.00 --provider openai\r\n```\r\n\r\nIf the model isn't in the pricing table, you must provide `-c ` when logging.\r\n\r\n## Budget awareness\r\n\r\nIf the user has set a budget or you detect high spending:\r\n- Check `cs status --json` before expensive operations\r\n- Warn the user if `aiCost` exceeds $5.00 in a single session\r\n- Suggest cheaper models if costs are escalating\r\n\r\n## Important\r\n\r\n- Use `--close-stale` on `cs start` to avoid \"session_active\" errors from prior crashes\r\n- If `cs` is not installed, skip session tracking ā€” don't block the user's task\r\n- **Always** use `--json` on every command ā€” agents must use structured output\r\n- With `--json`, `cs start` creates the session and exits (no long-running process needed)\r\n- Sessions are scoped by **git root** ā€” running from a subdirectory still matches the repo-level session\r\n- On errors in `--json` mode, exit code is always `1` and the response has `{ \"error\": { \"code\": \"...\", \"message\": \"...\" } }`\r\n- Check `schemaVersion` in JSON responses to detect breaking changes\r\n\r\n## Update check\r\n\r\nPeriodically check if the CLI is up to date (e.g. at session start or once per day):\r\n\r\n```bash\r\n# Compare installed version to latest on npm:\r\ncs --version # installed version\r\nnpm view codesession-cli version # latest on npm\r\n```\r\n\r\nIf the installed version is behind, notify the user:\r\n> \"codesession-cli update available: v1.9.4 -> v2.0.0. Run `npm install -g codesession-cli` to update.\"\r\n\r\nDon't block the workflow for an update ā€” just inform and continue.\r\n\r\n## JSON output\r\n\r\nAll commands support `--json` for machine-readable output. Use this when you need to parse session data programmatically.\n\nFile v2.1.0:_meta.json\n\n{\n \"ownerId\": \"kn756bc007k4jgde4rdmc008d580tqt4\",\n \"slug\": \"costhq\",\n \"version\": \"2.1.0\",\n \"publishedAt\": 1771214969260\n}\n\nArchive v2.0.1: 2 files, 3923 bytes\n\nFiles: _meta.json (125b), SKILL.md (8479b)\n\nFile v2.0.1:SKILL.md\n\n---\r\nname: codesession\r\ndescription: Track agent session costs, file changes, and git commits with codesession-cli. Enforces budget limits and provides detailed session analytics with a web dashboard. v2.0.0 - Alerts dashboard, start fresh, insights page.\r\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/brian-mwirigi/codesession-cli\", \"requires\": {\"bins\": [\"cs\"]}, \"install\": [{\"id\": \"npm\", \"kind\": \"node\", \"package\": \"codesession-cli\", \"bins\": [\"cs\"], \"label\": \"Install codesession-cli (npm)\"}]}}\r\n---\r\n\r\n# Session Cost Tracking (codesession-cli)\r\n\r\nTrack agent session costs, file changes, and git commits. Enforces budget limits and provides detailed session analytics with a full web dashboard.\r\n\r\n**Latest: v2.0.0** - Alerts dashboard, start fresh, insights page, alarm mode.\r\n\r\nšŸ“¦ [npm](https://www.npmjs.com/package/codesession-cli) ā€¢ ā­ [GitHub](https://github.com/brian-mwirigi/codesession-cli) ā€¢ šŸ“ [Changelog](https://github.com/brian-mwirigi/codesession-cli/blob/main/CHANGELOG.md)\r\n\r\n## Installation\r\n\r\n```bash\r\n# 1. Install the CLI globally from npm\r\nnpm install -g codesession-cli\r\n\r\n# 2. Install the OpenClaw skill\r\nclawhub install codesession\r\n```\r\n\r\nAfter installing, the `cs` command is available globally. The OpenClaw agent will automatically use it to track sessions.\r\n\r\n> **Requirements:** Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).\r\n>\r\n> | OS | Install build tools |\r\n> |---|---|\r\n> | **Ubuntu/Debian** | `sudo apt-get install -y build-essential python3` |\r\n> | **macOS** | `xcode-select --install` |\r\n> | **Windows** | `npm install -g windows-build-tools` or install Visual Studio Build Tools |\r\n> | **Alpine** | `apk add build-base python3` |\r\n>\r\n> Data is stored locally at `~/.codesession/sessions.db`.\r\n\r\n## When to use\r\n\r\n- **Always** start a tracked session at the beginning of a multi-step task\r\n- **Always** log AI usage after each API call you make\r\n- **Always** end the session when the task is complete\r\n- Check budget before expensive operations\r\n- Use `cs dashboard` to review session data in a browser\r\n\r\n## Commands\r\n\r\n### Start tracking\r\n```bash\r\n# Agent mode (always use --json for structured output):\r\ncs start \"task description\" --json --close-stale\r\n\r\n# Resume if a session was left open (e.g. after a crash):\r\ncs start \"task description\" --json --resume\r\n\r\n# Human/interactive mode (stays running with live file watcher):\r\ncs start \"task description\"\r\n```\r\n\r\n> **Agent mode vs interactive mode:** With `--json`, the session is created in the database, JSON is printed, and the process exits immediately -- the session stays \"active\" and tracks git changes when you run `cs end`. Without `--json`, the process stays running with a live file watcher and git commit poller until you press Ctrl+C or run `cs end` in another terminal.\r\n\r\n### Log AI usage (after each API call)\r\n```bash\r\n# With granular tokens (cost auto-calculated from built-in pricing):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json\r\n\r\n# With agent name tracking (NEW in v1.9.1):\r\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Code Review Bot\" --json\r\n\r\n# With manual cost:\r\ncs log-ai -p anthropic -m claude-opus-4-6 -t 15000 -c 0.30 --json\r\n\r\n# With all fields:\r\ncs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent \"Research Agent\" --json\r\n```\r\nProviders: `anthropic`, `openai`, `google`, `mistral`, `deepseek`\r\nCost is auto-calculated from a configurable pricing table (17+ built-in models). Use `cs pricing list --json` to see known models. If a model is unknown, provide `-c ` manually.\r\n\r\n**Agent Name (optional):** Use `--agent \"Agent Name\"` to track which agent performed the work. Perfect for multi-agent systems, A/B testing, and cost attribution. Agent names appear in the dashboard and can be used to filter/analyze costs per agent.\r\n\r\n### Check current status\r\n```bash\r\ncs status --json\r\n```\r\nReturns JSON with current session cost, tokens, files changed, duration. All JSON responses include `schemaVersion` and `codesessionVersion` fields.\r\n\r\n### End session and get summary\r\n```bash\r\ncs end -n \"completion notes\" --json\r\n```\r\nWhen ending, codesession automatically scans git for all files changed and commits made since the session started -- even if `--json` mode was used (no live watcher needed).\r\n\r\n### Web Dashboard\r\n```bash\r\ncs dashboard\r\n# Opens http://localhost:3737 with full analytics UI\r\n\r\ncs dashboard --port 4000 # custom port\r\ncs dashboard --no-open # don't auto-open browser\r\n```\r\n\r\nThe dashboard shows:\r\n- **Overview** ā€” KPIs, daily cost/token trends, spend projections, cost velocity\r\n- **Sessions** ā€” searchable/sortable table, per-session detail with timeline, files, commits, AI calls, notes\r\n- **Models** ā€” per-model & per-provider cost breakdown, token ratios, usage charts\r\n- **Insights** ā€” file hotspots, activity heatmap, project breakdown, pricing table\r\n- **Alerts** ā€” set daily/total/per-session cost thresholds with alarm mode (sound + browser notifications)\r\n- **Start Fresh** ā€” reset all session data from the sidebar\r\n\r\n### View session details\r\n```bash\r\ncs show --json --files --commits\r\n```\r\n\r\n### View historical stats\r\n```bash\r\ncs stats --json\r\n```\r\n\r\n### Export sessions\r\n```bash\r\ncs export --format json --limit 10\r\ncs export --format csv\r\n```\r\n\r\n### Add notes / annotations\r\n```bash\r\ncs note \"Starting refactor phase\"\r\ncs note \"Tests passing, moving to cleanup\"\r\n```\r\nTimestamped annotations appear in `cs show --json` under `annotations`.\r\n\r\n### Recover stale sessions\r\n```bash\r\ncs recover --max-age 12\r\n```\r\nAuto-ends any active sessions older than 12 hours.\r\n\r\n## Agent Workflow\r\n\r\nAgents should **always** use `--json` on every command for structured, parseable output.\r\n\r\n1. At task start: `cs start \"Fix authentication bug\" --json --close-stale`\r\n2. Add context notes: `cs note \"analyzing auth flow\" --json`\r\n3. After each AI call: `cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --agent \"Bug Fixer\" --json`\r\n4. Check spend: `cs status --json` -- read `aiCost` field\r\n5. At task end: `cs end -n \"Fixed the auth bug, added tests\" --json`\r\n6. Review past sessions: `cs dashboard`\r\n\r\n**Tip:** Use the `--agent` flag to identify your agent's work, especially useful in multi-agent systems where different agents handle different tasks (e.g., \"Code Review Bot\", \"Test Writer\", \"Documentation Agent\").\r\n\r\n## Pricing\r\n\r\nPricing is configurable. Run `cs pricing list` to see all known model prices. Override or add models:\r\n\r\n```bash\r\n# Plain model key\r\ncs pricing set my-model 5.00 15.00\r\n\r\n# Provider-namespaced key (avoids collisions)\r\ncs pricing set gpt-4o 2.50 10.00 --provider openai\r\n```\r\n\r\nIf the model isn't in the pricing table, you must provide `-c ` when logging.\r\n\r\n## Budget awareness\r\n\r\nIf the user has set a budget or you detect high spending:\r\n- Check `cs status --json` before expensive operations\r\n- Warn the user if `aiCost` exceeds $5.00 in a single session\r\n- Suggest cheaper models if costs are escalating\r\n\r\n## Important\r\n\r\n- Use `--close-stale` on `cs start` to avoid \"session_active\" errors from prior crashes\r\n- If `cs` is not installed, skip session tracking ā€” don't block the user's task\r\n- **Always** use `--json` on every command ā€” agents must use structured output\r\n- With `--json`, `cs start` creates the session and exits (no long-running process needed)\r\n- Sessions are scoped by **git root** ā€” running from a subdirectory still matches the repo-level session\r\n- On errors in `--json` mode, exit code is always `1` and the response has `{ \"error\": { \"code\": \"...\", \"message\": \"...\" } }`\r\n- Check `schemaVersion` in JSON responses to detect breaking changes\r\n\r\n## Update check\r\n\r\nPeriodically check if the CLI is up to date (e.g. at session start or once per day):\r\n\r\n```bash\r\n# Compare installed version to latest on npm:\r\ncs --version # installed version\r\nnpm view codesession-cli version # latest on npm\r\n```\r\n\r\nIf the installed version is behind, notify the user:\r\n> \"codesession-cli update available: v1.9.4 -> v2.0.0. Run `npm install -g codesession-cli` to update.\"\r\n\r\nDon't block the workflow for an update ā€” just inform and continue.\r\n\r\n## JSON output\r\n\r\nAll commands support `--json` for machine-readable output. Use this when you need to parse session data programmatically.\n\nFile v2.0.1:_meta.json\n\n{\n \"ownerId\": \"kn756bc007k4jgde4rdmc008d580tqt4\",\n \"slug\": \"costhq\",\n \"version\": \"2.0.1\",\n \"publishedAt\": 1771172468873\n}","readmeExcerpt":"Skill: CostHQ Owner: brian-mwirigi Summary: Track agent session costs, file changes, and git commits with CostHQ. Enforces budget limits, tracks local models, and provides Enterprise SOC2 audit trails... Tags: latest:4.0.0 Version history: v4.0.0 | 2026-06-09T18:27:46.036Z | user - Added Semantic Caching Proxy to intercept and cache API calls, reducing repeated costs. - Introduced granular session termination via the","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# 1. Install the CLI globally from npm\nnpm install -g costhq\n\n# 2. Install the OpenClaw skill\nclawhub install costhq"},{"language":"bash","snippet":"# Agent mode (always use --json for structured output):\ncs start \"task description\" --json --close-stale\n\n# Resume if a session was left open (e.g. after a crash):\ncs start \"task description\" --json --resume"},{"language":"bash","snippet":"# Standard cloud model (cost auto-calculated):\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json\n\n# Local model with compute duration (NEW in v3.3.0):\n# Use --duration in seconds (120) or string (2m30s). Cost is based on registered $/hr rate.\ncs log-ai -p ollama -m llama3 --tokens 4500 --duration 2m30s --local --json\n\n# With all fields:\ncs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent \"Research Agent\" --json"},{"language":"bash","snippet":"cs status --json"},{"language":"bash","snippet":"cs end -n \"completion notes\" --json"},{"language":"bash","snippet":"cs dashboard"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: costhq\nlicense: MIT-0\ndescription: Track agent session costs, file changes, and git commits with CostHQ. Enforces budget limits, tracks local models, and provides Enterprise SOC2 audit trails via a web dashboard. v3.3.0 - Enterprise SOC2 Audit Logging and Local Models.\nmetadata: {\"openclaw\": {\"homepage\": \"https://github.com/brian-mwirigi/costhq\", \"requires\": {\"bins\": [\"cs\"]}, \"install\": [{\"id\": \"npm\", \"kind\": \"node\", \"package\": \"costhq\", \"bins\": [\"cs\"], \"label\": \"Install costhq (npm)\"}]}}\n---\n\n# Session Cost Tracking (CostHQ)\n\nTrack agent session costs, file changes, and git commits. Enforces budget limits, tracks local models (Ollama, vLLM), and provides detailed session analytics with a full web dashboard and tamper-evident SOC2 audit logging for Enterprise users.\n\n**Latest: v4.0.0** - Added Semantic Caching Proxy and Granular Session Termination.\n\nšŸ“¦ [npm](https://www.npmjs.com/package/costhq) ā€¢ ā­ [GitHub](https://github.com/brian-mwirigi/costhq) ā€¢ šŸ“ [Changelog](https://github.com/brian-mwirigi/costhq/blob/main/CHANGELOG.md)\n\n## Installation\n\n```bash\n# 1. Install the CLI globally from npm\nnpm install -g costhq\n\n# 2. Install the OpenClaw skill\nclawhub install costhq\n```\n\nAfter installing, the `cs` command is available globally. The OpenClaw agent will automatically use it to track sessions.\n\n> **Requirements:** Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).\n>\n> | OS | Install build tools |\n> |---|---|\n> | **Ubuntu/Debian** | `sudo apt-get install -y build-essential python3` |\n> | **macOS** | `xcode-select --install` |\n> | **Windows** | `npm install -g windows-build-tools` or install Visual Studio Build Tools |\n> | **Alpine** | `apk add build-base python3` |\n>\n> Data is stored locally at `~/.costhq/sessions.db` (or `~/.CostHQ`).\n\n## When to use\n\n- **Always** start a tracked session at the beginning of a multi-step task\n- **Always** log AI usage after each API call you make\n- **Always** end the session when the task is complete\n- Use `cs dashboard` to review session data, set up local models, or verify the audit trail (Enterprise).\n\n## Commands\n\n### Start tracking\n```bash\n# Agent mode (always use --json for structured output):\ncs start \"task description\" --json --close-stale\n\n# Resume if a session was left open (e.g. after a crash):\ncs start \"task description\" --json --resume\n```\n\n### Log AI usage (after each API call)\n```bash\n# Standard cloud model (cost auto-calculated):\ncs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json\n\n# Local model with compute duration (NEW in v3.3.0):\n# Use --duration in seconds (120) or string (2m30s). Cost is based on registered $/hr rate.\ncs log-ai -p ollama -m llama3 --tokens 4500 --duration 2m30s --local --json\n\n# With all fields:\ncs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent \"Research Agent\" --json\n```\n\n**Agent Name:** Use `--agent \"Agent Name\"` to track which agent performed the wo"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn756bc007k4jgde4rdmc008d580tqt4\",\n \"slug\": \"costhq\",\n \"version\": \"4.0.0\",\n \"publishedAt\": 1781029666036\n}"},{"path":"skill-card.md","content":"## Description:\n\nTrack agent session costs, file changes, and git commits with CostHQ, including budget limits, local model tracking, dashboard analytics, and Enterprise SOC2 audit trails.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[brian-mwirigi](https://clawhub.ai/user/brian-mwirigi)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and engineering teams use CostHQ to track agent task sessions, log AI usage costs, review file and commit activity, manage budgets, and inspect activity through a local dashboard.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: CostHQ can record agent activity, usage details, file changes, commits, and repository metadata.\n\nMitigation: Install only in repositories where this monitoring is acceptable, prefer a pinned reviewed npm package version, and review collected session data before using it for audit or reporting.\n\nRisk: The Semantic Caching Proxy intercepts API calls and may cache prompts or responses.\n\nMitigation: Avoid routing secrets, customer data, or regulated prompts through the proxy until retention, cache purge, and access-control behavior are clear.\n\nRisk: Dashboard command controls can affect active tracked sessions and execute CostHQ CLI operations.\n\nMitigation: Restrict dashboard access to trusted users and avoid running installation or CostHQ commands with elevated privileges unless required.\n\n## Reference(s):\n\n- [CostHQ ClawHub Listing](https://clawhub.ai/brian-mwirigi/skills/costhq)\n- [CostHQ GitHub Repository](https://github.com/brian-mwirigi/costhq)\n- [CostHQ npm Package](https://www.npmjs.com/package/costhq)\n- [CostHQ Changelog](https://github.com/brian-mwirigi/costhq/blob/main/CHANGELOG.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown with bash command examples and JSON-oriented CLI guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Commands are expected to use --json and may read or write local CostHQ session data.]\n\n## Skill Version(s):\n\n4.0.0 (source: server release metadata; artifact heading also states Latest v4.0.0)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Track agent session costs, file changes, and git commits with CostHQ. Enforces budget limits, tracks local models, and provides Enterprise SOC2 audit trails... Skill: CostHQ Owner: brian-mwirigi Summary: Track agent session costs, file changes, and git commits with CostHQ. Enforces budget limits, tracks local models, and provides Enterprise SOC2 audit trails... Tags: latest:4.0.0 Version history: v4.0.0 | 2026-06-09T18:27:46.036Z | user - Added Semantic Caching Proxy to intercept and cache API calls, reducing repeated costs. - Introduced granular session termination via the","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1287,"uniquenessScore":48,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T05:34:47.557Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T05:34:47.557Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T01:43:26.717Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | šŸŒŸ Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation ā€¢ (~400 MCP servers for AI agents) ā€¢ AI Automation / AI Agent with MCPs ā€¢ AI Workflows & AI Agents ā€¢ MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}