asciinema-streaming-backup — Claude Code skill: how to install
asciinema-streaming-backup streams asciinema terminal recordings to an isolated GitHub orphan branch using zstd and brotli compression.
MIT 128 installs ★ 3 updated 2026-10-25
npx skills add terrylica/cc-skills --skill asciinema-streaming-backup -a claude-codeWhat asciinema-streaming-backup does
This skill configures a backup pipeline for asciinema terminal sessions. It monitors terminal inactivity using an idle detector, breaks recordings into chunks at pauses, and compresses them with zstd. Everything pushes to a dedicated Git orphan branch, keeping terminal logs completely isolated from your project history.
On GitHub, an Actions workflow recompresses the incoming chunks with brotli. Running this requires macOS or Linux alongside asciinema 3.0+, git 2.20+, gh, zstd, and brotli. Without the GitHub CLI authenticated locally, the skill cannot configure the remote target branch.
What it helps with
- Stream asciinema terminal recordings directly to a GitHub repository
- Keep recording history separate from main code using an orphan branch
- Split terminal recordings automatically during idle pauses
- Recompress streamed zstd chunks with brotli via GitHub Actions
Example prompts for the agent
- Set up streaming asciinema backup to a GitHub orphan branch
- Configure idle-detection chunking for my asciinema recordings
- Validate requirements and initialize the recording backup pipeline
How to install asciinema-streaming-backup
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill asciinema-streaming-backup -a claude-code2Manually: put the files in place
~/.claude/skills/asciinema-streaming-backup/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/asciinema-streaming-backup/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill asciinema-streaming-backup -a codex2Manually: put the files in place
.agents/skills/asciinema-streaming-backup/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill asciinema-streaming-backup -a cursor2Manually: put the files in place
.cursor/skills/asciinema-streaming-backup/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install terrylica/cc-skills plugins/asciinema-tools/skills/asciinema-streaming-backup2Manually: put the files in place
.github/skills/asciinema-streaming-backup/SKILL.md1Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill asciinema-streaming-backup -a gemini-cli2Platform CLI
gemini skills install https://github.com/terrylica/cc-skills --path plugins/asciinema-tools/skills/asciinema-streaming-backupManually: put the files in place
.devin/skills/asciinema-streaming-backup/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add terrylica/cc-skills --skill asciinema-streaming-backup -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about asciinema-streaming-backup
How to install asciinema-streaming-backup in Claude Code?
Run npx skills add terrylica/cc-skills --skill asciinema-streaming-backup -a claude-code. The skill file is placed in ~/.claude/skills/asciinema-streaming-backup/SKILL.md.
What does asciinema-streaming-backup do?
It creates an automated pipeline that streams asciinema terminal recordings to an orphan branch in GitHub. It cuts recordings into chunks during idle periods, compresses them with zstd, and triggers a GitHub Actions workflow for brotli recompression.
Which dependencies are required?
You need macOS or Linux with asciinema 3.0+, git 2.20+, gh, zstd, and brotli. The fswatch tool is optional for live filesystem monitoring.
Source text
SKILL.md · MIT
---
name: asciinema-streaming-backup
description: Real-time asciinema backup to GitHub orphan branch. TRIGGERS - streaming backup, asciinema backup, session backup, recording backup.
allowed-tools: Read, Bash, Glob, Write, Edit, AskUserQuestion
---
# asciinema-streaming-backup
Complete system for streaming asciinema recordings to GitHub with automatic brotli archival. Uses idle-detection for intelligent chunking, zstd for concatenatable streaming compression, and GitHub Actions for final brotli recompression.
> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
## When to Use This Skill
Use this skill when:
- Setting up real-time backup of asciinema recordings to GitHub
- Configuring idle-detection chunking for recordings
- Creating orphan branch infrastructure for recording storage
- Integrating GitHub Actions for brotli recompression
> **Platform**: macOS, Linux
> **Isolation**: Uses Git orphan branch (separate history, cannot pollute main)
---
## Architecture Overview
```
┌─────────────────┐ zstd chunks ┌─────────────────┐ Actions ┌─────────────────┐
│ asciinema rec │ ──────────────────▶ │ GitHub Orphan │ ───────────────▶ │ brotli archive │
│ + idle-chunker │ (concatenatable) │ gh-recordings │ │ (300x compress)│
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
│ Idle ≥30s triggers chunk │ Separate history
▼ │ Cannot PR to main
~/asciinema_recordings/ ▼
└── repo-name/ .github/workflows/
└── chunks/*.zst └── recompress.yml
```
---
## Requirements
| Component | Required | Installation | Version |
| ----------------- | -------- | ------------------------ | ------------- |
| **asciinema CLI** | Yes | `brew install asciinema` | 3.0+ (Rust) |
| **zstd** | Yes | `brew install zstd` | Any |
| **brotli** | Yes | `brew install brotli` | Any |
| **git** | Yes | Pre-installed | 2.20+ |
| **gh CLI** | Yes | `brew install gh` | Any |
| **fswatch** | Optional | `brew install fswatch` | For real-time |
---
## Workflow Phases
### Phase 0: Preflight Validation
Verify all tools installed, offer self-correction if missing. Run the preflight check script, then AskUserQuestion to offer installation for missing tools.
See [Setup Scripts](./references/setup-scripts.md) for the complete `preflight-check.sh` script.
**Self-Correction**: If tools are missing, generate installation command and offer to run it.
---
### Phase 1: GitHub Account Detection
Detect available GitHub accounts from 4 sources (SSH config, SSH keys, gh CLI, git config) and let user choose which to use.
See [Account & Repository Detection](./references/account-detection.md) for the detection script, scoring logic, and AskUserQuestion flow.
---
### Phase 1.5: Current Repository Detection
Detect current git repository context (`CURRENT_REPO_OWNER`, `CURRENT_REPO_NAME`, `DETECTED_FROM`) to provide intelligent defaults for Phase 2.
See [Account & Repository Detection](./references/account-detection.md#phase-15-current-repository-detection) for the detection script.
---
### Phase 2: Core Configuration
Gather essential configuration: repository URL (with auto-detection from Phase 1.5), recording directory, and branch name.
See [Configuration Reference](./references/configuration-reference.md#phase-2-core-configuration) for all AskUserQuestion sequences and URL normalization logic.
---
### Phase 3: Advanced Configuration
Allow customization of compression and behavior parameters:
| Parameter | Default | Range |
| -------------- | ------- | ----------- |
| Idle threshold | 30s | 5-300s |
| zstd level | 3 | 1-22 |
| Brotli level | 9 | 1-11 |
| Auto-push | Yes | Yes/No |
| Poll interval | 5s | 2s, 5s, 10s |
See [Configuration Reference](./references/configuration-reference.md#phase-3-advanced-configuration) for all AskUserQuestion sequences.
---
### Phase 4: Orphan Branch Setup
Create or configure the orphan branch with GitHub Actions workflow. Checks for existing branch first and offers clone/reset/verify options.
Key actions:
1. Check if branch exists on remote via `git ls-remote`
2. If exists: AskUserQuestion for clone/reset/verify
3. If new: Create orphan branch, add workflow + directory structure, push
See [Setup Scripts](./references/setup-scripts.md#setup-orphan-branchsh) for the complete `setup-orphan-branch.sh` script.
See [GitHub Workflow](./references/github-workflow.md) for the full `recompress.yml` Actions workflow.
---
### Phase 5: Local Environment Setup
Configure local directory and generate customized `idle-chunker.sh` with user parameters embedded from Phase 3.
Key actions:
1. Clone orphan branch to `~/asciinema_recordings/<repo>/`
2. Generate `idle-chunker.sh` with embedded configuration
3. Display configuration summary and usage instructions
See [Setup Scripts](./references/setup-scripts.md) for local setup scripts.
See [Idle Chunker](./references/idle-chunker.md) for the complete chunker implementation.
---
### Phase 6: Autonomous Validation
Claude executes 8 tests autonomously, displaying formatted results. Only 2 tests require user action (recording test, chunker live test).
| Test Category | Count | Autonomous? |
| ---------------------- | ----- | ----------- |
| Tool preflight | 5 | Yes |
| Compression round-trip | 3 | Yes |
| Repository validation | 4 | Yes |
| GitHub Actions trigger | 1 | Yes |
| Recording test | 1 | No (USER) |
| Chunker live test | 1 | No (USER) |
See [Autonomous Validation](./references/autonomous-validation.md) for the complete validation script, user-required test flows, and troubleshooting table.
---
## Quick Start
### First-Time Setup
```bash
/usr/bin/env bash << 'PREFLIGHT_EOF'
# 1. Check requirements
for tool in asciinema zstd brotli git gh; do
command -v "$tool" &>/dev/null && echo "$tool: OK" || echo "$tool: MISSING"
done
# 2. Create orphan branch (replace with your repo)
REPO="[email protected]:YOUR/REPO.git"
./setup-orphan-branch.sh "$REPO"
# 3. Validate setup
./validate-setup.sh "$HOME/asciinema_recordings/REPO"
PREFLIGHT_EOF
```
### Recording Session
```bash
/usr/bin/env bash << 'SKILL_SCRIPT_EOF'
# Terminal 1: Start recording
WORKSPACE=$(basename "$PWD")
asciinema rec $PWD/tmp/${WORKSPACE}_$(date +%Y-%m-%d_%H-%M).cast
# Terminal 2: Start idle-chunker
~/asciinema_recordings/REPO/idle-chunker.sh $PWD/tmp/${WORKSPACE}_*.cast
SKILL_SCRIPT_EOF
```
---
## Key Design Decisions
| Decision | Rationale |
| ----------------------- | -------------------------------------------------- |
| **zstd for streaming** | Supports frame concatenation (brotli doesn't) |
| **brotli for archival** | Best compression ratio (~300x for .cast files) |
| **Orphan branch** | Complete isolation, can't pollute main history |
| **Idle-based chunking** | Semantic breakpoints, not mid-output splits |
| **Shallow clone** | Minimal disk usage, can't accidentally access main |
| **30s idle threshold** | Balances chunk frequency vs semantic completeness |
---
## Troubleshooting
See [Troubleshooting Guide](./references/troubleshooting.md) for common issues and fixes.
---
## Post-Change Checklist
After modifying this skill:
1. [ ] Orphan branch creation scripts use heredoc wrapper
2. [ ] All bash blocks compatible with zsh (no declare -A, no grep -P)
3. [ ] GitHub Actions workflow validates brotli recompression
4. [ ] Idle chunker handles both macOS and Linux stat syntax
5. [ ] Detection flow outputs parseable key=value format
6. [ ] References validate links to external documentation
---
## Reference Documentation
- [Account & Repository Detection](./references/account-detection.md) - GitHub account detection + repo context
- [Configuration Reference](./references/configuration-reference.md) - AskUserQuestion sequences + task templates
- [Idle Chunker Script](./references/idle-chunker.md) - Complete chunker implementation
- [GitHub Workflow](./references/github-workflow.md) - Full Actions workflow
- [Setup Scripts](./references/setup-scripts.md) - All setup and validation scripts
- [Autonomous Validation](./references/autonomous-validation.md) - Validation script and user-required tests
- [Troubleshooting Guide](./references/troubleshooting.md) - Common issues and fixes
- [asciinema 3.0 Docs](https://docs.asciinema.org/)
- [zstd Frame Format](https://github.com/facebook/zstd)
- [Git Orphan Branches](https://graphite.dev/guides/git-orphan-branches)
## Post-Execution Reflection
After this skill completes, reflect before closing the task:
0. **Locate yourself.** — Find this SKILL.md's canonical path before editing.
1. **What failed?** — Fix the instruction that caused it.
2. **What worked better than expected?** — Promote to recommended practice.
3. **What drifted?** — Fix any script, reference, or dependency that no longer matches reality.
4. **Log it.** — Evolution-log entry with trigger, fix, and evidence.
Do NOT defer. The next invocation inherits whatever you leave behind.
© terrylica · MIT · terrylica/cc-skills