CostGoblin

CostGoblin is a desktop app that syncs your AWS billing data locally and queries it with DuckDB. Filter, drill down, and slice costs by any dimension — from a plane at 10,000 meters.

Install

Download the latest release for your platform from costgoblin.com. macOS binaries are signed and notarized. See the code signing policy for details.

Release builds check GitHub Releases for a new version once at launch and prompt you when one is out. Downloading and installing are one click each and never happen without your confirmation; Check for updates in Settings → General runs a check on demand. To turn the launch check off, choose Manual only under Settings → General → Update check (saved per workspace), or set COSTGOBLIN_DISABLE_UPDATE_CHECK=1 in the app's environment, which covers every workspace (macOS GUI apps don't read shell profiles: use launchctl setenv COSTGOBLIN_DISABLE_UPDATE_CHECK 1, e.g. from an MDM LaunchAgent). Turning it off is advisable where github.com is blocked. The prompt is a notification, not a patching mechanism: fleets should enforce versions through MDM.

Quick Start

make dev

make dev installs dependencies with npm ci on its first run, and again whenever package-lock.json changes (after a pull or a branch switch). On first launch, the setup wizard guides you through connecting to your AWS billing data.

Prerequisites

• Node.js 24+
• At least one billing source:
  • AWS — a FOCUS 1.2 Data Export delivered as Parquet to S3 (below)
  • GCP — the native FOCUS BigQuery export, copied into a GCS bucket by the FOCUS exporter

A workspace can configure several providers at once; totals sum across them and a provider dimension splits them apart.

Setting Up AWS Data Exports

CostGoblin reads AWS billing data from AWS Data Exports delivered to S3 as Parquet: the FOCUS 1.2 table, plus, optionally, Cost Optimization Hub recommendations. Everything below happens in the account that owns the billing data, usually the management (payer) account.

Before you start

Whichever way you create the exports afterwards:

1. Activate your cost allocation tags under Billing and Cost Management → Cost allocation tags. Only active tags reach the export, and activating one later doesn't backfill it.
2. Enable Cost Optimization Hub, if you want its recommendations: open Billing and Cost Management → Cost Management preferences, go to the Cost Optimization Hub tab, tick Enable Cost Optimization Hub (in the management account, also include all member accounts under Organization and member account settings), then Save preferences. Until you do, AWS refuses to create a Cost Optimization Hub export, so a stack that includes one fails too. Recommendations take up to 24 hours to appear, and the rightsizing ones need Compute Optimizer enabled as well.
3. Make room for the exports. AWS allows two FOCUS 1.2 exports per account. If Data Exports already lists FOCUS 1.2 exports, connect CostGoblin to those instead, or delete them first: AWS refuses a third.

Then create the exports in one of the two ways below. Both produce the same exports with the same settings; use the stack unless you can't.

Recommended: one CloudFormation stack

The stack (costgoblin-exports.yaml) creates everything with the settings CostGoblin needs:

• an S3 bucket (no public access, encrypted) with the lifecycle rules below;
• the daily FOCUS 1.2 export, and optionally the hourly and Cost Optimization Hub exports;
• a read-only IAM policy granting exactly what CostGoblin needs on that bucket.

The setup wizard walks you through it: on the bucket step, choose Create one with CloudFormation. It opens the stack with your answers filled in and configures CostGoblin with the stack's paths. Without the app:

1. Launch the stack. It opens CloudFormation in us-east-1, the only region with AWS Data Exports, with the latest release's template loaded.
2. Fill in the parameters: a bucket name (leave it empty for costgoblin-billing-<account id>), and whether to add the hourly and Cost Optimization Hub exports. If the account already has the AWSServiceRoleForBCMDataExports role (IAM → Roles; creating a Cost Optimization Hub export adds it), set CreateDataExportsServiceRole to no.
3. Acknowledge that the stack creates IAM resources, and create it.
4. Attach the ReadAccessPolicyArn output to the role or user CostGoblin reads with, and point CostGoblin at the paths in the stack's Outputs (DailyExportPath and the others).

To read the template before running it, download the raw file, open CloudFormation in us-east-1 and choose Create stack → With new resources → Upload a template file. Don't paste a GitHub link into the Amazon S3 URL field: it only accepts templates stored in S3.

This is the beginning of the README. Read the rest at the original. Read the full README ↗