SNACK

中文文档 | Documentation

SNACK is a generic CLI runtime for packaging, scheduling, and running portable tasks from any compatible host CLI or agent runner.

A snack is packaged as a .snack archive with a SNACK.md manifest and an internal Python entry script. Users do not call the internal entry directly. The host invokes the snack runtime, and the runner executes the entry in a controlled environment with inputs, context, output capture, scheduling, and dependency setup.

Highlights

• Stable JSON discovery endpoints for host CLIs.
• Portable .snack archives built from source directories.
• Cron-based scheduled runs and one-off execution.
• Per-snack dependency declarations with isolated cached environments.
• Small SDK for inputs, context paths, JSON output, and host-provided LLM calls.
• Host-neutral protocol that is not tied to a single AI CLI.

Quick Start

SNACK requires Python 3.10 or newer and uv.

From this repository's upload/ directory:

uv run snack version --json
uv run snack capabilities --json
uv run snack schema manifest --json

Create, package, and run a snack:

uv run snack init hello --dir workspace
uv run snack pack workspace/hello --output workspace/images
uv run snack list workspace --json
uv run snack run --once hello workspace --json

Run the test suite:

uv run --extra dev pytest

Manifest

Every snack source directory contains a SNACK.md file:

---
name: hello-world
version: 0.1.0
description: Minimal SNACK example.
entry: scripts/run.py
requires:
  llm: none
  dependencies: []
---

# Hello World

The entry path is internal to the snack package. It is executed only by the runner after archive extraction and validation.

See the manifest reference for all supported fields.

Dependency Policy

Each snack may declare its own dependencies through requires.dependencies in SNACK.md or through a packaged requirements.txt file. When dependencies are present, SNACK creates or reuses a cached virtual environment for that snack and executes the entry script with that environment's Python.

requirements.txt takes priority when the same package is also listed in the manifest. See the dependency policy for details.

Host CLI Integration

The public integration surface is the snack command:

snack capabilities --json
snack schema manifest --json
snack version --json
snack pack FOLDER --json
snack run [SNACKS_DIR] --json
snack run --once NAME [SNACKS_DIR] --json

Host tools should use the JSON endpoints instead of importing runtime internals. See the host protocol.

Documentation

• Getting started
• Concepts
• Manifest reference
• CLI reference
• SDK reference
• Dependency policy
• Host protocol
• Development
• Troubleshooting

Chinese documentation is available under docs/cn.

Project Status

SNACK is currently an alpha runtime. The CLI discovery protocol is the intended integration boundary for hosts. Internal Python modules may change faster than the CLI protocol.

License

Apache-2.0. See LICENSE.