CostHQ v4.0.0: Semantic Caching & Granular Controls

CostHQ v4 brings major upgrades to how you track and save on AI agent costs!

What's New

• Semantic Caching Proxy: Stop paying for duplicate API calls! Run the local proxy (cs proxy start --port 3739) or toggle it directly from the new dashboard Overview. Any identical AI requests routed through the proxy are instantly served from the cache for $0.00.
• Granular Session Termination: The Command Center now lists all individual running sessions. You can selectively terminate a specific background session without halting your other active projects.
• Fully Unlocked Free Tier: We've completely eliminated the "Pro Trial" lockouts. The base version of CostHQ is now 100% free with no hidden timers or trial expirations!

🔧 Fixes & Improvements

• Fixed an API routing bug when toggling the proxy from the dashboard.
• Resolved a UI crash in the Command Center when attempting to map over an empty session list.
• Updated the OpenClaw SKILL.md to properly document the new caching proxy and granular termination features.
• The GitHub Action now automatically spins up the Semantic Caching Proxy in CI environments to save you money on automated agent tests.

GitHub Action Usage

Use this action in your CI/CD pipelines to enforce AI budgets and catch rogue loops before they drain your API credits:

- uses: brian-mwirigi/CostHQ@v4.0.0
  with:
    max_cost: '5.00'

v3.0.2

What's New in v3.0.0 (The Pro Unlock)

We've completely overhauled the UI, added new sharing tools, and unlocked the entire Pro architecture for free!

Highlights

• Shareable Stats Card — A beautiful, Spotify-Wrapped style component to export a PNG image of your coding and AI usage stats.
• In-App Feedback — Built-in feedback modal allowing you to report bugs or request features directly from the dashboard.
• Onboarding Wizard — First-time user overlay walkthrough for CLI commands and dashboard capabilities.
• Pro Features Unlocked — The entire Pro tier architecture (including Alerts, Share Cards, and Insights) is now completely free and unlocked by default.

Performance & Fixes

• Massive Performance Boosts — SQLite performance indexes added, simple-git instances are now cached.
• React Stability — Hardened network requests across the dashboard to prevent silent crash errors.
• Dependency Bloat — puppeteer was removed from production dependencies making npm installs instantly faster and avoiding 400MB Chromium downloads.

v2.6.0

What's New in v2.6.0

Biggest structural update yet — the codebase went from a 1200-line monolith to a proper modular architecture, and we shipped cs today on top of it.

Major Refactor

• index.ts went from 1216 lines to ~50. db.ts (903 lines) split into 5 focused modules
• 30 �s any casts replaced with 16 typed DB row interfaces
• collectPullRequests converted from a 15-second sync block to async
• TypeScript target bumped to ES2022. 53 tests across 5 suites

New Features

• *\cs today* — open your terminal and instantly see where you left off across all your projects: git state, failing tests, open PRs, TODOs, and what your last session cost. --share\ for markdown, --json\ for data, --ai\ outputs a context block optimized for pasting into Claude/Cursor/ChatGPT
• Dashboard Changelog tab — browse full release history right in the web UI
• Dashboard Help tab — CLI command reference at a glance
• Dashboard Pricing tab — view and manage model pricing from the browser
• Programmatic agent API —
  unAgentSession, \AgentSession, \BudgetExceededError\
• Codex (o3, o4-mini) pricing added

Fixes

• Reset button fixed (was silently returning 400)
• Negative \limit\ could bypass query cap — now clamped
• \promptTokens: 0\ and \duration: 0\ no longer silently dropped
• Shell-safe browser launch, query param clamping
• \CHANGELOG.md\ now included in npm package (Changelog tab works for installed users)

Install / Update

\\�ash
npm install -g codesession-cli
\\

Full Changelog

v2.5.1 — Dashboard Help Tab, Bug Fixes, Architecture Improvements

What's New

Dashboard

• Help tab — full CLI command reference and MCP tools right in the web UI
• Pricing tab — view and manage model pricing from the dashboard
• Donate tab — support links

Commands

• \cs today\ — pick up where you left off: git state, TODOs, PRs, session history across all projects
• Programmatic agent API — \
  unAgentSession\, \AgentSession\, \BudgetExceededError\ for custom agent frameworks

Architecture

• Split monolithic \index.ts\ (1216 lines) into \src/commands/\ modules
• Split \db.ts\ (903 lines) into \src/db/\ with 5 focused modules
• 16 typed DB row interfaces replace ~30 \�s any\ casts
• 53 Vitest tests across 5 suites

Bug Fixes

• Reset button in dashboard no longer 400s (missing \?confirm=true\)
• \/help\ page no longer 404s on browser refresh
• Negative \limit\ query params can't bypass row caps
• \promptTokens: 0\ no longer silently dropped
• \duration: 0\ no longer treated as null
• Token estimation fix for explicit prompt/completion split
• File change deduplication
• 21 \catch (e: any)\ → \catch (e: unknown)\ with typed helper
• Async watcher cleanup properly handled
• Shell-safe browser launch
• Dead imports cleaned up

Docs

• README refreshed with all dashboard tabs
• Comprehensive CHANGELOG entry
• CONTRIBUTING project structure updated
• SKILL.md and marketplace.json updated

Full Changelog: https://github.com/brian-mwirigi/codesession-cli/blob/main/CHANGELOG.md

v2.5.0 - cs run, proxy --session, UX overhaul

What's New

cs run - one command does everything

cs run python my_agent.py

Starts session, launches proxy, runs your command, prints cost summary on exit.

cs proxy --session "name" - skip the separate cs start

cs proxy --session "fix auth bug"

Starts the proxy and creates a session in one step.

Smarter proxy output

• Shows the active session name on startup
• Auto-detects Windows vs Unix env var syntax
• Warns when no session is active

Security fix

• Upstream response buffer capped at 10 MB in non-streaming mode

README rewrite

• Agent/MCP skill install as the primary hero
• Full docs: https://www.brianmunene.me/docs/codesession-cli-docs
• Cut from 765 to 295 lines

Upgrading

npm install -g codesession-cli@latest

v2.4.0 — Codex Pricing, Security Fixes & Community Files

What's New in v2.4.0

Added

• Codex model pricing — codex-mini-latest, gpt-5.1-codex-max, gpt-5.1-codex-mini, gpt-5.3-codex added to auto-pricing table
• Community health files: Code of Conduct, Contributing guide, Security policy, issue templates, PR template
• GitHub Actions workflow for automated publish on future releases

Fixed

• Shell injection vulnerability in dashboard server process management
• /api/reset endpoint now requires ?confirm=true to prevent accidental data wipes
• Input validation on log-ai command (negative tokens, infinite cost, oversized strings)
• File watcher crash on filesystem errors (missing error handler)
• Git polling race condition causing duplicate commit entries
• Git operations now have a 15s timeout to prevent hangs on slow filesystems

Changed

• Bumped to v2.4.0

v2.3.0 — Pricing Tab, Claude Code Plugin & Marketplace

What's New in v2.3.0

Pricing Tab

Full model pricing management in the web dashboard:

• View all default prices grouped by provider (Anthropic, OpenAI, Google, DeepSeek)
• Inline edit: click Edit → change $/M token rates → Save
• Add custom models with your own rates
• Reset individual models to defaults
• Changes persist in ~/.codesession/pricing.json

Claude Code Plugin

Install codesession as a Claude Code plugin:
```

In Claude Code settings → Extensions → Install from GitHub

brian-mwirigi/codesession-cli
```
Includes slash commands: `/codesession:status`, `/codesession:budget`, `/codesession:dashboard`

Marketplace Listing

Now listed on claudemarketplaces.com — searchable by the Claude community.

Extended Model Pricing

Added GPT-5, GPT-5 mini, GPT-5-codex, GPT-5.1-codex, GPT-5.2-codex to the default pricing table.

Bug Fixes

• Fixed demo seed script to use real git hashes (proper diff display in dashboard)
• Fixed hardcoded development path in seed script

Install / Upgrade

```bash
npm install -g codesession-cli
cs --version # 2.3.0
```

v2.2.0 — Claude Code MCP Server

Claude Code Integration via MCP

codesession now ships as a Model Context Protocol (MCP) server, letting Claude Code (and any MCP client) track sessions, log costs, and check budgets — all in context.

Setup (one command)

claude mcp add --transport stdio codesession -- npx codesession-cli mcp

8 Tools Available

Tool	Description
session_status	Get active session status (cost, tokens, duration)
start_session	Start a new tracking session
end_session	End session and get full summary
log_ai_usage	Log token usage with auto-pricing
add_note	Add timestamped notes
get_stats	Overall statistics across all sessions
list_sessions	List recent sessions
check_budget	Check spending breakdown by model

1 Resource

• codesession://pricing — Current model pricing table

Other Changes

• New codesession-mcp binary for direct invocation
• /donate SPA route added to dashboard
• Study guide added for codebase contributors

v2.1.0 - Parallel Sessions, Donate Page, Auto-Log Fixes

What's New

Parallel Session Support

• cs start now succeeds when another session is active in a different directory/git root
• Same-directory sessions still blocked (use --resume or --close-stale)
• All commands (end, log-ai, status, note, auto-log) resolve the correct session based on your current working directory
• Enables multi-agent workflows where each sub-agent tracks costs independently per worktree

Donate Page

• New "Donate" tab in the dashboard with GitHub Sponsors and Buy Me a Coffee links
• GitHub repo now shows Sponsor button (FUNDING.yml)
• npm fund codesession-cli shows sponsor link

Auto-Log Bug Fixes

• Fixed token loss when no active session (position was saved before session check)
• Fixed TTY hang when cs auto-log run without piped input
• Position only saved after successful log
• Position file corruption and transcript truncation recovery

Sponsor Links

• GitHub Sponsors + Buy Me a Coffee badges in README

Full Changelog: https://github.com/brian-mwirigi/codesession-cli/blob/main/CHANGELOG.md

v2.0.0 - Alerts, Insights, Auto-Log & Donate

What's New in v2.0.0

Alerts Dashboard

• Dedicated Alerts page with spend threshold monitoring
• Set daily, total, and per-session cost limits with visual progress bars
• ON/OFF toggle per rule with status dots (green/red/gray)
• Alarm mode: browser notifications + Web Audio sound when budgets are exceeded
• Sessions over limit table

Insights Dashboard

• New analytics page with file hotspots, activity heatmap, project breakdown, and pricing table

Start Fresh

• Reset all session data from the dashboard with one click
• "Start Fresh" button in sidebar with confirmation modal
• POST /api/reset endpoint for programmatic reset

Auto-Log for Claude Code Hooks

• cs auto-log command reads Claude Code hook transcripts and automatically logs token usage
• Position-based de-duplication prevents double-counting across Stop events
• Tokens only saved after successful log (prevents token loss)
• TTY detection prevents hanging when run without piped input
• BOM stripping, position corruption recovery, transcript truncation handling

Donate Page

• Dashboard donate tab with GitHub Sponsors and Buy Me a Coffee links
• GitHub repo Sponsor button via FUNDING.yml
• npm funding field

Claude Code Integration

• Full integration guide at docs/integrations/claude-code.md
• 3-hook automatic setup: SessionStart, Stop, SessionEnd

Bug Fixes

• AudioContext autoplay policy fix for silent alarms
• Web Audio scheduling fix for reliable alarm sound
• Alarms no longer fire on page load with existing exceeded thresholds
• Null reference fix in Alerts when threshold changes before data load
• Active session cleanup on reset (stops watchers/pollers before delete)

Full Changelog: https://github.com/brian-mwirigi/codesession-cli/blob/main/CHANGELOG.md