Skip to content
internal/cache
Updated Edit
On this page

Fetches Claude API usage data, caches responses with TTL and exponential backoff, and converts between API, cache, and display formats.

#internal/cache

#internal/cache

Package cache fetches the Claude usage windows from the platform API and stores them in a file cache with a TTL, error backoff and stale-data fallback, so a statusline render costs at most one network call per minute.

#CacheTTL

Go go
const CacheTTL         = 60 * time.Second

Cache TTL constants.

#ErrorCacheTTL

Go go
const ErrorCacheTTL    = 60 * time.Second

#MaxErrorCacheTTL

Go go
const MaxErrorCacheTTL = 5 * time.Minute

#CombinedTimeout

Go go
const CombinedTimeout  = 7 * time.Second

#ErrAuth

Go go
var ErrAuth = errors.New("authentication error (401/403)")

ErrAuth is returned when the usage API responds with 401 or 403.

#NowMs

Go go
var NowMs = func() int64 {

NowMs returns the current time in unix milliseconds. Exported for testing.

#UsageResponse

Go go
type UsageResponse struct

UsageResponse is the parsed JSON from the usage API.

#WindowUsage

Go go
type WindowUsage struct

WindowUsage represents a single usage window from the API.

#ExtraUsage

Go go
type ExtraUsage struct

ExtraUsage represents extra/overage usage from the API.

#CacheData

Go go
type CacheData struct

CacheData is persisted to .statusline-cache.json.

#CachedWindow

Go go
type CachedWindow struct

CachedWindow stores a usage window in the cache.

#CachedExtra

Go go
type CachedExtra struct

CachedExtra stores extra usage in the cache.

#UsageResult

Go go
type UsageResult struct

UsageResult is what GetUsageData returns to callers.

#WindowResult

Go go
type WindowResult struct

WindowResult represents a single usage window for display.

#ExtraResult

Go go
type ExtraResult struct

ExtraResult represents extra usage for display.

#FetchUsageFromAPI

Go go
func FetchUsageFromAPI(accessToken string) (*UsageResponse, error)

FetchUsageFromAPI calls the usage API with the given access token. Returns ErrAuth for 401/403, generic error for other failures.

#ReadCache

Go go
func ReadCache(claudeDir string) *CacheData

ReadCache reads the cache file from claudeDir. Returns nil on any error.

#WriteCache

Go go
func WriteCache(claudeDir string, data *CacheData) error

WriteCache atomically writes cache data to the cache file.

#IsCacheValid

Go go
func IsCacheValid(cache *CacheData, now int64, forceRefresh bool) bool

IsCacheValid determines whether the cached data can be used without refresh.

#GetUsageData

Go go
func GetUsageData(claudeDir string, forceRefresh bool) *UsageResult

GetUsageData is the main entry point: reads cache, fetches if needed, returns results.

#ParseWindowFromMap

Go go
func ParseWindowFromMap(m map[string]interface{}) (percent *float64, resetAtMs *int64)

ParseWindowFromMap extracts used_percentage and resets_at from a rate limit window map (five_hour or seven_day). Returns nil for either value if the key is missing or has the wrong type. resets_at is converted from unix seconds to unix milliseconds. Does NOT apply to extra_usage (different shape).

#WriteUsageFromStdin

Go go
func WriteUsageFromStdin(claudeDir string, rateLimits map[string]interface{}) error

WriteUsageFromStdin writes rate limit data from stdin directly to cache, bypassing the API. This is the "newer Claude Code" path where rate_limits are provided in the stdin JSON.

More tools from this site

  • claudestream Drive Claude Code from Python: run it as a subprocess and read its output as typed events, with async and sync sessions, sandbox policies, and tools you define in Python
  • claudewheel A TUI Claude Code Launcher that lets you have more than one profile, manage sessions lifecycle, pick the exact CC version, model to use (even older unlisted ones), pick which GitHub account to use, etc.
  • dirstat Fast, single-binary directory statistics CLI: every file under a tree grouped by format, with counts, sizes, and lines of code, as a colored terminal table or as JSON
  • fastware A batteries-included ASGI framework: msgspec JSON, a managed Granian server, dependency injection, SSE, WebSockets, auth, and a test client
  • go-toml-edit Zero-dep TOML editing library for Go with comment preservation
  • orxtra
  • pgdesign
  • predraw Declarative rendering pipeline: describe a scene in JSON and get SVG, PNG and WebP out, with light and dark style tokens, reusable components and text converted to path outlines
  • reposummary Turn a git repository's history into a Markdown journal: pick a time window or revision range and get a readable digest of what changed, optionally narrated by an LLM
  • rlsbl Release orchestration and project scaffolding CLI that bumps versions, validates a structured JSONL changelog, tags only the commit CI verified, and publishes to npm, PyPI, Go and more
  • safegit git wrapper CLI that gives each commit its own temporary index and retries ref updates on conflict, so concurrent agents share one repository
  • saferm Command-line replacement for rm that archives every deletion with a mandatory reason and the context it ran in, so deleted files can be listed, inspected and restored
  • selfdoc Static Site Generator that builds a project's documentation site directly from its source code, so the docs can never drift from the code they describe, with SEO/AEO, first-class blog, search, and cross-project linking built in
  • strictcli
  • stricttest An always-on test-isolation floor: a pytest plugin and a Go env-hygiene module that make a test suite structurally unable to reach real credentials, the real HOME, the network, or the development repository.
  • wesktop A Python framework that turns an ASGI web app into a desktop application, serving it from a local Granian server and displaying it in a native OS window via pywebview
Search