> Halyard Launches Open-Source AI Work Ledger for Developers Tracking Time, Tokens, and Costs

Halyard dropped on GitHub this week as a new open-source project tackling a problem more developers are bumping into: AI-assisted work leaves zero trace in your billing stack. The tool runs lightweight hooks inside Claude Code, Cursor, Gemini CLI, and Codex Desktop to capture session metadata—time, tokens, model, cost, project attribution, git branch—and writes everything to plain-text logs you own. No account required. No cloud service. MIT licensed.

The Core Problem Halyard Addresses

If you're billing clients or managing a team budget, three questions get uncomfortable fast: what did AI actually cost on this project? What did it help produce—and can you prove it? Is your spend going in the right direction? Your existing tools don't record any of that. Halyard does. It captures per-session data including input/output tokens, cache read/write metrics, billing model (API vs seat vs credits), and capture source—whether from an automatic hook or manual entry. The log format is append-focused with correction records for auditability, and writers use OS-level file locking so concurrent hooks don't mangle entries.

Privacy-First by Design

Here's what Halyard explicitly does NOT capture: prompt content, code context, file contents, or full transcripts. The privacy promise is unconditional, according to the project docs. When a collector temporarily reads local transcript files (like Claude Code's JSONL path), it's only extracting session metadata—timestamps, token counts, model identifiers—not the actual prompts or responses. This matters for client-facing work where you'd want to prove AI was used without handing over your intellectual property or conversational context. The project calls this an "AI Work Ledger" approach: cost allocation for seat subscriptions and credit plans so you know what each client engagement actually costs rather than lumping it into general overhead.

Collector Coverage and Integrations

Currently shipped collectors target Claude Code (stop hook), Cursor (beforeSubmitPrompt/stop hooks), Gemini CLI (SessionStart/AfterModel/AfterAgent hooks with history file enrichment for multi-model breakdowns), and Codex Desktop (JSONL session importer reading local rollout files). VS Code/GitHub Copilot support is manual capture via a VS Code extension that tracks active editing time, branch, and code delta—token counts aren't available there because no public Copilot session hook exists yet. Windsurf integration is marked TBD. The MCP server component lets you query your ledger in natural language from within coding agents like Claude Code or Cursor: "how much did I spend this week?" becomes a legitimate question you can ask your own tools without leaving context.

Technical Architecture

Halyard runs on Python 3.11+ as a Typer CLI app with Rich for terminal reports and Textual for the TUI interface. The Bridge is a local HTTP dashboard served at 127.0.0.1 so nothing leaves your machine. Durable data lives in plain-text files—ai-sessions.log for session events, ai-plans.toml for seat/credit definitions, time.timeclock for hledger-compatible human time tracking. SQLite only appears as a rebuildable read-model cache for faster queries; it's not the source of truth. The project uses OpenSpec for spec-driven development with changeset IDs tracking design history rather than traditional release versions. Current PyPI package is 0.x (alpha).

Who Should Care

Individual developers and freelancers dealing with AI-assisted billing get immediate value—prove what happened without exposing prompts or code to clients. Small AI shops can share the local ledger format across teams for project spend visibility and trust-labeled cost allocation. Enterprise governance layers are described as additive, gated on design-partner pull, and won't change what local files mean. The quickstart is straightforward: pipx install halyard, cd into your project directory, run halyard init and halyard setup to auto-register hooks with detected AI tools, then verify capture with halyard doctor --first-capture before opening the dashboard.

The Bottom Line

Halyard fills a gap that's been gnawing at freelance developers and small shops trying to justify AI costs to clients: how do you prove value without revealing your secret sauce? By capturing metadata only—never prompts or code—the tool makes auditable proof artifacts possible while keeping your work private. Local-first, MIT licensed, no account required—this is how open-source tooling should approach sensitive developer workflows. If you're doing serious AI-assisted client work and can't answer "what did this actually cost?" with confidence, Halyard deserves a look.