Self-Hosted Umami Analytics Agent Skill
Overview
A Claude Code skill that queries and manages a self-hosted Umami analytics platform on behalf of a non-admin client user. It exposes website registration, traffic/visitor stats, sessions, events, real-time data, and report generation through a single scriptable CLI.
Why It Exists
Web analytics questions (“how much traffic did this site get”, “what are the top pages”, “register a new website to track”) should be answerable by an agent directly against a self-hosted Umami instance, without exposing admin endpoints or asking the user to click through a dashboard.
What We Built
A Bun/TypeScript CLI (scripts/umami.ts) wrapped as a Claude Code skill. It logs in with credentials supplied via environment variables, caches a login token under the user cache directory and auto-refreshes it on 401, and scopes every call to the user’s own websites. Admin endpoints are refused at runtime. A reference/ folder documents the endpoint surface and report formats; output is emitted as compact JSON for downstream tooling.
Technologies & Approach
TypeScript on Bun for lightweight execution; token caching with TTL control and transparent refresh; strict non-admin scoping so the same tool is safe to hand to an automated agent. Declared with scoped allowed-tools and an argument hint.
Outcome / Impact
Makes a self-hosted analytics backend queryable in natural language inside agentic workflows, returning structured analytics and reports while keeping admin surface area off-limits.
Capabilities Demonstrated
- Integrating a self-hosted analytics platform behind an agent interface
- Token caching, TTL handling, and auto-refresh on expiry
- Runtime privilege scoping (non-admin enforcement)
- Reusable, JSON-emitting CLI design for automation