Itemize

CLI tool that syncs purchases from Walmart, Costco, and Amazon with Monarch. Automatically splits transactions by category using AI.

What it does

1. Fetches orders from retailers with item details
2. Matches them to transactions in Monarch
3. Categorizes items using an LLM (OpenAI or Anthropic Claude)
4. Splits the transaction by category with proportional tax

Example: A $150 Walmart transaction becomes:

• $104.57 Groceries (milk, bread, eggs...)
• $28.42 Household (paper towels, cleaning supplies)
• $17.32 Personal Care (shampoo, toothpaste)

Setup

Prerequisites

• Go 1.24+
• Monarch account
• An LLM API key — OpenAI or Anthropic (Claude)
• Retailer account(s)

Install

go install github.com/eshaffer321/itemize/cmd/itemize@latest

Prebuilt binaries for macOS (amd64/arm64) and Linux (amd64/arm64) are also published on the GitHub Releases page whenever a version tag (vX.Y.Z) is pushed. Download the archive for your platform and extract the itemize binary.

Run itemize -version (or itemize version) at any time to confirm exactly which build you're running — useful for checking whether a locally built binary is stale.

Build from source

For contributors, or to build against an unreleased commit:

git clone https://github.com/eshaffer321/itemize
cd itemize
go build -o itemize ./cmd/itemize/

Contributor checks

Install local tools and hooks before committing:

make install-tools
make install-hooks

The pre-commit hook runs formatting checks, golangci-lint, go vet, and go test ./.... To bypass once in an emergency, run ITEMIZE_SKIP_PRECOMMIT=1 git commit ....

Configure

Set environment variables:

export MONARCH_TOKEN="your_monarch_token"

# Pick one LLM backend:
export OPENAI_API_KEY="your_openai_key"
# or
export ANTHROPIC_API_KEY="your_anthropic_key"

Or create config.yaml:

monarch:
  api_key: "${MONARCH_TOKEN}"

openai:
  api_key: "${OPENAI_API_KEY}"
  model: "gpt-5.4-nano"

anthropic:
  api_key: "${ANTHROPIC_API_KEY}"
  model: "claude-haiku-4-5-20251001"

# Optional: force a backend when both keys are set.
# Leave blank to auto-detect from whichever key is present.
categorizer:
  provider: ""  # "openai" | "anthropic" | ""

storage:
  database_path: "monarch_sync.db"

Choosing an LLM backend

itemize picks the LLM backend based on which API key is configured:

• Only OPENAI_API_KEY set → OpenAI is used.
• Only ANTHROPIC_API_KEY (or CLAUDE_API_KEY) set → Claude is used.
• Both set → defaults to OpenAI; set CATEGORIZER_PROVIDER=anthropic to force Claude.

Override the model with OPENAI_MODEL or ANTHROPIC_MODEL per run.

Usage

# Preview changes (dry run)
./itemize walmart -dry-run -days 14
./itemize costco -dry-run -days 7
./itemize amazon -dry-run -days 7

# Apply changes
./itemize walmart -days 14
./itemize costco -days 7
./itemize amazon -days 7

Flags

Flag	Default	Description
-dry-run	false	Preview without applying changes
-days	14	Days to look back for orders
-max	0	Max orders to process (0 = all)
-verbose	false	Show detailed logs
-force	false	Reprocess already-processed orders

Provider Setup

Walmart

Requires cookies in ~/.walmart-api/cookies.json. See walmart-client-go.

Costco

Uses credentials saved by costco-go.

Amazon

Set up an account with Itemize's guided login command:

./itemize amazon setup -account erick

Itemize creates a persistent browser profile under ~/.itemize/amazon/, opens Chromium, and waits for you to sign into Amazon. After setup, verify the account with a small dry run:

./itemize amazon -account erick -dry-run -days 14 -max 1

Itemize uses amazon-go as a library. The login flow uses Playwright to open Chromium. If Playwright is not already installed globally or in this repo, install it once:

npm install playwright

If Playwright lives elsewhere, add -playwright-root <dir> to amazon setup, where <dir> contains node_modules/playwright. The lower-level -import-browser-profile flag remains available for importing a specific existing Chromium/Playwright profile.

Multiple Amazon accounts

If you sync more than one Amazon account, use -account to pick a cookie account per run instead of setting AMAZON_ACCOUNT_NAME (useful for one-off manual runs where you don't want to remember an env var, or for cron jobs where the account name should be visible right in the crontab line):

./itemize amazon -list-accounts        # see saved amazon-go cookie accounts
./itemize amazon -account amazon-wife  # sync a specific account
./itemize amazon amazon-wife           # shorthand for the same account

AMAZON_ACCOUNT_NAME still works and is used as the default when -account is omitted — cron jobs relying on the env var need no changes.

Troubleshooting

"No matching transaction found"

• Transaction hasn't posted to Monarch yet (wait 1–3 days)
• Amount differs by more than $0.01
• Date differs by more than 5 days

"Order already processed"

• Use -force to reprocess

OpenAI errors

• Check OPENAI_API_KEY is set and has credits

Telemetry

itemize collects anonymous usage data to help understand how the tool is being used and what errors occur in the wild. No personal information or credentials are ever sent.

What is collected:

• Which provider was run (walmart, costco, amazon)
• Sync flags used (dry-run, lookback_days, force, etc. — flag names only, no values that could contain secrets)
• Outcome counts (processed, skipped, errors)
• Error type and message when a sync fails
• OS and Go version (added automatically by the Sentry SDK)

What is never collected:

• API tokens or keys (MONARCH_TOKEN, OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
• Costco email or password
• Amazon account names or cookie file paths
• Order IDs, transaction IDs, or any financial data

Opt out:

export ITEMIZE_NO_TELEMETRY=1
# or the standard
export DO_NOT_TRACK=1

Development

# Run tests
go test ./...

# With coverage
go test ./... -cover

See CLAUDE.md for architecture details and development guide.

License

MIT