Skip to main content

snow-agent

Cross-device command execution and agent orchestration CLI.

snow-agent 把目标设备(host)与可复用命令(command)作为确定性资源管理:先注册可通过 SSH 访问的目标设备,再在本地或目标机上执行命令,直接复用目标机用户的登录态与业务凭据,不复制私钥或业务令牌。跨 Agent 任务委派(delegate/task/daemon)把开发方案交给执行设备上的原生编码 Agent(Codex / OpenCode / Claude Code / Antigravity CLI / ZCode)持久执行:同项目任务 FIFO 串行,Snow 独立验证并受控提交。定时调度(job)、配置管理(config)、环境检查(doctor)、MCP 接入与 Snow 自有 Agent Loop 在 docs 中规划,随迭代交付。

安装

需要 Python >= 3.10,无第三方运行时依赖:

uvx snow-agent --version       # 免安装直接运行(uv)
pipx install snow-agent        # 独立环境常规安装
pip install snow-agent         # 装入当前环境

开发安装:克隆仓库后 pip install -e .。

安装后获得 snow-agent 命令入口;uvx snow-agent 无需安装即可使用全部子命令。

当前可用命令

完整调用说明(参数、工作流、JSON 字段与错误恢复)见 docs/cli-usage.md;本节只列命令速览。

snow-agent help [COMMAND...]        # 分层帮助;--format json 输出同源的结构化能力描述
snow-agent init                     # 初始化用户级配置
snow-agent host add|list|show|test|remove          # 目标设备注册与 SSH 连通性检查
snow-agent command add|list|show|check|run|remove  # 可复用命令注册、检查与执行
snow-agent exec [--host HOST] [--cwd PATH] [--timeout DURATION] -- COMMAND [ARGS...]
snow-agent delegate submit|targets  # 把开发方案提交给原生编码 Agent 持久执行
snow-agent task list|show|cancel|resume|report     # 委派任务的查询、取消、恢复与阶段上报
snow-agent daemon start|stop|status # 任务调度守护进程(单实例)

无参数调用 snow-agent 预留给未来的交互式 TUI,当前降级为输出根帮助。

job、config、doctor、mcp、agent 已在命令树中声明但尚未实现,调用返回结构化 not_available 错误。_rpc 是委派传输经 SSH 调用的内部入口,不面向日常调用。

根级支持 snow-agent --version:文本模式输出一行 snow-agent 0.1.0;--json 输出 {"schema_version":1,"kind":"version","version":"0.1.0"}。该选项仅在根级可用。

退出码:确认的业务退出码原样保留;Snow 自身失败为 1;超时或中断等结果不确定的情况为 2。

文本模式(无 --json)下,远端执行的输出剥离 snow-agent 控制记录后逐块实时转发到本进程 stdout/stderr,不等待命令结束;--json 时 stdout 只有一个结果对象,字段契约见 snow-agent exec --help。

配置存储在 ~/.snow-agent/(目录 0700、文件 0600、原子写入),用环境变量 SNOW_AGENT_CONFIG_DIR 可指定其他位置。

快速上手

本地执行,无需任何配置:

snow-agent exec -- git status

跨设备执行(备用机调用主力机上已登录的业务 CLI):

snow-agent host add main --ssh user@192.168.1.10   # 注册目标设备,认证沿用标准 SSH 配置
snow-agent host test main                          # 检查连接、认证与目标执行环境
snow-agent exec --host main -- meishi unread       # 在目标机上执行一次

对需要反复调用的 CLI,注册为可复用命令:

snow-agent command add meishi --host main --bin /opt/homebrew/bin/meishi
snow-agent command check meishi
snow-agent command run meishi -- unread

跨设备委派在项目所在设备执行(--host 指定,默认 local);方案文件在调用端读取,以不可变快照传输。执行设备需先启动调度进程:

snow-agent daemon start                                             # 在执行设备上启动任务调度
snow-agent delegate targets                                         # 查看当前设备可用的委派目标(codex / opencode / claude-code / antigravity / zcode)
snow-agent delegate submit --cwd /workspace/repo --agent codex --file ./plans/B.md
snow-agent task show <task_id>                                      # 轮询阶段、验证结论与提交哈希

submit 立即返回任务 ID;执行设备上的队列、Agent 轮次、独立验证与受控提交在调用方离线后继续。同项目任务按提交顺序串行,失败或状态不明的任务阻塞后续任务,处理后用 task resume 恢复。跨设备查询与提交经 SSH 短请求转发到执行设备,方案文件在调用端读取后以不可变快照传输。

取消、恢复、崩溃续接与各阶段上报语义,以及全部命令的参数、JSON 字段和错误处理,见 docs/cli-usage.md。

每个命令都有分层 --help;外部 Agent 无需预置专属 Skill,仅凭逐级帮助与结构化结果即可完成配置、检查、执行和错误恢复。

Metadata

Release files for snow-agent 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for snow-agent 0.1.0
File Size Uploaded Provenance Actions
snow_agent-0.1.0.tar.gz 145.6 kB Without provenance Details for snow_agent-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for snow-agent 0.1.0
File Interpreter ABI Platform Actions
snow_agent-0.1.0-py3-none-any.whl Python 3 none any Details for snow_agent-0.1.0-py3-none-any.whl

Total release size: 263.1 kB

Release files / snow_agent-0.1.0.tar.gz

Download URL snow_agent-0.1.0.tar.gz
Size 145.6 kB
Tags Source
SHA-256 checksum
How to use checksums
98cd78e4362d8e9d4e2d15fbd4520d5c7ecb51fde4d7d72afc1dea07d0acd7e1
BLAKE2b-256 checksum
How to use checksums
2a00754e7ee409dbc2bdaae833ad6ab6edbf1f872d55c59b7a6c225c9cbbe25f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Release files / snow_agent-0.1.0-py3-none-any.whl

Download URL snow_agent-0.1.0-py3-none-any.whl
Size 117.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a9ee9ead72c74fe083d7af51674f3fb10f6e1061092d8422517a8baaff44c672
BLAKE2b-256 checksum
How to use checksums
1392afb7c9eb974e7887f2b783020666c3da25dbd91d31b98786d868a683b24b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.13

Security for snow-agent 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page