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...
---
name: oneshot-ship
description: 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 Claude and Codex.
license: MIT
metadata:
author: ADWilkinson
version: "0.2.12"
repository: "https://github.com/ADWilkinson/oneshot-cli"
compatibility: Requires Bun, Claude Code CLI, Codex CLI, and GitHub CLI. SSH access to a server optional (can run locally with --local)
---
# oneshot CLI
Ship code with a single command. oneshot runs a full pipeline with configurable agents per phase. Defaults are classify + plan (Claude) → execute (Codex) → review (Codex) → PR metadata (Claude), but each agent phase can be Claude or Codex. 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
```bash
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](https://bun.sh)
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
- [Codex CLI](https://github.com/openai/codex)
- [GitHub CLI](https://cli.github.com) (authenticated)
- `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` in environment
## Usage
```bash
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>" --deep-review # force exhaustive review
oneshot <repo> "<task>" --model sonnet # override Claude-backed 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> --dry-run # validate only
oneshot init # configure
oneshot stats # recent runs + timing
oneshot doctor # package, tool, SSH, and event health
oneshot doctor --repo zkp2p/pay # health plus checkout existence
```
## Pipeline
1. **Validate**: checks the repo exists, fetches latest from origin
2. **Worktree**: creates a temp git worktree from the target base branch
3. **Classify**: configurable agent classifies the task as `fast` or `deep` via heuristics + LLM
4. **Plan**: configurable agent reads the codebase and CLAUDE.md conventions, outputs an implementation plan
5. **Execute**: configurable agent implements the plan. If it times out with partial changes, the pipeline continues
6. **Draft PR**: configurable agent creates a branch, commits, and writes PR metadata; the runtime opens the draft PR
7. **Review**: configurable agent reviews the diff. In `deep` mode it runs an exhaustive review across correctness, security, and code quality
8. **Finalize**: runtime pushes review fixes and marks the PR ready
Worktree is cleaned up after every run.
## Configuration
`~/.oneshot/config.json`:
```json
{
"host": "user@100.x.x.x",
"basePath": "~/projects",
"anthropicApiKey": "sk-ant-...",
"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": { "provider": "claude", "model": "haiku" },
"plan": { "provider": "claude", "model": "opus" },
"execute": { "provider": "codex", "model": "gpt-5.5", "reasoningEffort": "xhigh" },
"review": { "provider": "codex", "model": "gpt-5.5", "reasoningEffort": "xhigh" },
"deepReview": { "provider": "codex", "model": "gpt-5.5", "reasoningEffort": "xhigh" },
"pr": { "provider": "claude", "model": "opus" }
},
"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`, phase-agent defaults, timeout settings, and configured Anthropic/Linear credentials stay aligned even if the server does not have its own oneshot config file.
## Flags
| Flag | Short | Description |
|------|-------|-------------|
| `--model` | `-m` | Override Claude-backed plan/PR model |
| `--branch` | `-b` | Base branch (default: main) |
| `--base-path` | | Override the workspace path used to locate the repo |
| `--mode` | | Skip classification and force `fast` or `deep` mode |
| `--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 |
| `--help` | `-h` | Help |
| `--version` | `-v` | Version |
## Customization
- Put a `CLAUDE.md` in any repo root. oneshot passes it to the configured agents for planning and execution
- Configure `phases.classify`, `phases.plan`, `phases.execute`, `phases.review`, `phases.deepReview`, and `phases.pr` to choose `claude` or `codex`, exact model, and Codex reasoning effort per phase
- Edit `prompts/plan.txt`, `execute.txt`, `review.txt`, `pr.txt` to change pipeline behavior
- 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`)
- 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 the agent hook runtime, and can verify a specific checkout with `--repo`
don't have the plugin yet? install it then click "run inline in claude" again.