Welcome to Crystil!

Cost Visibility for AI Agents

Crystil is a lightweight infrastructure layer that gives AI teams real-time visibility into the true costs of deploying agents - across tasks, workflows, and customers. Most teams today can’t see what it actually costs to deploy their agents, making it nearly impossible to manage gross margins or price with confidence.

With just a single line of code, Crystil delivers:

  • Cost tracking across OpenAI, Anthropic, Gemini, and more in one place
  • Breakdowns by task, agent, and customer in real time
  • Confidence to deploy the right pricing model (cost-plus, token-based, outcome-based, etc.) while preserving gross margins

Watch a short demo video: Crystil Walkthrough Video

By surfacing exactly what’s driving cost and value, Crystil becomes the source of truth for agent economics - helping founders and operators scale their agents with confidence.

Sign up here: crystil.com

Installation

gem install crystil

Documentation

Our SDK reference provides documentation for:

  • Understanding how Crystil works
  • Demonstrating how to integrate Crystil into your product
  • Code samples to illustrate our SDK and API

Check it out here: developers.crystil.com

Releasing a New Version

Publishing is automated. Pushing a GitHub Release triggers publish-to-rubygems.yaml, which builds the gem and pushes it to RubyGems via Trusted Publishing (OIDC). There is no API key stored in GitHub, and you should never run gem push or rake release by hand — the release's safety checks only exist in CI, and a version number can never be reused on RubyGems once taken.

To release version X.Y.Z:

  1. Update the version number in lib/crystil/version.rb:

    VERSION = "X.Y.Z"

    This constant is the single source of truth — the gemspec and the meta.sdk.version field on every payload both read from it.

  2. Update the CHANGELOG in CHANGELOG.md:

    • Add a new section for the version with today's date
    • Document all changes under appropriate categories (Added, Changed, Fixed, etc.)
    • Follow the Keep a Changelog format

  3. Open a PR and merge it to main once CI is green (lint, type-check, and the Ruby 3.2 / 3.3 / 3.4 test matrix).

  4. Publish a GitHub Release tagged vX.Y.Z — the leading v is required, and the rest must match Crystil::VERSION exactly or the workflow fails. There is no separate git tag step: the release creates the tag against --target, and pushing a tag on its own triggers nothing.

    gh release create vX.Y.Z --target main --title "vX.Y.Z" \
  --notes "$(sed -n '/^## \[X.Y.Z\]/,/^## \[/p' CHANGELOG.md | sed '$d')"

    Pass the notes explicitly as above (or --generate-notes for an auto-generated commit summary). Don't use --notes-from-tag here — when gh creates the tag it is lightweight, so that flag falls back to the commit message and your notes end up reading "Merge pull request #NN".

    Or use the GitHub UI: Releases → Draft a new release, create the tag vX.Y.Z against main, then Publish release. Saving a draft does not trigger anything; only publishing does.

  5. Watch the run:

    gh run watch

    Before pushing anything, the workflow verifies the tag matches the version, runs the unit and mocked integration specs, and asserts the packaged gem contains what it should. It then waits for the new version to be installable rather than merely uploaded, so a green run means the release is live.

  6. Verify the release:

One-time publishing setup

The workflow authenticates via RubyGems Trusted Publishing, which must be configured once before the first release.

Because crystil is not yet on RubyGems, create a pending publisher at rubygems.org/profile/oidc/pending_trusted_publishers (for a gem that already exists, use Trusted publishers in the gem's sidebar instead):

Field Value
RubyGem name crystil
Repository owner CrystilAI
Repository name ruby-sdk
Workflow filename publish-to-rubygems.yaml
Environment rubygems

Then create a matching GitHub environment named rubygems under Settings → Environments — optionally with required reviewers, which turns every release into an approval gate.

All five values are part of the trusted identity. Renaming the workflow file or the environment breaks publishing until RubyGems is updated to match. After the first successful push, the pending publisher converts to a normal one and the configuring user becomes a gem owner.