oneshot CLI
Ship code with a single command. oneshot runs a full pipeline: plan (Claude) → execute (Codex) → review (Codex) → PR (Claude). Works over SSH to a remote server or locally with --local.
When to use this skill
- - User wants to ship a code change to a repository without manual coding
- User wants to automate the plan/implement/review/PR workflow
- User mentions "oneshot" or wants to delegate a coding task
- User wants to run a task on a remote server or locally
Installation
CODEBLOCK0
Setup
Run oneshot init to configure SSH host, workspace path, API keys, and model preferences. Config is saved to ~/.oneshot/config.json.
Repos on the server should live as <org>/<repo> under the workspace path:
CODEBLOCK1
Server prerequisites
Usage
CODEBLOCK2
Pipeline
- 1. Validate: checks the repo exists, fetches latest from origin
- Worktree: creates a temp git worktree from the target base branch
- Classify: classifies the task as
fast or deep via heuristics + LLM - Plan: Claude reads the codebase and CLAUDE.md conventions, outputs an implementation plan
- Execute: Codex implements the plan. If it times out with partial changes, the pipeline continues
- Draft PR: Claude creates a branch, commits, pushes, and opens a draft PR
- Review: Codex reviews the diff. In
deep mode it runs an exhaustive review across correctness, security, and code quality - Finalize: pushes review fixes and marks the PR ready
Worktree is cleaned up after every run.
Configuration
INLINECODE9 :
CODEBLOCK3
Only host is required for SSH runs. Local mode works without a config file.
Flags
| Flag | Short | Description |
|---|
| INLINECODE11 | INLINECODE12 | Override Claude model |
| INLINECODE13 |
-b | Base branch (default: main) |
|
--deep-review | | Force exhaustive review mode |
|
--local | | Run locally instead of over SSH |
|
--bg | | Run in background, return PID + log path |
|
--dry-run |
-d | Validate only |
|
--events-file | | Mirror JSONL events to an additional file |
|
--help |
-h | Help |
|
--version |
-v | Version |
Customization
- - Put a
CLAUDE.md in any repo root. oneshot passes it to Claude and Codex at every step - Edit
prompts/plan.txt, execute.txt, review.txt, pr.txt to change pipeline behavior
Tips
- - Use
--bg to fire and forget long tasks - Linear integration moves tickets to "In Review" and comments the PR URL
- Per-step timeouts prevent runaway processes (plan 20m, execute 60m, review 20m, PR 20m)
- Worktree isolation means your main branch is never touched
- Task classification picks
fast or deep mode automatically. Use --deep-review to force deep - Duration estimates come from historical runs per repo (
~/.oneshot/history.json)
oneshot CLI
一条命令即可交付代码。oneshot 运行完整的流水线：规划（Claude）→ 执行（Codex）→ 审查（Codex）→ PR（Claude）。支持通过 SSH 连接到远程服务器，或使用 --local 在本地运行。
何时使用此技能
- - 用户希望无需手动编码即可向仓库交付代码变更
- 用户希望自动化规划/实现/审查/PR 工作流
- 用户提到 oneshot 或希望委托编码任务
- 用户希望在远程服务器或本地运行任务
安装
bash
bun install -g oneshot-ship
设置
运行 oneshot init 配置 SSH 主机、工作空间路径、API 密钥和模型偏好。配置保存在 ~/.oneshot/config.json。
服务器上的仓库应位于工作空间路径下的 <组织>/<仓库> 格式：
~/projects/
my-org/my-app/
my-org/my-api/
服务器前提条件
用法
bash
oneshot <仓库> <任务> # 交付一个任务
oneshot <仓库> # 从 Linear 工单交付
oneshot <仓库> <任务> --bg # 触发后即忘
oneshot <仓库> <任务> --local # 本地运行，不使用 SSH
oneshot <仓库> <任务> --deep-review # 强制全面审查
oneshot <仓库> <任务> --model sonnet # 覆盖 Claude 模型
oneshot <仓库> <任务> --branch dev # 指定不同分支
oneshot <仓库> --dry-run # 仅验证
oneshot init # 配置
oneshot stats # 最近运行记录 + 耗时
流水线
- 1. 验证：检查仓库是否存在，从源拉取最新代码
- 工作树：从目标基础分支创建临时 git 工作树
- 分类：通过启发式规则 + LLM 将任务分类为 fast 或 deep
- 规划：Claude 读取代码库和 CLAUDE.md 约定，输出实现计划
- 执行：Codex 实现计划。如果超时且仅完成部分更改，流水线继续执行
- 草稿 PR：Claude 创建分支、提交、推送并打开草稿 PR
- 审查：Codex 审查差异。在 deep 模式下，对正确性、安全性和代码质量进行全面审查
- 完成：推送审查修复并将 PR 标记为就绪
每次运行后清理工作树。
配置
~/.oneshot/config.json：
json
{
host: user@100.x.x.x,
basePath: ~/projects,
anthropicApiKey: sk-ant-...,
linearApiKey: linapi...,
claude: { model: opus, timeoutMinutes: 180 },
codex: {
model: gpt-5.4-mini,
reasoningEffort: xhigh,
reviewModel: gpt-5.4-mini,
reviewReasoningEffort: xhigh,
timeoutMinutes: 180
},
stepTimeouts: {
planMinutes: 20,
executeMinutes: 60,
reviewMinutes: 20,
deepReviewMinutes: 20,
prMinutes: 20
}
}
SSH 运行仅需 host 字段。本地模式无需配置文件。
标志
| 标志 | 缩写 | 描述 |
|---|
| --model | -m | 覆盖 Claude 模型 |
| --branch |
-b | 基础分支（默认：main） |
| --deep-review | | 强制全面审查模式 |
| --local | | 本地运行而非通过 SSH |
| --bg | | 后台运行，返回 PID + 日志路径 |
| --dry-run | -d | 仅验证 |
| --events-file | | 将 JSONL 事件镜像到额外文件 |
| --help | -h | 帮助 |
| --version | -v | 版本 |
自定义
- - 在任何仓库根目录放置 CLAUDE.md。oneshot 会在每个步骤将其传递给 Claude 和 Codex
- 编辑 prompts/plan.txt、execute.txt、review.txt、pr.txt 以更改流水线行为
提示
- - 使用 --bg 触发后即忘长时间运行的任务
- Linear 集成将工单移至审查中状态并评论 PR 链接
- 每步超时防止进程失控（规划 20 分钟，执行 60 分钟，审查 20 分钟，PR 20 分钟）
- 工作树隔离确保主分支永远不会被触及
- 任务分类自动选择 fast 或 deep 模式。使用 --deep-review 强制深度模式
- 耗时估算来自每个仓库的历史运行记录（~/.oneshot/history.json）
