Keep the local services healthy.

Most Fleetlens operation is intentionally small: start the local dashboard, let the daemon poll in the background, inspect logs when a metric is missing, and update the bundled CLI as one unit.

Service lifecycle

fleetlens start
fleetlens status
fleetlens stop

Use fleetlens daemon stop when you want to stop only usage polling while leaving the dashboard available.

Menu bar widget

On macOS, Fleetlens can add a small usage icon to the menu bar so plan utilization is visible without opening the dashboard. It is optional. Running any menu bar command on Linux or Windows prints a note pointing you back to the dashboard URL instead of failing silently.

fleetlens menubar install
fleetlens menubar status
fleetlens menubar uninstall

Add --no-open to install without launching immediately, or --no-login to skip the login registration. fleetlens menubar status reports whether the widget is installed, currently running, or only available to install from the current build.

Once installed, click the menu bar icon to open a popover with a utilization bar for every provider that has data — Claude Code, Codex, Copilot, Grok, and Z.ai — each with a countdown to its next reset. The widget does not poll on a fixed interval: it watches the local usage log directly, so every daemon poll (roughly every five minutes) or manual fleetlens usage --save updates the bars immediately.

The Settings page mirrors these commands with Install, Open, and Uninstall buttons, so day-to-day management does not require a terminal. Installing from Settings always skips the login registration, to avoid an unexpected permission prompt from a button click — run fleetlens menubar install from a terminal if you also want it to launch at login. Until the widget is installed, a dismissible banner at the top of the dashboard suggests installing it. A separate one-time banner appears the first time you open the dashboard after pairing with a Team Edition server, confirming what will sync; both banners stay dismissed once closed.

Automatic digest generation

Two digests generate on their own, so Insights has something to show before you ask for it:

If you run Fleetlens without the daemon (fleetlens start --no-daemon), opening the dashboard triggers the same yesterday's-digest generation once per day as a fallback. Month digests never generate automatically — open Insights and generate one when you want it.

Both auto-fire paths respect the AI feature settings on the Settings page. Turning off "Enable AI digests and enrichment" stops both, along with every other AI-generated screen. Two separate checkboxes let you opt out of just one path while keeping the other — "Auto-backfill yesterday's digest on daemon start" and "Auto-backfill last week's narrative on daemon start" — and all three are on by default. Auto-fire never regenerates a digest that already exists and never overlaps one that is currently in progress.

Local state directory

Fleetlens keeps its own state separate from provider transcript roots:

Usage and team logs

fleetlens daemon status
fleetlens daemon logs
fleetlens usage
fleetlens team status
fleetlens team logs

Transcript analytics do not depend on a plan snapshot. If usage is missing, first check provider authentication and the daemon log. For team sync, the log distinguishes a successful push, a queued retry, and an unrecoverable validation failure.

Updates

fleetlens update

The updater installs the newest published CLI and re-executes the fresh binary so the local server and daemon do not remain on an older bundle. If you run the dashboard from a source checkout, rebuild the web standalone output before preparing the CLI bundle.

Build and verify from source

git clone https://github.com/cowcow02/fleetlens.git
cd fleetlens
pnpm install
pnpm typecheck
pnpm test
pnpm build

Prerequisite for pnpm test: the Team Edition server's test suite needs a local Postgres with a dedicated test database — run createdb fleetlens_test once (migrations apply automatically). Without it, team-server tests fail with connection errors while every other package's tests pass. Details in the repository's CONTRIBUTING.md.

For the bundled CLI build:

NEXT_OUTPUT=standalone pnpm build
node scripts/prepare-cli.mjs
node packages/cli/dist/index.js start

Symptom-first troubleshooting