OpenBox for AI Agents — pip install samai-openbox

Install

One pip command. Works on Python 3.8+. Bundles a static OpenBox binary so there are no system dependencies.

# Standard install
pip install samai-openbox

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

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

The package ships a statically-linked OpenBox binary for Windows, macOS and Linux. No Go toolchain, no Fyne, no GUI dependencies — just the CLI engine.

Why a Python wrapper for AI agents?

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

🧠

One verb, one syntax

Every archive operation is samai-openbox <verb> <files...>. The agent doesn't have to remember whether 7z uses a or c, whether tar needs -z or -j, or whether rar is even installed.

📦

Self-contained binary

The pip wheel bundles a static OpenBox binary for the host platform. No system zip/tar/7z needed — useful inside minimal Docker images and CI runners.

🔒

Path-traversal safe

The same engine-level protection that the GUI app has: malicious archives with ../../etc/passwd entries are blocked at extraction time. Safe to point at untrusted downloads.

⚡

Zero startup cost

Static Go binary, no Python runtime in the hot path. samai-openbox --version runs in ~10ms. Big archives are processed at the speed of the underlying Go archive libraries.

🧩

JSON output mode

Pass --json and every command emits machine-parseable JSON on stdout. Perfect for agent reasoning loops: list an archive, decide what to extract, verify the result.

🎯

Stable, documented CLI

Verbs and flags are versioned with semver. We won't rename compress to pack in a minor release. Agents can rely on the skill spec for years.

The CLI in 60 seconds

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

Compress files into an archive

# Compress files / folders into a new archive
# Format auto-detected from output extension: .zip .tar .tar.gz .7z
samai-openbox compress report.pdf photos/ -o backup.zip

# Force a specific format and compression level (0-9)
samai-openbox compress src/ -o release.tar.gz --level 9

# 7z compression (requires 7-Zip CLI on PATH)
samai-openbox compress bigfile.bin -o archive.7z

Extract an archive

# Extract to a directory (auto-created if missing)
samai-openbox extract backup.zip -d ./restored

# Works for every supported format: zip, tar, tar.gz, 7z, rar, iso
samai-openbox extract legacy.rar -d ./legacy
samai-openbox extract cd-image.iso -d ./cd-contents

List archive contents (JSON)

# Human-readable list
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

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

# Useful in CI: check every archive in a folder
for f in *.zip *.tar.gz *.7z; do
  samai-openbox test "$f" || echo "CORRUPT: $f"
done

Show version & supported formats

samai-openbox --version
# openbox 0.4.2 (samai-openbox wrapper 0.1.0)
# platform: linux/amd64 · go1.23.4

samai-openbox formats
# FORMAT   COMPRESS  EXTRACT  NOTES
# zip      yes       yes      deflate or store
# tar      yes       yes      stdlib
# tar.gz   yes       yes      5 levels
# 7z       yes*      yes      *write needs 7z CLI
# rar      no        yes      read-only
# iso      no        yes      read-only

ClawHub Skill Spec

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

# skill.yaml — register samai-openbox as an agent skill
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 &&

Agent Conversation Example

What it looks like when an LLM agent uses OpenBox to package up a project for delivery.

👤 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?

Give Your Agent Archive Skills