selfaware

name

selfaware

description

Makes Claude aware of its own API usage limits and able to manage them intelligently. Usage is checked automatically by hooks (SessionStart + UserPromptSubmit) that inject a directive when usage gets high; Claude delegates suitable tasks to a Codex sub-agent to conserve tokens, checkpoints work before limits hit, and resumes after resets. Use this skill for: long coding sessions, multi-file refactors, agentic tasks, marathon sessions, or any work where hitting a usage limit mid-task would be disruptive. Also trigger when the user mentions usage, limits, capacity, quota, token conservation, Codex delegation, or the claude-m marathon command. If a TASK_STATE.md exists in the project root, this skill is relevant — read it before doing anything.

Claude Selfaware

You have real-time awareness of your own API usage and manage it intelligently — including offloading work to Codex when you're running low. Usage is checked automatically by hooks; your job is to act on what they inject.

How checks reach you (hooks)

Two hooks run usage-hook.sh for you — you don't call them:

• SessionStart — at session start, surfaces any TASK_STATE.md checkpoint to resume.
• UserPromptSubmit — before every reply, re-checks usage.

They stay silent at OK/MODERATE and only inject a <usage_status> directive once you reach WARNING (80%) or above. So: if you see no usage note, you have plenty of capacity — just work. When a directive appears, follow it (delegate / checkpoint / push through).

Manual check

You can still read usage on demand (the hooks use the same script):

~/.claude/skills/selfaware/scripts/usage-check.sh

Outputs:

<usage_status>
  <five_hour>
    <utilization>42%</utilization>
    <resets_at>2026-06-24T18:30:00Z</resets_at>
    <minutes_to_reset>87</minutes_to_reset>
  </five_hour>
  <seven_day>
    <utilization>67%</utilization>
    <resets_at>2026-06-29T12:00:00Z</resets_at>
  </seven_day>
  <opus_seven_day>
    <utilization>23%</utilization>
  </opus_seven_day>
  <codex_available>true</codex_available>
  <reset_soon>false</reset_soon>
  <status>OK | MODERATE | WARNING | CRITICAL | CRITICAL_BUFFER | UNKNOWN</status>
  <directive>...</directive>
</usage_status>

When you might check manually

The hooks cover the routine cadence. Run usage-check.sh yourself only when you want a reading mid-task that the hook hasn't surfaced — e.g. before starting something large (know your budget first), or when the user asks about usage. The script caches for 2 minutes, so an occasional manual check is cheap.

How To Act By Status

OK (under 60%)

Full speed. Don't mention usage to the user.

MODERATE (60-79%)

Work normally, stay efficient. No need to mention usage.

WARNING (80-89%) — DELEGATE TO CODEX

This is the key behavior. When you cross 80%:

1. Check <codex_available>.

   • If true: Automatically delegate suitable tasks to Codex to conserve Claude tokens. You decide which tasks — no need to ask the user (they pre-approved auto-delegation).
   • If false: Can't offload. Just wrap up efficiently and prepare to checkpoint.

2. Pick the RIGHT tasks for Codex. Good candidates are independent, well-specified, and verifiable:

   • Boilerplate generation (CRUD, config files, type definitions)
   • Writing tests for already-written code
   • Repetitive edits across files (rename, format, mechanical refactors)
   • Self-contained functions with clear specs
   • Documentation generation

   Keep for yourself (don't delegate) tasks that are:

   • Architectural or design decisions
   • Anything needing context from this conversation Codex won't have
   • Security-sensitive logic
   • Tasks where verifying Codex's output costs as much as doing it yourself

3. Delegate with:

   ~/.claude/skills/selfaware/scripts/codex-delegate.sh "clear, complete task description" /path/to/project
   

   Give Codex a complete, self-contained prompt — it doesn't see this conversation. Include file paths, requirements, and what "done" looks like.

4. Review what Codex returns. Verify it (run tests, read the diff). If good, continue. If wrong, fix it yourself or re-delegate with clearer instructions.

5. Tell the user once: "Usage at X% — I've handed [task] to Codex to conserve tokens."

CRITICAL (90%+) — STOP WITH BUFFER

1. Mostly stop. Don't start new work. Keep a buffer of remaining capacity.
2. Write TASK_STATE.md immediately (template below).
3. Tell the user: what's done, what remains, when it resets, how to resume.
4. Stop after saving state.

CRITICAL_BUFFER (90%+ but 5h resets in ≤30 min) — PUSH THROUGH

Special case: if the 5-hour window is over 90% but resets within 30 minutes AND the weekly window is still healthy, the script returns CRITICAL_BUFFER. This means:

• You MAY keep working carefully through the remaining buffer, since the window refreshes shortly anyway.
• Still keep a TASK_STATE.md ready in case you hit a hard wall.
• Don't start large new operations — finish what's in flight.
• This only applies when reset_soon=true and weekly usage is NOT critical.

UNKNOWN

Script couldn't fetch data. Work normally, check again at next milestone. If repeated, tell the user the usage check isn't working.

TASK_STATE.md

Write to project root when checkpointing:

# Task State Checkpoint
> Saved at: [timestamp]
> Usage: [five_hour]% (5h) / [seven_day]% (7d)
> Resets at: [resets_at]

## Task
[One-line goal]

## Status: IN_PROGRESS

## Done
- [Completed item, with enough detail to verify]

## In Progress
- [What was being worked on and its current state]

## Delegated to Codex
- [Any tasks handed to Codex and their status]

## Next Steps
1. [Exact next action — specific enough for a fresh session]
2. [...]

## Files Touched
- `path/to/file` — [what changed]

## Resume Instructions
[What to do first when resuming]

Quality matters. Bad: "Was working on auth." Good: "Added JWT verify to src/auth.ts:45-80. Refresh logic written, untested. Next: npm test -- --grep auth."

Session Start Protocol

The SessionStart hook already checks usage and, if a TASK_STATE.md exists, injects a note telling you to resume. When you see that note: read TASK_STATE.md, tell the user what you're resuming, verify the recorded state, and continue from its Next Steps. If no note appears, just proceed with the user's request.

Marathon sessions (claude-m)

The user can launch a long unattended run with claude-m — it opens you inside a tagged tmux session watched by a shared background daemon. When usage hits the 5-hour limit the daemon sends you a wrap-up message: checkpoint to TASK_STATE.md and stop. After the window resets it sends a resume nudge. So in a marathon, treat any "checkpoint and pause" message as a hard signal to save state immediately — that's your only chance before the wall.

The Keep-Alive (background, not your concern)

A separate keepalive.sh runs via a launchd agent (surviving sleep and reboot) to ping Claude — and Codex if enabled and working — every 5 hours with a tiny dummy prompt, keeping the rolling windows warm. It skips when usage is already above 70%. You don't invoke this — it runs independently. Just know it exists if the user asks why their session stays active.

Weekly Limit Awareness

If seven_day is above 80% even when five_hour is low:

• Tell the user: "Weekly usage is at X%. Capacity now but we should prioritize."
• Lean harder on Codex delegation to stretch the weekly budget.
• Avoid Opus-heavy operations if opus_seven_day is also high.

Rules

• Never fabricate usage numbers. Only report what the script returns.
• Don't mention usage when OK/MODERATE. One mention at WARNING, clear comms at CRITICAL.
• At 80%+, delegate to Codex automatically when available — that's the whole point.
• Give Codex complete, self-contained prompts — it has zero conversation context.
• Always verify Codex output before building on it.
• Respect the 30-min buffer rule — CRITICAL_BUFFER means keep going, plain CRITICAL means stop.
• Always be ready to checkpoint — usage can jump 10%+ in one heavy operation.
• Delete TASK_STATE.md when a resumed task completes.