convez.ai
MCP Server
westbrookai

zipsa

westbrookai/zipsa

Ver no GitHub
InicialPluginScore · de 0 a 100

Lightweight runtime container for AI agents (Claude Code, Codex, Gemini CLI) with MCP support

Instalação

$npx convez-ai westbrookai/zipsa

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
50%
Último commit
há 5 meses
Versão
launcher-v0.1.5
Issues abertas
8
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Zipsa

Runtime-agnostic SKILL execution system for AI agents

License: MIT

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

📚 Runtime Documentation


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"

📚 Launcher Documentation


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

📚 Skills Documentation


Quick Start (Full Stack)

  1. Pull Runtime:

    docker pull ghcr.io/westbrookai/zipsa-runtime:latest
    
  2. Install Launcher:

    cd launcher
    uv pip install -e ".[dev]"
    
  3. Configure Runtime:

    cp launcher/runtime-config.yaml.example ~/.zipsa/runtime-config.yaml
    # Edit ~/.zipsa/runtime-config.yaml and add your tokens
    
  4. Run a Skill:

    zipsa run skills/daily-progress "summarize today's work"
    

Development

Each component has its own development guide:

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:

  1. Choose component: runtime/, launcher/, or skills/
  2. Read the development guide
  3. Create feature branch: dev/your-feature
  4. Write tests first (TDD)
  5. Submit PR to main

License

MIT License - see LICENSE file for details


Support

Ver o original no GitHub

Bom para

Relacionados