BossHogg

Product Introduction

1. Definition: BossHogg is a community-built, open-source Command-Line Interface (CLI) tool written in Rust, designed for programmatic interaction with the PostHog product analytics platform. It functions as an agent-first, terminal-native administrative and query interface.
2. Core Value Proposition: It exists to provide AI coding agents (like Claude Code, Cursor) and terminal-native developers with a compact, scriptable way to operate PostHog without the high context token overhead of loading a full Model Context Protocol (MCP) server surface into every session. Its primary keywords are agent-first PostHog CLI, terminal-native analytics, and low-context AI tooling.

Main Features

1. Comprehensive PostHog Resource Coverage: BossHogg implements the full PostHog API surface accessible via a Personal API Key, covering 31 distinct resources across 10 milestones (M1-M10). This includes core analytics (insights, dashboards, cohorts), data management (persons, events, groups), growth tools (experiments, surveys, feature flags), and the CDP pipeline (Hog Functions, batch exports). It uses a reqwest-based HTTP client with HTTPS-only enforcement for cloud instances and configurable plaintext HTTP for self-hosted deployments.
2. HogQL-First Query Engine: At its core is the bosshogg query run command, which executes synchronous or asynchronous HogQL queries directly against a PostHog project's database. For safety, it automatically injects a LIMIT 100 clause into queries lacking one, a behavior logged in debug mode and overrideable with the --no-limit flag. It accepts queries via command-line argument, standard input (stdin), or file, outputting results in tabular or structured JSON format.
3. Claude Code Skill & Agent-Native Design: BossHogg ships with an integrated Claude Code skill located at .claude/skills/bosshogg/. This skill is engineered for low idle token consumption (200 tokens for frontmatter) compared to the full PostHog MCP server (44,000 tokens), drastically reducing the context load for AI agent loops. The skill provides on-demand reference loading and enables agents to execute precise CLI commands like bh flag list --active --json.
4. Multi-Context Configuration & Safety: The tool supports kubectl-style multiple contexts for managing different PostHog instances (US Cloud, EU Cloud, self-hosted) within a single TOML config file (~/.config/bosshogg/config.toml). It embeds robust safety features: config files are written with 0600 permissions, authorization headers are redacted from debug logs, destructive operations require --yes flag confirmation, and session recording snapshots are never written to stdout by default (requiring an --out file parameter).

Problems Solved

1. Pain Point: High context token consumption in AI agent workflows. Loading the entire PostHog MCP server toolset into an AI coding session consumes significant context window space (~44k tokens), reducing the space available for code and other tools. BossHogg solves this with a skill-based design that loads only essential metadata.
2. Target Audience: The primary users are AI Coding Agent Operators (users of Claude Code, Cursor, etc.), DevOps Engineers automating analytics in CI/CD pipelines, Data Analysts who prefer terminal workflows for ad-hoc HogQL queries, and Product Engineers managing feature flags and experiments via script.
3. Use Cases: Specific scenarios include: automating feature flag rollouts in a deployment script, running scheduled HogQL queries for daily reports in a CI job, debugging a specific user's event journey from the terminal, allowing an AI agent to fetch live analytics data to inform code generation decisions, and managing PostHog resources (cohorts, insights) on a self-hosted instance without using the web UI.

Unique Advantages

1. Differentiation vs. Official Tools: Unlike the official @posthog/cli (focused on source maps and release tracking) or the PostHog MCP server (optimized for rich, UI-driven chart rendering), BossHogg is purpose-built for terminal operations and agent integration. It offers a broader administrative API surface than the CLI and a drastically lower token footprint than the MCP server, making it complementary rather than competitive.
2. Key Innovation: The primary innovation is its "skill-first" architecture for AI agents. By packaging its capabilities as a lightweight Claude skill that defers full tool loading, it achieves a ~220x reduction in idle context token usage. This architectural decision explicitly optimizes for the economics and efficiency of iterative AI agent loops, a niche not directly addressed by PostHog's official tooling.

Frequently Asked Questions (FAQ)

1. How does BossHogg's token usage compare to the PostHog MCP server? BossHogg's Claude Code skill idles at approximately 200 tokens (frontmatter only), while the PostHog MCP server loads its full tool surface, consuming around 44,000 idle tokens per agent session. This makes BossHogg about 220x more context-efficient for agent-based workflows.
2. Can I use BossHogg with a self-hosted PostHog instance? Yes, BossHogg offers first-class support for self-hosted PostHog. You can configure a context using bosshogg login --host http://your-instance --allow-http. The tool automatically disables anonymous usage telemetry for self-hosted contexts and includes version probing via bosshogg doctor to gracefully handle feature availability.
3. Is BossHogg safe for production use with destructive commands? BossHogg incorporates multiple safety features for production use. Destructive operations (hard deletes, data capture) require an explicit --yes flag or interactive TTY confirmation. HogQL queries auto-apply a LIMIT 100 clause unless overridden with --no-limit. All configuration with secrets is stored with strict file permissions (0600).
4. What is the difference between bosshogg login and bosshogg configure? bosshogg login initiates a browser-based OAuth device flow (available on newer PostHog instances). bosshogg configure is the interactive setup that walks you through setting a host URL and pasting a Personal API Key directly, which is the fallback method for instances that don't support the device code flow.
5. How do I output JSON for scripting with BossHogg? Nearly every BossHogg subcommand supports the --json flag, which outputs results as structured JSON. This is ideal for piping into tools like jq for further processing in shell scripts or for direct consumption by other programs, e.g., bosshogg flag list --active --json | jq '.[0].key'.