assaio：面向 Claude Code、Codex CLI 等工具的离线 AI 编码用量与成本分析 Go CLI

See how AI coding tools are used, compare estimated costs and inspect local delivery evidence.

assaio is an open-source, offline-first Go CLI (assaio-agent) with embedded SQLite for Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, Cline and Antigravity CLI. Platform and engineering teams can inspect observed usage breadth, API-equivalent cost estimates and bounded local PR, review and CI observations. Antigravity contributes activity only, excluded from token and cost figures. assaio collects no prompts, responses or code and never ranks people. Optional self-hosted team mode pools usage; delivery evidence remains on the invoking clone.

assaio website · Roadmap · Shipped features · Documentation · Privacy model

Use vendor dashboards for plan limits and vendor administration. assaio gives a local view across vendors for these questions:

• Which tools and projects appear in observed sessions, and on how many active days?
• What are the API-equivalent cost estimates for Claude Code, Codex, Gemini CLI, Copilot CLI and Cline?
• Where do logs record edits, rework or failed tool calls?
• What PR, review and CI evidence is available around candidate commits in this clone?
• How complete is each figure, and which source could not supply it?

Adoption describes observed sessions, active days and tool/project breadth, not the percentage of all employees using AI. The local evidence command reports session→commit candidates with confidence, ambiguity, abstention and population coverage. Optional --github adds bounded PR, review snapshots, raw review dismissals, latest-head checks and historical suite/run observations through your own gh. Dismissals retain actual event times, nullable review joins and separate source coverage; they leave current snapshots and matching unchanged. These are facts about PRs, not proof of AI productivity or session outcomes. See the source study. Exact review rounds, comparable PR pipeline CI rates, authoritative squash-versus-rebase methods and PR revert relations remain outside the shipped scope. See the roadmap.

Who assaio is for

assaio is for platform teams, engineering-enablement groups and individual developers that:

• need to understand observed AI usage across tools and projects
• want estimated costs on a common basis, with unpriced usage visible
• need local PR, review and CI evidence before choosing what to investigate
• want an inspectable baseline with clear sources and missing-data handling
• want to test an improvement without making telemetry an employee leaderboard

assaio is not a fit for live quota bars, prompt replay, a general LLM observability backend or a production-ready multi-tenant service. Use vendor tools for quota data. assaio does not extract or store prompt or response bodies. The team server is an MVP.

Install assaio-agent

assaio-agent is one Go binary with embedded SQLite. Prebuilt releases support macOS, Linux and Windows on amd64 and arm64.

Homebrew:

brew install assaio/tap/assaio-agent

With Go 1.26 or newer:

go install github.com/assaio/assaio/cmd/assaio-agent@latest

Or download an archive from GitHub Releases. Releases include checksums, an SPDX SBOM and build-provenance attestations. See RELEASING.md to verify them.

First run

Preview assaio without reading your logs:

$ assaio-agent demo

Then run the guided import:

$ assaio-agent init

init shows which local logs it will read and which configured parser plugins it will run, imports their history and writes the first report. assaio itself sends nothing over the network; a parser plugin from your config is your own program (see PRIVACY.md).

The usual loop is short:

$ assaio-agent dashboard --since 30d --output assay.html
$ assaio-agent evidence --repo . --since 30d
$ assaio-agent evidence --repo . --since 30d --github
$ assaio-agent digest --weekly --dry-run
$ assaio-agent doctor --strict

• dashboard creates a self-contained offline HTML report.
• evidence compares local sessions with local commit observations without storing an edge; optional --github uses your own gh to read bounded PR, review, latest-head check and separate historical suite/run observations. Only PRs named by candidates or alternatives get details.
• digest reports what changed since the previous run and whether the comparison is sound.
• doctor reports source coverage, format drift, store health and unpriced usage.

For automation or a narrower question, use report, effectiveness, analyze, recommend, reprice, reconcile, check and signals. The generated command reference is authoritative; the README omits the full flag list.

What assaio measures

Every metric includes source coverage, sample size, freshness and parser version. If a source lacks a field, assaio excludes it from the denominator rather than counting it as zero. For an exec parser plugin, omitted token counters are still stored as 0 (B212). A missing model price appears as —/null, not $0.

Run:

$ assaio-agent signals coverage

to see what your data supports. FEATURES.md lists shipped features; docs/corrections.md records published figures later found to be wrong.

evidence observes attribution; it is not an outcome metric. It joins a repository's commits only with sessions whose rows resolved to that repository, uses bounded time proximity, labels results matched, ambiguous or unmatched, and shows competing commits. A match does not show that the session caused the commit. With --github, independent bounded repository reads add PR and review snapshots, latest-head checks and historical suites/runs on currently listed commits. Details appear only for PRs named by candidates or alternatives. Counts expose missing and truncated layers; null means unavailable, while an explicit empty connection means known empty. Reviewed-revision counts require complete usable review populations. A request-change snapshot share uses the entire named merged PR population, including alternatives, as its denominator and is withheld unless every PR has a nonempty complete usable review population. Exact rounds and comparable PR pipeline CI rates are withheld. Merge topology can prove a multi-parent merge, but one parent cannot distinguish squash from rebase. Observations stay local and in memory for one command; offline evidence stays unchanged. See how to read the result.

Supported AI coding tools

assaio reads existing local logs from these tools:

The source-depth matrix lists each field and its source. Vendor log formats can change. Tests, calibration checks and doctor show format drift but cannot prevent it.

Costs are API-equivalent estimates from a vendored LiteLLM price snapshot, not vendor invoices or reconstructed subscription quota use. Since v0.29.0, when LiteLLM stops listing a model, assaio keeps the last price LiteLLM published for it; the vendor may no longer offer that rate, and doctor counts such models. reconcile compares a downloaded export with the local estimate and shows any unexplained remainder.

Privacy: local and offline

On its normal offline analysis path, assaio:

• makes no network request and has no telemetry; evidence --github asks GitHub for pull requests through your own gh only when you run it;
• does not extract or store prompt text, response text or repository file contents;
• reads commit hashes, times and content-free change counts only when evidence or survival runs, and stores none of them;
• stores token counts, model names, timestamps, pseudonymous identity and content-free activity counts in local SQLite;
• pseudonymizes project and member names by default in dashboard and share output; team sync transmits Project, Subpath and session ID to the server;
• refuses per-person leaderboards for output, spend and productivity.

Line activity comes from counts and diff markers; code on those lines is not stored. See PRIVACY.md for the exact fields, retention and deletion commands.

Team mode

serve and sync can pool usage on infrastructure you operate. Sync v2 sends a keyed member digest and usage records to the team server; project, subpath and session ID also reach it. Each writer needs a distinct bearer token. Existing central stores require an offline migration and backup; see the team-server guide. Team mode is a tested MVP, not a production-ready service.

It has authentication, request bounds and an aggregated usage dashboard for observed adoption and estimated costs. PR/review/CI evidence is absent from sync and the server. It still needs RBAC, token rotation, resumable sync, retention controls, a backup/restore drill and a measured operating envelope. The roadmap lists these gates.

Extension points

Executables in any language can add a parser, metric or check rule. Each protocol has a handshake, a versioned JSON contract and boundary validation. Parser and metric plugins have a verify command; a rule plugin is checked by running check. The core does not import plugin internals.

Start with docs/extending.md. The binary can also export the full machine-readable reference:

$ assaio-agent docs export

The in-process Go packages stay under internal/ until the public contracts freeze.

Project status

The local CLI is suitable for evaluation and design-partner pilots. At the v0.26 audit, the project had an 86% statement-coverage snapshot. It has cross-platform CI, race tests, native parser fuzzers, vulnerability scanning and a published correction record.

It remains pre-1.0 because:

1. GitHub delivery evidence is bounded and local: exact review rounds, comparable PR pipeline CI histories and rates, authoritative squash-versus-rebase methods and trustworthy PR revert relations still need more source evidence and conformance cases; causal AI outcomes are not derived;
2. the contracts and calibration have not been tested across several external teams and release cycles.

The roadmap sets the evidence needed for v1.0. BACKLOG.md lists candidate work, not a schedule.

Collaboration

For a design partnership, pilot or consulting on measuring AI-assisted engineering, email contact@assaio.dev or use the contact form.

Contributing and security

Read CONTRIBUTING.md before opening a PR. Each change needs one Conventional Commit, DCO sign-off, and passing make fmt, make lint and make test. Parser changes must also pass make fuzz.

Report vulnerabilities privately through GitHub Security Advisories, not a public issue. See SECURITY.md.

License

Apache-2.0; see LICENSE. The embedded LiteLLM pricing snapshot is MIT-licensed; see NOTICE for attribution.