finfocus-budget
Configure, check, and troubleshoot FinFocus budget thresholds. Use when setting cost.budgets in config.hujson, reading budget health, filtering scopes with --budget-scope, or making cost projected, cost actual, or overview exit non-zero in CI. Triggers on: "finfocus budget", "bud
Install
npx skills add https://github.com/rshade/finfocus/tree/main/agent-skills/finfocus-budget
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install rshade-finfocus@llmmart
git clone https://github.com/rshade/finfocus.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole rshade/finfocus collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
FinFocus budgets
This skill is FinFocus-specific. Generic multi-tool budget workflows live in
rshade/agent-skills, not here.
1. Put the limit in config
finfocus config init writes $PROJECT/.finfocus/config.hujson inside a Pulumi
project, or ~/.finfocus/config.hujson otherwise. Project config overrides
global config at the top-level key. A legacy config.yaml is migrated on read.
Set cost.budgets. A global amount is required when any provider, tag, or type
budget is present. Amount 0 disables that scope. Only monthly is valid.
{
"cost": {
"budgets": {
"global": {
"amount": 500,
"currency": "USD",
"exit_on_threshold": true,
"exit_code": 2,
"alerts": [{ "threshold": 100, "type": "forecasted" }]
}
}
}
}
Full schema, scoped examples, and validation errors: references/budget-config.md.
2. See whether spend is inside the limit
finfocus cost projected --pulumi-json plan.json
finfocus cost actual --pulumi-json plan.json --from 2026-10-01
finfocus overview
Table output prints a BUDGET STATUS section. JSON and NDJSON cost documents
do not include that banner. Health bands:
- OK below 80%
- WARNING from 80% up to 90%
- CRITICAL from 90% up to 100%
- EXCEEDED at 100% and above
Several scopes roll up to the worst status.
Details: references/budget-health.md.
3. Fail CI only when asked
A global-only budget (no provider, tag, or type scope) exits through
checkBudgetExit. That path fails when exit_on_threshold is true and a
configured alert, including a forecasted alert, is exceeded.
--exit-on-threshold and --exit-code override the global scope for that one
command and write nothing to the config. FINFOCUS_BUDGET_EXIT_ON_THRESHOLD and
FINFOCUS_BUDGET_EXIT_CODE set cost.budgets.global for the process, and a
flag wins over them. Default is off, exit code 1.
Any provider, tag, or type budget switches the exit to checkScopedBudgetExit.
That gate opens on CRITICAL or EXCEEDED actual-spend health. A scoped gate can fail at 90% actual utilization. Configured alerts, including a forecasted
alert, stay on the global-only path. The breached scope uses its own
exit_on_threshold when set. An unset scope uses
cost.budgets.exit_on_threshold. The CLI flags and the two exit environment
variables apply to the global scope only, so set the provider field or the
parent field to open a provider gate.
finfocus cost projected --pulumi-json plan.json --exit-on-threshold --exit-code 2
overview accepts the same flags and the same exit path. Its
--exit-on-threshold help text says the exit applies in non-TTY output.
On the global-only path, exit code 0 logs a warning and still exits 0.
A budget evaluation failure uses exit code 1.
Flags and the exit path: references/budget-cli.md.
4. Fix the usual misses
- No banner:
cost.budgets.global.amountis missing or0. Read the effectiveconfig.hujson(finfocus config list). - Exit stays 0 on a global-only budget:
cost.budgets.global.exit_on_thresholdis still false. Pass--exit-on-thresholdor set that field orFINFOCUS_BUDGET_EXIT_ON_THRESHOLD. - Exit stays 0 on a provider, tag, or type budget: set that scope's
exit_on_threshold, or setcost.budgets.exit_on_threshold. The CLI flag andFINFOCUS_BUDGET_EXIT_ON_THRESHOLDapply to the global scope only. global budget is required: a provider, tag, or type budget exists withoutglobal.amount > 0.- Currency error: a scoped currency differs from the global currency. Omit it to inherit.
- Tag rows stay at
$0: tag allocation is validated but not applied to cost results yet. The config warning says so.
Do not invent FINFOCUS_BUDGET_AMOUNT or FINFOCUS_BUDGET_CURRENCY. The
process does not read those variables.
Files (finfocus)
-
references
-
budget-cli.md 4 KB
Loading… -
budget-config.md 3.8 KB
Loading… -
budget-health.md 2.5 KB
Loading…
-
-
finfocus-budget.skill 6.8 KB · in bundle
-
SKILL.md 4.4 KB
--- name: finfocus-budget description: > Configure, check, and troubleshoot FinFocus budget thresholds. Use when setting cost.budgets in config.hujson, reading budget health, filtering scopes with --budget-scope, or making cost projected, cost actual, or overview exit non-zero in CI. Triggers on: "finfocus budget", "budget threshold", "exit-on-threshold", "budget health", "scoped budget", "cost.budgets", or a CI gate on FinFocus cost. --- <!-- Copyright 2025-2026 Richard Shade. Licensed under Apache-2.0. --> <!-- SPDX-License-Identifier: Apache-2.0 --> # FinFocus budgets This skill is FinFocus-specific. Generic multi-tool budget workflows live in `rshade/agent-skills`, not here. ## 1. Put the limit in config `finfocus config init` writes `$PROJECT/.finfocus/config.hujson` inside a Pulumi project, or `~/.finfocus/config.hujson` otherwise. Project config overrides global config at the top-level key. A legacy `config.yaml` is migrated on read. Set `cost.budgets`. A global amount is required when any provider, tag, or type budget is present. Amount `0` disables that scope. Only `monthly` is valid. ```hujson { "cost": { "budgets": { "global": { "amount": 500, "currency": "USD", "exit_on_threshold": true, "exit_code": 2, "alerts": [{ "threshold": 100, "type": "forecasted" }] } } } } ``` Full schema, scoped examples, and validation errors: [references/budget-config.md](references/budget-config.md). ## 2. See whether spend is inside the limit ```bash finfocus cost projected --pulumi-json plan.json finfocus cost actual --pulumi-json plan.json --from 2026-10-01 finfocus overview ``` Table output prints a `BUDGET STATUS` section. JSON and NDJSON cost documents do not include that banner. Health bands: - OK below 80% - WARNING from 80% up to 90% - CRITICAL from 90% up to 100% - EXCEEDED at 100% and above Several scopes roll up to the worst status. Details: [references/budget-health.md](references/budget-health.md). ## 3. Fail CI only when asked A global-only budget (no provider, tag, or type scope) exits through `checkBudgetExit`. That path fails when `exit_on_threshold` is true and a configured alert, including a `forecasted` alert, is exceeded. `--exit-on-threshold` and `--exit-code` override the global scope for that one command and write nothing to the config. `FINFOCUS_BUDGET_EXIT_ON_THRESHOLD` and `FINFOCUS_BUDGET_EXIT_CODE` set `cost.budgets.global` for the process, and a flag wins over them. Default is off, exit code `1`. Any provider, tag, or type budget switches the exit to `checkScopedBudgetExit`. That gate opens on CRITICAL or EXCEEDED actual-spend health. A scoped gate can fail at 90% actual utilization. Configured alerts, including a forecasted alert, stay on the global-only path. The breached scope uses its own `exit_on_threshold` when set. An unset scope uses `cost.budgets.exit_on_threshold`. The CLI flags and the two exit environment variables apply to the global scope only, so set the provider field or the parent field to open a provider gate. ```bash finfocus cost projected --pulumi-json plan.json --exit-on-threshold --exit-code 2 ``` `overview` accepts the same flags and the same exit path. Its `--exit-on-threshold` help text says the exit applies in non-TTY output. On the global-only path, exit code `0` logs a warning and still exits 0. A budget evaluation failure uses exit code 1. Flags and the exit path: [references/budget-cli.md](references/budget-cli.md). ## 4. Fix the usual misses - No banner: `cost.budgets.global.amount` is missing or `0`. Read the effective `config.hujson` (`finfocus config list`). - Exit stays 0 on a global-only budget: `cost.budgets.global.exit_on_threshold` is still false. Pass `--exit-on-threshold` or set that field or `FINFOCUS_BUDGET_EXIT_ON_THRESHOLD`. - Exit stays 0 on a provider, tag, or type budget: set that scope's `exit_on_threshold`, or set `cost.budgets.exit_on_threshold`. The CLI flag and `FINFOCUS_BUDGET_EXIT_ON_THRESHOLD` apply to the global scope only. - `global budget is required`: a provider, tag, or type budget exists without `global.amount > 0`. - Currency error: a scoped currency differs from the global currency. Omit it to inherit. - Tag rows stay at `$0`: tag allocation is validated but not applied to cost results yet. The config warning says so. Do not invent `FINFOCUS_BUDGET_AMOUNT` or `FINFOCUS_BUDGET_CURRENCY`. The process does not read those variables.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.