zipsa
westbrookai/zipsa
Lightweight runtime container for AI agents (Claude Code, Codex, Gemini CLI) with MCP support
Instalação
npx convez-ai westbrookai/zipsa1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Zipsa
Runtime-agnostic SKILL execution system for AI agents
Zipsa is a complete ecosystem for developing and executing SKILL-based AI agents. It provides isolated Docker runtime, multi-runtime launcher, and a skill library.
Architecture
┌─────────────────────────────────────────────────────────┐
│ Zipsa Ecosystem │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌───────────┐ │
│ │ Runtime │ │ Launcher │ │ Skills │ │
│ │ (Docker) │ │ (Python) │ │ Library │ │
│ │ │ │ │ │ │ │
│ │ • Claude Code│◄──│ • CLI Tool │◄──│ • Manifests│ │
│ │ • Codex │ │ • Executor │ │ • SKILL.md│ │
│ │ • Gemini │ │ • MCP Config │ │ • Examples│ │
│ └──────────────┘ └──────────────┘ └───────────┘ │
│ │
└─────────────────────────────────────────────────────────┘
Components
1. Runtime (runtime/)
Lightweight Docker image providing isolated execution environment:
- Pre-installed: Claude Code, Codex, Gemini CLI
- Multi-architecture (amd64, arm64)
- 1.9GB image size (54.9% reduction)
Quick Start:
docker pull ghcr.io/westbrookai/zipsa-runtime:latest
docker run -it --rm -v $(pwd):/workspace ghcr.io/westbrookai/zipsa-runtime:latest claude
2. Launcher (launcher/)
Python CLI for orchestrating skill execution:
- Multi-runtime support (claude, codex, gemini)
- SKILL manifest validation
- MCP server support (npx, uvx, pipx)
- Environment variable management
- Execution logging and metrics
Quick Start:
cd launcher
uv pip install -e ".[dev]"
zipsa run ../skills/daily-progress "summarize today's work"
3. Skills (skills/)
Collection of reusable SKILL definitions:
daily-progress: Summarize Claude Code sessions and log to Notion- More coming soon...
Quick Start:
cd skills/daily-progress
cat manifest.yaml # View skill definition
Quick Start (Full Stack)
-
Pull Runtime:
docker pull ghcr.io/westbrookai/zipsa-runtime:latest -
Install Launcher:
cd launcher uv pip install -e ".[dev]" -
Configure Runtime:
cp launcher/runtime-config.yaml.example ~/.zipsa/runtime-config.yaml # Edit ~/.zipsa/runtime-config.yaml and add your tokens -
Run a Skill:
zipsa run skills/daily-progress "summarize today's work"
Development
Each component has its own development guide:
- Runtime: runtime/CLAUDE.md - Dockerfile, hadolint, integration tests
- Launcher: launcher/CLAUDE.md - Python, uv, pytest, TDD
- Skills: skills/README.md - Manifest format, SKILL.md syntax
Common Principles (All Components):
- ✅ TDD Required: Write tests first
- ✅ English Only: All code, comments, docs in English
- ✅ Conventional Commits:
feat:,fix:,docs:, etc. - ✅ Branch Strategy: Feature branches, PR to main
Repository Structure
zipsa/
├── runtime/ # Docker runtime environment
│ ├── Dockerfile
│ ├── CLAUDE.md # Development guide
│ └── README.md # Usage documentation
│
├── launcher/ # Python CLI orchestrator
│ ├── zipsa/ # Python package
│ ├── tests/
│ ├── CLAUDE.md # Development guide
│ └── README.md # Usage documentation
│
├── skills/ # SKILL library
│ ├── daily-progress/
│ └── README.md # Authoring guide
│
├── examples/ # Docker Compose examples
│ └── minimal-agent/
│
└── docs/ # Design documents
└── zipsa-python-design.md
Use Cases
Scenario 1: Daily Progress Logging
# Automatically summarize today's Claude Code work and log to Notion
zipsa run skills/daily-progress "log today's progress"
Scenario 2: Custom SKILL Development
# Create new skill
cd skills
mkdir my-skill
# ... create manifest.yaml and SKILL.md
zipsa validate my-skill
zipsa run my-skill "test query"
Scenario 3: Multi-Runtime Testing
# Test skill on different runtimes
zipsa run my-skill "query" --runtime claude
zipsa run my-skill "query" --runtime codex
zipsa run my-skill "query" --runtime gemini
Roadmap
- Runtime: Docker image with Claude Code, Codex, Gemini
- Runtime: Multi-architecture builds (amd64, arm64)
- Runtime: Image size optimization (1.9GB)
- Launcher: Python CLI with manifest validation
- Launcher: Runtime config system
- Launcher: MCP server environment management
- Launcher: Execution logging and metrics
- Skills: daily-progress (Notion integration)
- Skills: More example skills
- Launcher: Skill dependency management
- Runtime: Security hardening (non-root user)
- Runtime: Container signing and verification
Contributing
We welcome contributions! Please read the development guide for your target component:
- Choose component: runtime/, launcher/, or skills/
- Read the development guide
- Create feature branch:
dev/your-feature - Write tests first (TDD)
- Submit PR to
main
License
MIT License - see LICENSE file for details
Support
- Issues: GitHub Issues
- Documentation:
- Runtime: runtime/README.md
- Launcher: launcher/README.md
- Skills: skills/README.md