Droid Data Source (Experimental)

Droid support is experimental. Expect breaking changes while both ccusage and Droid continue to evolve.

ccusage can read local Droid session settings files as one of its supported data sources, using the same daily, monthly, and session report views as the rest of ccusage.

Focused Views

bunx (Recommended)

bunx ccusage droid --help

npx

npx ccusage@latest droid --help

pnpm

pnpm dlx ccusage droid --help

Data Source

The CLI reads Droid settings JSON files from DROID_SESSIONS_DIR (defaults to ~/.factory/sessions). DROID_SESSIONS_DIR can be one directory or a comma-separated list of directories.

DROID_SESSIONS_DIR="$HOME/.factory/sessions,/backup/factory/sessions" ccusage droid session

~/.factory/sessions/
└── **/*.settings.json

Report Views

Focused view	Description	See also
ccusage droid daily	Aggregate usage by date	Daily Usage
ccusage droid monthly	Aggregate usage by month	Monthly Usage
ccusage droid session	Group usage by Droid session	Session Usage

These views support --json for structured output, --compact for narrow terminals, and --offline for cached pricing data.

What Gets Calculated

• Token usage - Droid settings files provide input, output, cache creation, cache read, and thinking token counts.
• Reasoning tokens - Thinking tokens are included in total tokens and output-side cost estimation.
• Pricing - Costs are calculated from LiteLLM pricing data for the recorded model and provider.

Environment Variables

Variable	Description
DROID_SESSIONS_DIR	Override the sessions directory, or comma-separated sessions directories, containing Droid data
LOG_LEVEL	Adjust verbosity (0 silent ... 5 trace)

Troubleshooting

No Droid usage data found

Ensure the data directory exists at ~/.factory/sessions/ and contains *.settings.json files. Set DROID_SESSIONS_DIR if your Droid data lives elsewhere or in multiple archive roots.

Costs showing as $0.00

If a model is not in LiteLLM's database, the cost will be $0.00. Open an issue to request alias support.