Universal session management skill for AI coding agents
AI coding agents (Claude Code, Cursor, Aider, Windsurf, Cline) burn through token budgets and session limits in minutes without pacing. This skill gives any agent self-awareness of its resource consumption, enabling it to:
- Track estimated token/tool-call usage across a session
- Pace work using a Pomodoro-style sprint/rest cadence
- Detect and respond to rate limits with exponential backoff
- Gracefully degrade from full work → planning-only → stop
- Split budgets across multi-agent orchestrations
- Log session activity for debugging and optimization
- Copy
SKILL.mdinto your project root - Copy
config/session-defaults.yamlalongside it - Reference it from your agent's steering file:
Claude Code — add to CLAUDE.md:
Read and follow all instructions in SKILL.md for session management.
Cursor — add to .cursorrules:
@include SKILL.md
Aider — add to .aider.conf.yml:
read: SKILL.md
- Optionally copy
scripts/session-timer.shfor countdown sleep support - Optionally copy
templates/SESSION_LOG.mdas your log starter
| Platform | Integration File | Status |
|---|---|---|
| Claude Code | CLAUDE.md | ✅ Full |
| Cursor | .cursorrules | ✅ Full |
| Aider | .aider.conf.yml | ✅ Full |
| Windsurf | .windsurfrules | ✅ Full |
| Cline | .clinerules | ✅ Full |
| Generic | Any system prompt | ✅ Full |
All tunable parameters live in config/session-defaults.yaml. Key settings:
budget_window_minutes— Rolling time window (default: 300 min / 5 hrs)estimated_max_tool_calls— Max tool calls per window (default: 80)sprint_tool_calls— Tool calls per sprint (default: 20)rest_duration_minutes— Rest between sprints (default: 5)budget_thresholds— Green/Yellow/Red/Critical percentages
See the config file for the full list with documentation.
Contributions welcome! Please open an issue first to discuss changes. PRs should include updates to relevant example files if the skill format changes.
MIT — see LICENSE