メニュー
Token budget tracking and enforcement for Gastown convoy-level execution. Hard limits with pre-execution checking, per-convoy and per-agent tracking, structured stop reasons.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/Tibsfox/gsd-skill-creator --skill token-budgetコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SOC 職業分類に基づく
SKILL.md を表示中
| name | token-budget |
| description | Token budget tracking and enforcement for Gastown convoy-level execution. Hard limits with pre-execution checking, per-convoy and per-agent tracking, structured stop reasons. |
| type | skill |
| category | state |
| status | stable |
| origin | tibsfox |
| modified | false |
| first_seen | "2026-04-04T00:00:00.000Z" |
| first_path | .claude/skills/token-budget/SKILL.md |
| superseded_by | null |
Pre-execution budget gating for multi-agent convoy execution. Prevents token overspend by checking budgets BEFORE API calls, not after. Identified by the 12 Primitives analysis (Primitive 5) as the #1 actionable improvement.
This skill activates when:
Convoy Budget (hard limit, default 500K tokens)
|
+-- Agent A budget (hard limit, default 100K tokens)
+-- Agent B budget (hard limit, default 100K tokens)
+-- Agent C budget (hard limit, default 100K tokens)
The convoy budget is the aggregate ceiling. Individual agent budgets prevent any single polecat from consuming a disproportionate share.
Every API call in a convoy MUST follow this sequence:
checkBudget(budget, agentId, projectedCost) — returns BudgetCheckResultallowed: false — stop immediately, do NOT make the API callreason: 'warning_threshold' — proceed but log the warningreason: 'ok' — proceed normallyrecordUsage(budget, agentId, actualInput, actualOutput)saveBudget(budget, budgetDir) to survive crashes| Reason | Meaning | Action |
|---|---|---|
ok | Under budget, no concerns | Proceed |
warning_threshold | Past warning % but under hard limit | Proceed, log warning |
convoy_budget_exceeded | Convoy would exceed hard limit | STOP, do not call API |
agent_budget_exceeded | Agent would exceed its limit | STOP, do not call API |
interface TokenBudget {
convoyId: string;
maxTokensPerConvoy: number; // Hard limit for entire convoy
maxTokensPerAgent: number; // Hard limit per polecat
warningThresholdPercent: number; // Warn at this % (e.g., 80)
currentUsage: BudgetUsage;
createdAt: string; // ISO 8601
updatedAt: string; // ISO 8601
}
interface BudgetCheckResult {
allowed: boolean;
reason: 'ok' | 'warning_threshold' | 'convoy_budget_exceeded' | 'agent_budget_exceeded';
remainingTokens: number;
usagePercent: number;
}
| Function | Signature | Description |
|---|---|---|
createBudget | (convoyId, config?) => TokenBudget | Initialize a budget for a convoy |
checkBudget | (budget, agentId, projectedCost) => BudgetCheckResult | Pre-execution gate check |
recordUsage | (budget, agentId, input, output) => void | Track actual usage after execution |
getBudgetReport | (budget) => BudgetReport | Summary for logging/display |
saveBudget | (budget, budgetDir) => Promise<void> | Persist to .chipset/state/budgets/ |
loadBudget | (convoyId, budgetDir) => Promise<TokenBudget | null> | Load from disk |
deleteBudget | (convoyId, budgetDir) => Promise<void> | Remove budget file |
listBudgets | (budgetDir) => Promise<string[]> | List all persisted convoy budget IDs |
| Parameter | Default | Recalibration note |
|---|---|---|
maxTokensPerConvoy | 500,000 tokens | Was set conservatively pre-INLINE-SERIAL pattern. v1.49.621 actuals: ~50-300K per convoy under inline-serial Opus/Sonnet authoring (~10-15% of this default). Default retained for safety margin; missions may explicitly cap lower based on convoy shape. |
maxTokensPerAgent | 100,000 tokens | Pre-recursive-spawn-block default; with INLINE SERIAL the agent IS the convoy, so per-agent ≈ per-convoy. |
warningThresholdPercent | 80% | Unchanged. |
v1.49.621 retrospective lesson 3 — projection recalibration: Wave 1+2+3+4 fleet token spend came in at ~26% of projected ceiling under INLINE SERIAL authoring. Future missions should project Opus convoys at ~75-300K and Sonnet convoys at ~30-150K based on output volume × ~1.5K tokens/100-line-of-output heuristic. Reserve 3-5× headroom over the projection for safety; do not 10× as this skill historically did.
Path: .chipset/state/budgets/{convoyId}.json
Follows the same durability contract as beads-state:
When the mayor creates a convoy, it should also create a token budget:
const convoy = await stateManager.createConvoy('Sprint 1', beadIds);
const budget = createBudget(convoy.id, {
maxTokensPerConvoy: 500_000,
maxTokensPerAgent: 100_000,
});
await saveBudget(budget, '.chipset/state/budgets');
Before each API call in GUPP autonomous mode:
const budget = await loadBudget(convoyId, '.chipset/state/budgets');
const check = checkBudget(budget!, agentId, estimatedTokens);
if (!check.allowed) {
// Structured stop — include reason in termination message
return { stopped: true, reason: check.reason, remaining: check.remainingTokens };
}
// ... make API call ...
recordUsage(budget!, agentId, actualInput, actualOutput);
await saveBudget(budget!, '.chipset/state/budgets');
The witness can periodically check budget health:
const budget = await loadBudget(convoyId, '.chipset/state/budgets');
const report = getBudgetReport(budget!);
if (report.warningActive) {
// Alert: convoy approaching budget limit
}
src/chipset/gastown/token-budget.tssrc/chipset/gastown/token-budget.test.tssrc/chipset/gastown/index.ts