Halyard – open AI work ledger for developers (time, tokens, cost, invoices)

Uh oh!

There was an error while loading. Please reload this page.

Notifications You must be signed in to change notification settings

Fork 0

Star 1

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

328 Commits

328 Commits

.agents/skills

.agents/skills

.github

.github

assets/icons/halyard-nautical

assets/icons/halyard-nautical

docs

docs

openspec

openspec

pricing

pricing

prompts

prompts

samples

samples

src/halyard

src/halyard

tests

tests

vscode-extension

vscode-extension

.gitignore

.gitignore

.mcp.json

.mcp.json

AGENTS.md

AGENTS.md

CHANGELOG.md

CHANGELOG.md

CLAUDE.md

CLAUDE.md

CODE_OF_CONDUCT.md

CODE_OF_CONDUCT.md

CONTRIBUTING.md

CONTRIBUTING.md

LICENSE

LICENSE

README.md

README.md

SECURITY.md

SECURITY.md

pyproject.toml

pyproject.toml

uv.lock

uv.lock

Repository files navigation

A halyard is the line that raises the sails. Pull on it, the sails go up. Pull on this one, your AI work comes into focus.

Your AI work leaves a trail. Halyard makes that trail legible, auditable, and client-safe.

Every AI session — time, tokens, model, cost, project — captured where the work happens, stored as plain text on your machine, owned by you. No account. No cloud service. No prompt or code capture. Ever. MIT licensed.

Status: alpha, open source — capture loop, reports, invoices, The Bridge, and TUI in daily use.

What it looks like

CLI report

The Bridge — local dashboard

The problem

You're doing AI-assisted work. At the end of a sprint, a month, or a client engagement, you can't answer three basic questions:

What did AI actually cost on this project?

What did AI help produce — and can you prove it?

Is your AI spend going in the right direction?

Your tools don't record this. Halyard does.

It runs as lightweight hooks inside Claude Code, Cursor, and Gemini CLI, with manual/editor-task capture for tools like VS Code where no public AI-session hook exists. Every session writes one line to a plain-text log you own. From that log: cost breakdowns, project attribution, invoice evidence, and eventually a signed, verifiable AI work appendix you can hand to a client.

The privacy promise is unconditional: Halyard captures session metadata, never prompt content, code context, file contents, or transcripts.

Who it is for

Individual developers and freelancers — your primary audience right now. Your time, your AI spend, and your invoice evidence live as plain text on your laptop. Halyard helps you prove what happened without exposing prompts or code. Git it, back it up, sync it however you want. No account. No SaaS. No proprietary format.

Small AI shops — share the same local ledger format across a team. Project spend, trust-labeled cost allocation, and client-safe appendices built from individual plain-text logs.

Enterprise — the same format will support governance, cost centers, and cross-tool AI Work Intelligence later. That layer is additive, gated on design-partner pull, and will not change what local files mean.

How it works

Halyard has three layers:

Collection — Lightweight hooks that run where AI work happens. Claude Code, Cursor, Windsurf, and Gemini CLI hooks capture sessions automatically; a VS Code extension captures editing time, branch, and code delta — token counts unavailable until VS Code/Copilot exposes a public session hook. Since v3.5, Claude Code sessions are tagged with an advisory client surface (cli / desktop / ide) detected from the local environment. Captured fields include time, tokens when available, model, cost, project, and branch. Written to a plain-text log you own. New sessions are appended, and the current hardening track is making corrections explicit and auditable. Nothing is lost silently.

Intelligence — Analytics built on that log. Local CLI reports, cost-by-project breakdowns, per-model spend, budget alerts, and trust-labeled totals (captured vs. calculated vs. allocated). Works offline, no account required.

AI Work Ledger — Cost allocation for seat subscriptions and credit plans. If you pay $200/month for Claude Max, Halyard allocates that cost across your projects proportionally — by active minutes, session count, or credit usage — so you know what each client engagement actually costs. Runs on top of ai-sessions.log and ai-plans.toml; nothing is written back to the raw log.

Proof Artifacts — Invoice evidence today, and a signed attestable AI work appendix next. The goal is a client-safe artifact that proves AI-assisted work without showing prompts, transcripts, source code, or file contents.

The Bridge — A local dashboard for watching capture happen in real time. Run halyard dashboard inside any Halyard project.

Rich Session Telemetry — Where tools expose it, Halyard captures operational metadata beyond cost: tool call counts, error rates, wall time vs. active agent time, code delta, and per-model breakdowns. Gemini CLI sessions include full multi-model breakdowns from the history file. These signals surface in the TUI and The Bridge as work-health indicators — not productivity scores, but honest signals of session shape.

Honors — A service record that rewards clean proof, not raw hours. Ranks advance on attributed sessions (Deckhand → Commodore), stripes track your watch streak, and eight medals recognize behaviors that matter: completing your first watch, keeping a clean manifest, rescuing adrift sessions, and more. Run halyard honors to see your record.

Friends of the Sea — One sea creature per completed project, auto-assigned by personality. Projects move through nautical voyage stages (Anchors Aweigh → Making Headway → Rounding the Mark → Flying Colors → Shipshape · Moored) as sessions accumulate. Auto-completes on target hit or inactivity. Run halyard voyage to see the roster. Your Captain's Quarters on The Bridge shows a Passport — one stamp per AI tool you've used.

For technical readers

Halyard is a Python 3.11+ local-first CLI and dashboard, not a hosted billing service. The halyard command is a Typer app, reports use Rich, the terminal dashboard uses Textual, and The Bridge is a small 127.0.0.1 HTTP server. The durable data model is plain text in the project folder; SQLite is only a rebuildable read-model cache for faster queries.

The capture pipeline is intentionally simple:

AI tool hook/importer/manual command -> normalized AiSession object -> append-focused ai-sessions.log line -> reports, ledger allocation, dashboard, invoice evidence

So: is Halyard "just looking at logs"? Not exactly. It uses the best public signal each tool exposes:

Claude Code: installs UserPromptSubmit and Stop hooks. The start hook records session start time and git SHA. The stop hook reads the structured hook payload; for newer Claude Code formats it can also aggregate token/model metadata from the local transcript JSONL path passed by the hook.

Cursor: installs beforeSubmitPrompt and stop hooks. It reads the stop payload and prefers workspace_roots for attribution because that is the actual editor workspace, not necessarily the shell CWD.

Gemini CLI: installs SessionStart, AfterModel, and AfterAgent hooks. AfterModel accumulates token usage from usageMetadata; AfterAgent finalizes the session. It integrates deeply with OpenTelemetry (OTLP) to measure exact API and tool-execution durations (api_seconds, tool_seconds) and enriches from Gemini's local history file for accurate multi-model token breakdowns, tool-call counts, and deterministic cost.

Codex Desktop: imports local ~/.codex/sessions/.../rollout-*.jsonl files, extracts timing/model/token metadata, and records imported session IDs so repeated imports do not duplicate entries.

VS Code / GitHub Copilot: a local VS Code extension (vscode-extension/) tracks active editing time, captures branch and code-delta via git, and writes sessions through halyard record-session. Install the extension from a local .vsix build; no public Copilot session hook exists yet so token counts are not available.

Every collector writes the same normalized record shape: timestamps, tool, model, tokens when available, cache tokens, cost, billing type, project, branch, capture source, and attribution provenance. Halyard does not store prompts, source code, file contents, or full transcripts in ai-sessions.log. When a collector temporarily reads a local transcript or history file, it is only to extract session metadata.

The log is append-focused. Session records are s ... lines; corrections are separate amendment records keyed by a hash of the original line. Writers hold an exclusive OS-level file lock (fcntl.flock on POSIX, msvcrt.locking on Windows) so concurrent hooks do not interleave writes. Malformed records are quarantined instead of crashing report generation.

Cost handling is explicit about trust. Direct API usage can be captured or calculated from tokens and the local pricing table. Seat or credit plans are allocated at report time from ai-plans.toml by active minutes, session count, or credits. Reports label the result as captured, calculated, allocated, inferred, mixed, or unallocated so client-facing evidence does not pretend an estimate is a measurement.

Quickstart

Platform: macOS, Linux, and Windows. The halyard service install command is macOS-only; other platforms can run halyard dashboard in a long-lived terminal instead.

The 3-Minute Start

pipx install halyard cd ~/businesses/my-freelance halyard init

Guided setup installs supported hooks and checks readiness:

halyard setup

Verify your hooks and first capture:

halyard doctor --first-capture

Open the dashboard

halyard dashboard

Daily Workflow

Start your human timer (AI sessions are auto-captured in the background)

halyard start acme/auth-migration

... do work ...

halyard stop

Terminal UI

halyard tui

Ask in natural language — two ways, both read-only:

halyard log "what did I spend this month?" # from the CLI (local by

default; --agent claude|openai optional)

…or via your coding agent through the MCP server (see below)

Generate an invoice with an AI usage evidence appendix

halyard invoice acme --month 2026-05 --include-ai-evidence

View Full Command Reference

Stats-forward analytics — sessions, streaks, peak hour, model mix

halyard usage --range 30d halyard usage --range 7d --json # machine-readable

--json on report/usage/budget/status/evidence/health/doctor for CI + scripts

halyard report --all --json | jq '.totals.cost_usd' halyard budget --json | jq '.[] | select(.month.state=="over")' # spend gate

Install the background launchd service (macOS):

halyard service install

Ask your agent about your own AI work (read-only MCP server):

pipx inject halyard mcp # add the MCP extra to the pipx install halyard mcp # stdio MCP server for Claude Code / Cursor

Install hooks manually:

halyard install-hook # Claude Code halyard install-cursor-hook # Cursor halyard install-gemini-hook # Gemini CLI halyard install-vscode-tasks # VS Code manual capture task

Record VS Code/Copilot work manually

halyard record-session --tool vscode --model github-copilot --minutes 15 --note "Copilot chat"

Retroactive Gemini import

halyard import-gemini

Budget limits

halyard set-budget acme --daily 10.00 --monthly 200.00

AI Work Ledger — allocate seat/credit plan costs by project

halyard report --ledger

Confirm inferred project attribution from timeclock overlap

halyard confirm-attribution

Keep pricing table fresh

halyard update-pricing

Service record & Project voyage roster

halyard honors halyard voyage

See docs/demo.md for a full walkthrough — self-guided and live presentation script in one document. If capture does not show up, start with docs/troubleshooting.md.

MCP server (ask your agent about your AI wo

[truncated for AI cost control]