Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add terrylica/cc-skills --skill asciinema-streaming-backup -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/asciinema-streaming-backup/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/asciinema-streaming-backup/

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

Similar skills

All skills for Git and GitHub →

From the same set79

The whole set →
doppler-workflows The doppler-workflows skill guides commands that use Doppler secrets for Python package publishing and AWS tasks. It also covers common authentication errors. CX Codex +1 130installs ml-data-pipeline-architecture The ml-data-pipeline-architecture skill covers ML data pipelines built with Polars, Arrow, and ClickHouse. Use it to choose between Polars and Pandas or prepare data for PyTorch. CX Codex +1 130installs clickhouse-pydantic-config clickhouse-pydantic-config turns Pydantic v2 ClickHouse models and environment variables into a DBeaver connection file. Handy when one repo talks to both a local and a cloud database. CX Codex +1 130installs issue-create issue-create turns a rough description into a formatted GitHub issue: detects the type, picks labels that exist in the repo, and warns about duplicates before you post. CX Codex +1 129installs multi-agent-e2e-validation The multi-agent-e2e-validation skill for Claude Code and other AI editors spawns multiple validation agents in parallel to test database refactors comprehensively. CX Codex +1 128installs link-validator The link-validator skill detects absolute paths in markdown links that break when a skill is installed elsewhere. Run it before sharing a skill or after adding new links. CX Codex +1 127installs session-info session-info returns the active Claude Code session UUID and session chain cache details. Helpful for debugging and linking transcripts to sessions. CX Codex +1 127installs asciinema-analyzer The asciinema-analyzer skill searches asciinema text recordings for keywords, commands, errors, and patterns. Use it when reviewing terminal session history. CX Codex +1 127installs

Project sponsors

Companies that keep this analytics open