Engineering Conventions
ZaxbyHub/opencode-swarm
Guidelines and non-negotiable engineering invariants for modifying opencode-swarm.
Token-saving session automation — statusline, prompt guard, precompact handoffs, session rotation, and handoff commands for Claude Code
Install Save Tokens
$ npx skills add aspenkit/aspens --skill save-tokens -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install aspenkit/aspens save-tokens --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/aspenkit/aspens.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.agents/skills/save-tokens .claude/skills/save-tokens && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "save-tokens" agent skill from https://github.com/aspenkit/aspens/tree/main/.agents/skills/save-tokens into .claude/skills/save-tokens/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "save-tokens", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/aspenkit/aspens/tree/main/.agents/skills/save-tokensType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add aspenkit/aspens --skill save-tokens -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install aspenkit/aspens save-tokens --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/aspenkit/aspens.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.agents/skills/save-tokens .agents/skills/save-tokens && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "save-tokens" agent skill from https://github.com/aspenkit/aspens/tree/main/.agents/skills/save-tokens into .agents/skills/save-tokens/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "save-tokens", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add aspenkit/aspens --skill save-tokens -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install aspenkit/aspens save-tokens --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/aspenkit/aspens.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.agents/skills/save-tokens .cursor/skills/save-tokens && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "save-tokens" agent skill from https://github.com/aspenkit/aspens/tree/main/.agents/skills/save-tokens into .cursor/skills/save-tokens/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "save-tokens", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/aspenkit/aspens.git --path .agents/skills/save-tokens--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add aspenkit/aspens --skill save-tokens -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install aspenkit/aspens save-tokens --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/aspenkit/aspens.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.agents/skills/save-tokens .gemini/skills/save-tokens && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "save-tokens" agent skill from https://github.com/aspenkit/aspens/tree/main/.agents/skills/save-tokens into .gemini/skills/save-tokens/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "save-tokens", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install aspenkit/aspens save-tokensInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add aspenkit/aspens --skill save-tokens -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/aspenkit/aspens.git skills-src && mkdir -p .github/skills && cp -r skills-src/.agents/skills/save-tokens .github/skills/save-tokens && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "save-tokens" agent skill from https://github.com/aspenkit/aspens/tree/main/.agents/skills/save-tokens into .github/skills/save-tokens/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "save-tokens", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add aspenkit/aspens --skill save-tokens -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install aspenkit/aspens save-tokens --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/aspenkit/aspens.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.agents/skills/save-tokens .opencode/skills/save-tokens && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "save-tokens" agent skill from https://github.com/aspenkit/aspens/tree/main/.agents/skills/save-tokens into .opencode/skills/save-tokens/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "save-tokens", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
save-tokens- GitHub stars
- 102
- Token cost
- ~1.6k tokens
- SKILL.md length
- 621 words
- Files
- 1
- Skills in repo
- 12
- Repo updated
- First seen
- Licence
- MIT
At a glance
Token-saving session automation — statusline, prompt guard, precompact handoffs, session rotation, and handoff commands for Claude Code
- Tasks that involve LLM guardrails
- SKILL.md covers Domain purpose, Business rules / invariants, Non-obvious behaviors and Critical files (purpose, not…, plus 2 more sections
- Calls git
What it does
Save Tokens is an agent skill from aspenkit/aspens. Token-saving session automation — statusline, prompt guard, precompact handoffs, session rotation, and handoff commands for Claude Code
Its SKILL.md is about 1.6k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.
It sits in Agent Workflows, covering LLM guardrails. The repository describes itself as: Your CLAUDE.md stopped working at 200 lines. Generate scoped skill files from your import graph, auto-sync on every commit. Claude Code, Codex and OpenCode. The licence is MIT.
When your agent uses it
- Tasks that involve LLM guardrails
Example prompts
- “/save-tokens”
What it can do on your machine
Read from SKILL.md and the folder at commit 8dde826. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
git
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Save Tokens loads about 1.6k tokens when it runs. Until then it costs about 37 tokens; SKILL.md has 621 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from aspenkit/aspens at commit 8dde826, republished under its MIT licence (© aspenkit). 621 words, ~1,614 tokens.
Download SKILL.mdSave it as
.claude/skills/save-tokens/SKILL.md (or your agent's skills folder).- name
- save-tokens
- description
- Token-saving session automation — statusline, prompt guard, precompact handoffs, session rotation, and handoff commands for Claude Code
- triggers.files
- src/commands/save-tokens.js, src/lib/save-tokens.js, src/templates/hooks/save-tokens*.sh, src/templates/hooks/save-tokens.mjs…
- triggers.keywords
- save-tokens, handoff, statusline, prompt-guard, precompact, session rotation, token warning
You are working on save-tokens — the feature that installs Claude Code hooks and commands to warn about token usage, auto-save handoffs before compaction, and support session rotation.
Domain purpose
aspens save-tokens installs three Claude Code hooks (statusline, prompt-guard, precompact) plus /save-handoff, /resume-handoff-latest, and /resume-handoff slash commands. The hooks observe Claude's own token telemetry and inject system messages telling Claude to rotate sessions before context blow-up. Handoff files persist enough state in .aspens/sessions/ to resume seamlessly in a fresh session.
Business rules / invariants
- Claude-only feature. Hooks and statusline only work with Claude Code; Codex has no save-tokens integration. Config lives in
.aspens.jsonundersaveTokens. - Config thresholds default 175k warn / 200k compact.
Number.MAX_SAFE_INTEGERis the disabled sentinel for either threshold;target.js#isValidSaveTokensConfig()validates shape, types, and threshold ordering — invalid config causesreadConfig()to returnnull. writeConfigpreserves feature config —saveTokensis preserved acrosswriteConfigcalls unless explicitly set tonull.- Sessions dir gitignored —
.aspens/sessions/.gitignoreexcludes everything except.gitignoreandREADME.md. - Settings backup — first install creates
.claude/settings.json.bakif settings exist and no backup exists yet. - StatusLine pre-existence guard —
canInstallSaveTokensStatusLine()refuses to overwrite an unrelated customstatusLine.command; when refused,applyStatusLineAvailability()forces both thresholds toMAX_SAFE_INTEGERand disablessessionRotation.
Non-obvious behaviors
- Three hook entry points dispatched by subcommand. Shell wrappers (
*.sh) read stdin, resolve project dir, and callsave-tokens.mjswithstatusline,prompt-guard, orprecompact.ASPENS_PROJECT_DIRenv var overridesCLAUDE_PROJECT_DIR; both fall back tocwd. - Statusline doubles as telemetry recorder.
recordClaudeContextTelemetry()writes.aspens/sessions/claude-context.jsonsumminginput_tokens + cache_creation_input_tokens + cache_read_input_tokens + output_tokensfromcontext_window.current_usage. Telemetry older than 5 minutes is ignored by the prompt guard. - Prompt-guard speaks to Claude, not the user. Above
compactAtTokens: saves a handoff (reasonrotation-thresholdifsessionRotation, elsecompact-threshold) and stdout-prints an "IMPORTANT — you must tell the user" block instructing fresh session +/resume-handoff-latest. AbovewarnAtTokens: suggests/save-handoff. When telemetry is missing, prints a one-time link to the aspens issues page. - Precompact hook only fires when
saveHandoffis enabled andclaude.enabled !== false; reason isprecompact. extractSessionFacts()parses the JSONL transcript to extractoriginalTask(first user message, 500 char cap),recentPrompts(last 3, 200 char cap each),filesModified(Edit/Write tool_usefile_path),gitCommits(regex on Bashgit commit -m "..."), andbranch(fromgitBranchon user records). Transcript path is validated to be insideprojectDir; falls back toinput.promptwhen transcript is missing or outside the project.- Transcript parsing is best-effort — all errors caught, invalid JSON lines silently skipped; returns empty facts on failure.
pruneOldHandoffs()keeps newest 10*-handoff.mdfiles by lexicographic (timestamp) sort; older are unlinked.latestHandoff()uses the same sort.--recommendedinstall is non-interactive — used standalone or invoked bydoc init --recommended(which also installs agents and the doc-sync git hook).--removecleans legacy artifacts too — removes both.shand historic.mjsvariants of each hook, plus the legacysave-tokens-resume.mdcommand; stripsstatusLineif it points at save-tokens and filters any hook entry whose command containssave-tokens-; nullssaveTokensin.aspens.json.
Show full SKILL.md (149 more words)Show less
Critical files (purpose, not inventory)
src/commands/save-tokens.js— install/remove orchestration; interactive multiselect (warnings,handoffs),--recommended,--remove. ExportsinstallSaveTokensRecommended()consumed bydoc-init.js.src/lib/save-tokens.js— config + settings + template content builders (DEFAULT_SAVE_TOKENS_CONFIG,buildSaveTokensConfig,buildSaveTokensSettings,buildSaveTokensGitignore,buildSaveTokensReadme,buildSaveTokensRecommendations).src/templates/hooks/save-tokens.mjs— runtime library:runStatusline,runPromptGuard,runPrecompact,saveHandoff,extractSessionFacts, telemetry record/read, handoff pruning,main()subcommand dispatch.src/templates/hooks/save-tokens-{statusline,prompt-guard,precompact}.sh— shell wrappers; resolvePROJECT_DIRviacd "$SCRIPT_DIR/../.." && pwdand exec the.mjswith the matching subcommand.src/templates/commands/{save-handoff,resume-handoff-latest,resume-handoff}.md— slash command bodies installed under.claude/commands/.
Critical Rules
- Settings merge uses
mergeSettings()fromskill-writer.js— save-tokens hooks are treated as aspens-managed; do not hand-edit.claude/settings.jsonto add/remove save-tokens entries. - Hooks write to stdout to inject into Claude's context — comments in
runPromptGuard()flag this; keep those messages addressed to Claude ("Tell the user...") not to a human reader. - Token sum includes cache tokens — do not switch to just
input_tokens + output_tokens; that under-counts Claude's effective context use.
References
- Impact integration:
src/lib/impact.js—evaluateSaveTokensHealth()validates installed state
Last Updated: 2026-05-11
© aspenkit, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
Just SKILL.md in .agents/skills/save-tokens of aspenkit/aspens.
Open the folder on GitHubat commit 8dde826
Compare with similar skills
Save Tokens next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Save Tokens this skillaspenkit/aspens | 102 | — | ~1.6k | Automated safety check: Pass | MIT | |
| Engineering ConventionsZaxbyHub/opencode-swarm | 488 | — | ~4.7k | Automated safety check: Pass | MIT | |
| Claude Project Setupmohitagw15856/pm-claude-skills | 1.4k | — | ~1.2k | Automated safety check: Pass | MIT | |
| Run An Agent Teammohitagw15856/pm-claude-skills | 1.4k | — | ~1.3k | Automated safety check: Pass | MIT | |
| Improving MCP ToolsPostHog/posthog-foss | 721 | — | ~1.5k | Automated safety check: Pass | MIT | |
| Git Guardrails Claude Codefossasia/eventyay-interpretation | 1.6k | 12 repos | ~578 | Automated safety check: Pass | Apache-2.0 |
Similar skills
Claude Project Setup
mohitagw15856/pm-claude-skills
Set up a repo or project so an AI coding agent works well in it — the CLAUDE.md, the context, the guardrails, and the conventions the agent needs to be useful instead of lost.
Run An Agent Team
mohitagw15856/pm-claude-skills
Design a small team of AI agents to tackle a complex task in parallel — who does what, how they hand off, and how to keep them coordinated — instead of one overloaded agent doing everything serially.
- Official
Improving MCP Tools
PostHog/posthog-foss
Run an improve-my-MCP campaign: an autoresearch-style loop that measures the MCP agent experience with the eval harness, picks the highest-impact tool problem from production data, makes one bounded…
Git Guardrails Claude Code
fossasia/eventyay-interpretation
Set up Claude Code hooks to block dangerous git commands (push, reset --hard, clean, branch -D, etc.) before they execute.
Git Guardrails Claude Code
vinvcn/mattpocock-skills-zh-CN
设置 Claude Code hooks，在危险 git commands（push、reset --hard、clean、branch -D 等）执行前阻止它们。适用于用户想防止破坏性 git 操作、添加 git safety hooks，或在 Claude Code 中阻止 git push/reset 时。
More from aspenkit/aspens
All 12 skills in this repoAspens Agent Template Customizer
aspenkit/aspens
Injects a project's own skills and AGENTS.md content into generic bundled agent template files, adding a tech-stack line and real conventions without touching an agent's core logic.
aspens Project Conventions
aspenkit/aspens
Orientation to the aspens codebase for agents working on the CLI itself: its Node.js stack, commands, module layout and debug settings.
Aspens CLI Shell
aspenkit/aspens
Project context for the aspens CLI entry point: Commander wiring, the welcome screen, missing-hook warnings, CliError exit handling and the public programmatic exports.
Aspens Multi-Target Output
aspenkit/aspens
Explains how the aspens generator routes output to Claude Code or Codex CLI targets and transforms generated skills and instruction files between their formats.
Doc Impact
aspenkit/aspens
Context health analysis — freshness, domain coverage, hub surfacing, drift detection, LLM-powered interpretation, and auto-repair for generated agent context
Doc Sync
aspenkit/aspens
Incremental skill updater that maps git diffs to affected skills and optionally auto-syncs via a post-commit hook
Related
Categories
Questions about Save Tokens
What does Save Tokens do?
Token-saving session automation — statusline, prompt guard, precompact handoffs, session rotation, and handoff commands for Claude Code. Save Tokens is an agent skill from aspenkit/aspens.
When should I use Save Tokens?
Save Tokens fits situations like: tasks that involve LLM guardrails.
How do I install Save Tokens in Claude Code?
Run `npx skills add aspenkit/aspens --skill save-tokens -a claude-code`. Or copy the skill folder (.agents/skills/save-tokens in aspenkit/aspens) into .claude/skills/save-tokens in your project. Claude Code loads it when a task matches its description.
How do I install Save Tokens in Codex?
Run `npx skills add aspenkit/aspens --skill save-tokens -a codex`. Or copy the skill folder (.agents/skills/save-tokens in aspenkit/aspens) into .agents/skills/save-tokens in your project. Codex loads it when a task matches its description.
Can I use Save Tokens in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add aspenkit/aspens --skill save-tokens -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/save-tokens, .gemini/skills/save-tokens, .github/skills/save-tokens and .opencode/skills/save-tokens in your project.
What does Save Tokens need to run?
Going by SKILL.md and its folder, Save Tokens needs the command-line tools its instructions call (git).
Does Save Tokens access the network?
SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.
Is Save Tokens safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Save Tokens use?
Save Tokens is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Save Tokens use?
About 1.6k tokens (SKILL.md is roughly 6.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.
What are the alternatives to Save Tokens?
Skills that share tags, products or a category with Save Tokens: Engineering Conventions (ZaxbyHub/opencode-swarm, 488 stars), Claude Project Setup (mohitagw15856/pm-claude-skills, 1.4k stars), Run An Agent Team (mohitagw15856/pm-claude-skills, 1.4k stars) and Improving MCP Tools (PostHog/posthog-foss, 721 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Save Tokens?
aspenkit (a GitHub organization) maintains it in aspenkit/aspens, which has 102 GitHub stars. The repository holds 12 skills in this directory. The repository was last updated on September 12, 2026.
Source: aspenkit/aspens on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.