tutor-status

Tutor Status

The dashboard reader for llm-tutor. Shows the user's current state at a glance — XP, cycles, what they're working on, what they've finished.

This skill is read-only — it doesn't modify state, doesn't charge cycles, doesn't reward feedback. It just queries state.json and renders a formatted overview.

---

Step 0 — Defensive setup

STATE="$CLAUDE_PLUGIN_ROOT/scripts/state.sh"

# Ensure state file exists (idempotent — no-op if already initialized)
bash "$STATE" init >/dev/null

# Refill cycles if daily reset is due (defensive — the hook should have
# done this, but doesn't hurt to be sure on a status query)
bash "$STATE" refill-cycles >/dev/null 2>&1 || true

---

Step 1 — Read the pieces

XP=$(bash "$STATE" get .user.xp)
CYCLES=$(bash "$STATE" get .user.cycles)
CYCLES_CAP=$(bash "$STATE" get .user.cycles_cap)
LAST_RESET=$(bash "$STATE" get .user.cycles_last_reset)

# Current tier + progress toward next tier
TIER="$CLAUDE_PLUGIN_ROOT/scripts/tier.sh"
TIER_NAME=$(bash "$TIER" name "$XP")
TIER_INDEX=$(bash "$TIER" index "$XP")
NEXT=$(bash "$TIER" next "$XP")
# NEXT is either "max" or "<name>|<xp_needed>"

# Topic counts
TOPICS_JSON=$(bash "$STATE" get .topics)
ACTIVE_TOPICS=$(echo "$TOPICS_JSON" | jq 'to_entries | map(select(.value.status == "in_progress"))')
COMPLETED_TOPICS=$(echo "$TOPICS_JSON" | jq 'to_entries | map(select(.value.status == "completed"))')

ACTIVE_COUNT=$(echo "$ACTIVE_TOPICS" | jq 'length')
COMPLETED_COUNT=$(echo "$COMPLETED_TOPICS" | jq 'length')

---

Step 2 — Compute time until next cycles refill

The cycles hook refills 24 hours after cycles_last_reset. Compute the remaining time.

NOW_EPOCH=$(date -u +%s)
if [[ "$(uname -s)" == "Darwin" ]]; then
  LAST_EPOCH=$(date -j -u -f "%Y-%m-%dT%H:%M:%SZ" "$LAST_RESET" +%s 2>/dev/null || echo 0)
else
  LAST_EPOCH=$(date -u -d "$LAST_RESET" +%s 2>/dev/null || echo 0)
fi

ELAPSED=$((NOW_EPOCH - LAST_EPOCH))
REMAINING=$((86400 - ELAPSED))

if [ "$REMAINING" -le 0 ]; then
  REFILL_TEXT="due now"
else
  HOURS=$((REMAINING / 3600))
  MINS=$(( (REMAINING % 3600) / 60 ))
  if [ "$HOURS" -gt 0 ]; then
    REFILL_TEXT="next refill in ${HOURS}h ${MINS}m"
  else
    REFILL_TEXT="next refill in ${MINS}m"
  fi
fi