samai-openbox 0.2.0

CLI archive skill for AI agents — compress and extract zip, tar, tar.gz, 7z, rar, iso from one stable command. Part of the OpenBox project.

samai-openbox

CLI archive skill for AI agents — one stable command to compress and extract every common archive format.

samai-openbox is a tiny, dependency-light Python package that exposes the OpenBox archiver engine as a single CLI command — samai-openbox — so any LLM agent with shell access can compress and extract archives without remembering six different flag syntaxes.

Why does this exist?

LLM agents are great at writing shell commands, but they consistently get archive syntax wrong. One stable CLI fixes that:

• tar -czvf vs tar -xzvf vs 7z a vs 7z x vs zip -r vs unzip — agents hallucinate.
• Path-traversal protection varies by tool. OpenBox blocks ../../etc/passwd-style entries at extraction time.
• JSON output mode lets agents parse archive contents in their reasoning loop.

Install

# Standard
pip install samai-openbox

# Or with pipx (recommended for isolated CLI tools)
pipx install samai-openbox

# Verify
samai-openbox --version
samai-openbox --help

Works on Python 3.8+. Pure-Python implementation using stdlib zipfile and tarfile; shells out to the system 7z / 7zz / 7za for 7z, and unrar for rar (only if those formats are actually used).

The CLI in 60 seconds

Five verbs cover everything an agent needs to do with archives.

Compress files into an archive

# Auto-detects format from output extension: .zip .tar .tar.gz .7z
samai-openbox compress report.pdf photos/ -o backup.zip

# Force compression level (0-9, default 6)
samai-openbox compress src/ -o release.tar.gz --level 9

# 7z compression (requires 7z/7zz/7za on PATH)
samai-openbox compress bigfile.bin -o archive.7z

Extract an archive

# Auto-creates destination if missing
samai-openbox extract backup.zip -d ./restored

# Works for every supported format
samai-openbox extract legacy.rar -d ./legacy
samai-openbox extract cd-image.iso -d ./cd-contents

List archive contents

# Human-readable
samai-openbox list backup.zip

# Machine-readable JSON — perfect for agent reasoning
samai-openbox list backup.zip --json

Example JSON output:

{
  "archive": "backup.zip",
  "format": "zip",
  "entries": [
    {"name": "report.pdf",   "size": 2516582, "modified": "2024-08-15T10:23:00Z"},
    {"name": "photos/",      "size": 0,       "modified": "2024-08-15T10:24:00Z", "is_dir": true},
    {"name": "photos/01.jpg", "size": 4409111, "modified": "2024-08-14T18:11:00Z"}
  ]
}

Test archive integrity

# Verifies CRCs without extracting — exits non-zero on corruption
samai-openbox test backup.zip

Show version & supported formats

samai-openbox --version
samai-openbox formats

Format support matrix

Format	Compress	Extract	Notes
zip	✓	✓	stdlib zipfile, deflate or store
tar	✓	✓	stdlib tarfile
tar.gz	✓	✓	tarfile + gzip, 5 levels
7z	✓*	✓*	requires 7z / 7zz / 7za on PATH
rar	—	✓*	requires unrar on PATH
iso	—	✓*	requires 7z (handles ISO 9660)

* = via external CLI. Install with:

• 7-Zip: https://www.7-zip.org/download.html (Windows) · brew install 7zip (macOS) · sudo apt install p7zip-full (Linux)
• unrar: https://www.rarlab.com/rar_add.htm (Windows) · brew install unrar (macOS) · sudo apt install unrar (Linux)

Path-traversal safety

extract blocks any archive entry whose absolute path would escape the target directory. So an archive containing ../../etc/passwd extracts the file into <target>/etc/passwd instead of /etc/passwd. Safe to point at untrusted downloads.

ClawHub skill spec

Drop this into your agent's skill catalog so it knows when and how to call OpenBox:

# skill.yaml
name: openbox-archive
version: 0.1.0
description: Compress and extract archives (zip, tar, tar.gz, 7z, rar, iso)
command: samai-openbox
install: pip install samai-openbox
verbs:
  - name: compress
    usage: samai-openbox compress <files...> -o <archive> [--level 0-9]
    formats_out: [zip, tar, tar.gz, 7z]
  - name: extract
    usage: samai-openbox extract <archive> -d <dir>
    formats_in: [zip, tar, tar.gz, 7z, rar, iso]
  - name: list
    usage: samai-openbox list <archive> [--json]
  - name: test
    usage: samai-openbox test <archive>
safety:
  - Extraction blocks path-traversal entries (../../etc/passwd)
  - No network calls · no telemetry · no auto-update
  - Exits non-zero on any error — safe to chain with &&

Use as a Python module

from samai_openbox import compress, extract, list_archive, test_archive

# Compress
compress(["report.pdf", "photos/"], "backup.zip", level=6)

# Extract (path-traversal safe)
extract("backup.zip", "./restored")

# List (returns a list of dicts)
entries = list_archive("backup.zip")
for e in entries:
    print(e["name"], e["size"], e.get("modified"))

# Verify integrity
ok = test_archive("backup.zip")

Agent conversation example

User: Pack the reports/ folder into a .zip for email, but skip anything larger than 10 MB. Then list what's in the archive so I can sanity-check.

Agent (using samai-openbox):

# 1. Find files under 10 MB in reports/
find reports/ -type f -size -10M -print0 | \
  xargs -0 samai-openbox compress -o reports-email.zip

# 2. List the result as JSON for verification
samai-openbox list reports-email.zip --json

Done. reports-email.zip contains 23 files totalling 47.2 MB (after compression from 89.4 MB). Three files over 10 MB were excluded: reports/q3-raw-data.csv, reports/audit-full.pdf, and reports/appendix-exhibits.pptx. Want me to send them separately as a .tar.gz?

License

MIT — same as the OpenBox desktop app. See LICENSE.

See also

• OpenBox desktop app — graphical archiver for Windows / macOS / Linux: https://openbox.samai.cc
• Source code — https://github.com/samaidev/openbox
• SamAI Group public-welfare projects — https://samai.cc#public-welfare

OpenBox is a SamAI Group public-welfare open-source project. Free, forever.