openshard 0.4.8

Receipts for AI coding agents.

Use Claude Code, Codex, Cursor, OpenCode, Google Antigravity, Hermes Agent, Grok Build or Grok Bot normally. Openshard keeps a clear record of what happened: what ran, what changed, what was verified, what it cost, and what it could not establish.

Agents write code. Openshard keeps the receipt.

Docs · Changelog · Contributing · Security

See Openshard in action

Getting your first receipt takes a couple of commands:

pip install openshard
cd my-project
openshard setup

Now use your coding agent (Claude Code, Codex, Cursor, OpenCode, Google Antigravity or Grok Build; Hermes Agent and Grok Bot need one extra step, see Supported coding agents) as you normally would. When the agent finishes:

openshard last

Openshard records the available evidence from the run and turns it into a receipt you can inspect locally.

your coding agent
       ↓
does the work
       ↓
Openshard captures the available evidence
       ↓
receipt

You keep your existing coding workflow and Openshard gives that work a record.

What does a receipt tell you?

A receipt is the saved record of an AI coding run.

Depending on what the agent and its integration expose, Openshard can record the task, coding agent, model, inspected files, file changes, checks, estimated token usage and cost, actions taken during the run, capture completeness, result state, and integrity information.

Each new receipt also has a globally unique receipt_id, while the existing shard_id remains available for compatibility with local repo history.

The important part is not simply collecting more fields. It is being clear about what Openshard actually knows.

Why receipts?

AI coding agents have long moved past autocomplete and now carry out significant work in real production workflows. They inspect repositories, edit files, run commands, execute tests, call tools, and increasingly work on tasks that previously belonged entirely to developers.

Git gives us a durable history of code changes, but it does not always tell us what happened during the AI work around those changes. Which agent handled the task? Which model was used? What did the agent report changing? Which checks actually ran? What failed? What did the run cost? Was any evidence missed? Can we still trust the record we are looking at later?

Openshard exists to preserve that context. The coding agent still does the coding and Openshard keeps the receipt.

Openshard doesn't guess

Receipts stop being useful if uncertain information is presented as fact.

Openshard is deliberately conservative about what it claims. If the model is unknown, it says unknown. If cost was not captured, it says not recorded. If part of a session was missed, the receipt records a partial capture.

The same principle applies to code changes. A working tree might already contain human edits, another agent might be active at the same time, or Git might show that a file changed without providing enough evidence to establish who caused it.

Openshard therefore separates files an agent reported changing from changes that were only observed by Git, pre-existing changes, and changes associated with another recorded session. If Openshard cannot establish the actor, it says so.

A finished agent turn is also not automatically treated as proof that the code is correct. An agent can finish successfully while its work remains unverified, so Openshard can report the turn as Turn completed (unverified).

The aim is simple: record the evidence that exists without filling the gaps with guesses.

Receipt identity and integrity

Every new receipt receives a globally unique receipt_id when it is created.

Unlike the existing repo-local shard_id, the receipt ID is designed to remain unique across repositories, machines, developers, and organisations.

Receipts can also carry a content fingerprint. Openshard can use that fingerprint to check whether the stored record still matches the content from which it was produced.

This is an integrity check on the receipt itself. It is not a claim that the underlying code is correct.

Supported coding agents

Openshard currently captures receipts from:

All of them can contribute to the same local Openshard history in a repo. You can move between supported agents without creating separate receipt stores or changing the way you normally use those tools.

Run:

openshard doctor

to see which integrations are configured and what Openshard can currently capture.

Getting around your receipt history

The basic workflow is intentionally small.

See the most recent receipt:

openshard last

See more detail:

openshard last --more
openshard last --full

Browse recent AI coding work in the repo:

openshard history

See repo-level statistics:

openshard stats

Check the installation and agent integrations:

openshard doctor

The main receipt commands also support JSON, which makes them useful in scripts and other tooling:

openshard last --json
openshard history --json
openshard stats --json

How capture works

openshard setup detects whatever supported coding agents are available for the repo and configures their supported integration points.

The implementation differs slightly between agents. Openshard can use hooks, plugins, local configuration, and MCP-based integration depending on what each tool exposes. Those events are normalised into the same receipt history and passed through a local authenticated capture service.

That means every supported agent can leave receipts in the same repo history even though the agents themselves work differently.

For the deeper implementation details, see Agent capture.

Local-first

The open-source receipt layer is local-first. Your receipt history stays with the repo and can be inspected offline.

You do not need a hosted Openshard account to create or inspect local receipts.

Raw developer content is not sent to Openshard by default. Basic privacy-safe product telemetry may be collected after setup, such as versions, counts, timings, and error categories. It does not include code, prompts, file names, or receipt contents.

Telemetry can be disabled at any time:

openshard telemetry off

See Telemetry for the full behaviour.

Optional hosted sync

Receipts stay local by default. If you want them visible beyond your own machine, openshard sync sends copies of this repository's Receipts to an Openshard Platform organisation:

openshard sync connect --endpoint <url> --org <org-id>
openshard sync now
openshard sync status

Sync is off until you run connect, sends only the same bounded fields openshard history --json already prints (no prompts, transcripts, diffs, or file contents), and is retry-safe and idempotent: replaying sync now never duplicates a Receipt. See Platform sync for the full contract.

The hosted dashboard that reads this synced history is still being built; see Project status below.

Installation

The standard installation is:

pip install openshard

Then move into a Git repo and run:

cd your-project
openshard setup

pipx and uv are also supported:

pipx install openshard

uv tool install openshard

To upgrade later:

pip install -U openshard

or:

pipx upgrade openshard

See Installation for additional installation guidance.

Project status

Openshard is currently a working tool available for use, and the core local receipt loop is working across Claude Code, Codex, Cursor, OpenCode, Google Antigravity, Hermes Agent and Grok Build, with Grok Bot captured through Cursor's OpenTelemetry export or a self-report skill.

The project has automated CI, Ruff and mypy checks, a large pytest suite, Linux and Windows validation, authenticated local capture, receipt integrity checks, explicit capture-completeness handling, and real integration testing across supported agent paths.

Sending Receipts to the Openshard Platform is live and retry-safe (openshard sync), and that local-to-hosted path has passed real end-to-end testing. What's still being built on top of it is the hosted web experience: the dashboard, receipt history views, and team controls. They'll build on the same receipt primitive rather than replacing the local workflow.

For now, the focus is straightforward: making the receipt layer reliable, useful, and easy enough to fit naturally into the way developers already work.

Why open source?

We believe that evidence infrastructure should be inspectable.

If Openshard says a coding agent changed a file, a check passed, a session was incomplete, or an actor could not be established, developers should be able to understand how that conclusion was reached.

Keeping the local receipt layer open source makes the capture model, integrations, and integrity behaviour available for inspection and improvement.

Openshard is licensed under Apache-2.0.

Documentation

• Installation
• Agent capture
• What is a Receipt?
• Platform sync
• CLI reference
• Telemetry
• Changelog
• Security
• Contributing

Contributing

Contributions are welcome across receipt capture, coding-agent integrations, provenance, verification, CLI experience, platform compatibility, security, tests, documentation, and examples.

See CONTRIBUTING.md to get started.

Security

If you find a security issue, please report it privately before opening a public issue.

See SECURITY.md.

License

Apache-2.0