Oneshot Ship

Other

Ship code with oneshot CLI. One command that plans, executes, reviews, and opens a PR. Runs over SSH or locally. Use when the user wants to ship code changes, automate PRs, or run a coding pipeline with Codex or Claude.

Install

openclaw skills install oneshot-ship

oneshot CLI

Ship code with a single command. oneshot is an agentic software workflow runtime: repo + task in, isolated agent run out, reviewed PR ready. It runs with one selected fallback provider, or with invisible adaptive routing when routing.enabled is true. The router chooses Codex or Claude plus reasoning effort, while each provider stays on its configured frontier model. 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

bun install -g oneshot-ship

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:

~/projects/
  my-org/my-app/
  my-org/my-api/

Server prerequisites

Bun
Either Codex CLI or Claude Code CLI
GitHub CLI (authenticated)
OPENAI_API_KEY for Codex mode, or ANTHROPIC_API_KEY for Claude mode

Usage

oneshot <repo> "<task>"                 # ship a task
oneshot <repo> <linear-url>            # ship from a Linear ticket
oneshot <repo> "<task>" --bg           # fire and forget
oneshot <repo> "<task>" --local        # run locally, no SSH
oneshot <repo> "<task>" --mode deep    # skip classification and force deep mode
oneshot <repo> "<task>" --workflow ship # apply a workflow preset
oneshot <repo> "<task>" --deep-review  # force exhaustive review
oneshot <repo> "<task>" --model gpt-5.5 # override configured plan/PR model
oneshot <repo> "<task>" --branch dev   # target a different branch
oneshot <repo> "<task>" --base-path /srv/workspaces  # override repo root for this run
oneshot <repo> "<task>" --worktree-root /tmp/agents   # override temp worktree root
oneshot route "fix failing CI and publish" --json # inspect invisible route
oneshot <repo> --dry-run               # validate only
oneshot init                           # configure
oneshot stats                          # recent runs + timing
oneshot runs                           # durable run ledger
oneshot runs --json --limit 10         # list runs for automation
oneshot status <run-id|events-file> --json  # inspect one run
oneshot eval --json                    # summarize outcomes
oneshot workflow list                  # inspect workflow presets
oneshot workflow show fix-ci --json    # inspect one workflow preset
oneshot policy init                    # create .oneshot/policy.json
oneshot policy init --path ./repo      # write policy in another directory
oneshot mcp serve                      # expose MCP tools over stdio
oneshot doctor                         # package, tool, SSH, and event health
oneshot doctor --repo zkp2p/pay        # health plus checkout existence

Pipeline

Validate: checks the repo exists, fetches latest from origin
Worktree: creates a temp git worktree from the target base branch
Route: oneshot's adaptive router chooses provider, reasoning effort, context shape, execution style, verification profile, and fast/deep mode
Plan: routed agent reads the codebase plus AGENTS.md/CLAUDE.md instructions, package scripts, policy packs, and relevant docs, then outputs an implementation plan
Execute: routed agent implements the plan. If it times out with partial changes, the pipeline continues
Draft PR: configurable agent creates a branch, commits, and writes PR metadata; the runtime pushes and opens or updates the draft PR
Review: configurable agent reviews the diff across correctness, compatibility, runtime contracts, policy, security, docs quality, and simplicity. Confirmed issues are fixed directly
Finalize: runtime pushes review fixes and marks the PR ready, or preserves the draft if review fails/times out

Every run writes JSONL events to /tmp/oneshot-<runId>.events.jsonl and mirrors them into ~/.oneshot/runs/<runId>.events.jsonl. Worktrees are cleaned up after successful runs and preserved on failure for recovery.

Configuration

~/.oneshot/config.json:

{
  "host": "user@100.x.x.x",
  "basePath": "~/projects",
  "provider": "codex",
  "routing": { "enabled": true },
  "linearApiKey": "lin_api_...",
  "claude": { "model": "opus", "timeoutMinutes": 180 },
  "codex": {
    "model": "gpt-5.5",
    "reasoningEffort": "xhigh",
    "reviewModel": "gpt-5.5",
    "reviewReasoningEffort": "xhigh",
    "timeoutMinutes": 180
  },
  "phases": {
    "classify": { "model": "gpt-5.5", "reasoningEffort": "medium" },
    "plan": { "model": "gpt-5.5", "reasoningEffort": "xhigh" },
    "execute": { "model": "gpt-5.5", "reasoningEffort": "xhigh" },
    "review": { "model": "gpt-5.5", "reasoningEffort": "xhigh" },
    "deepReview": { "model": "gpt-5.5", "reasoningEffort": "xhigh" },
    "pr": { "model": "gpt-5.5", "reasoningEffort": "high" }
  },
  "stepTimeouts": {
    "planMinutes": 20,
    "executeMinutes": 60,
    "reviewMinutes": 20,
    "deepReviewMinutes": 20,
    "prMinutes": 20
  }
}

Only host is required for SSH runs. Local mode works without a config file. Remote SSH runs stream the active oneshot config to the server for that run, so basePath, provider defaults, timeout settings, and configured Linear credentials stay aligned even if the server does not have its own oneshot config file.

Flags

Flag	Short	Description
`--model`	`-m`	Override configured plan/PR model
`--branch`	`-b`	Base branch (default: main)
`--base-path`		Override the workspace path used to locate the repo
`--worktree-root`		Override where temporary git worktrees are created
`--mode`		Skip classification and force `fast` or `deep` mode
`--workflow`		Apply a workflow preset: `ship`, `review`, `fix-ci`, `research`, `docs`, or `swarm-review`
`--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
`--repo`		With `doctor`, verify a specific `owner/repo` checkout exists
`--provider`		With `route`, choose the fallback provider (`codex` or `claude`)
`--help`	`-h`	Help
`--version`	`-v`	Version

Customization

Put an AGENTS.md or CLAUDE.md in any repo root. oneshot passes the instruction snapshot to the configured agents, and the prompts ask agents to inspect relevant local instruction files directly
Choose provider: "codex" or provider: "claude" as the fallback. Set routing.enabled: true when oneshot's adaptive router should silently pick Codex or Claude per task
Configure claude.model and codex.model as the frontier models for each provider. Adaptive routing varies effort and provider, not model class
Configure phases.classify, phases.plan, phases.execute, phases.review, phases.deepReview, and phases.pr for model and reasoning defaults when routing is disabled
Edit prompts/plan.txt, execute.txt, review.txt, pr.txt to change pipeline behavior
Use oneshot policy init to add .oneshot/policy.json with protected paths, required checks, approval-sensitive keywords, and secret-pattern gates
Use oneshot mcp serve when another agent should call oneshot through tools instead of shelling out ad hoc
For dense specs, explainers, review maps, incident reports, design sheets, or one-off editors, oneshot can create a self-contained HTML artifact instead of a long markdown wall. Durable artifacts belong in docs/artifacts/; throwaway local artifacts belong in /tmp/oneshot-html-artifacts/.

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)
Durable run events live in ~/.oneshot/runs; use oneshot runs, oneshot status, and oneshot eval for recovery and feedback loops
Repo slugs must be exact owner/repo values. Nested paths and .. are rejected before dispatch
doctor compares the running CLI version with the npm registry, checks config, required CLIs, recent event files, SSH reachability, and can verify a specific checkout with --repo
oneshot mcp serve exposes tools for running tasks, listing runs, reading status, initializing policy, listing workflows, and summarizing eval outcomes