oneshot

Ship code in one command. Repo + task in, PR out.

laptop → server → configurable agents per phase → PR

Also runs locally with --local, no server needed.

Install

Requires Bun. macOS and Linux.

bun install -g oneshot-ship

Quick start

oneshot init                                    # configure
oneshot doctor                                  # check local + remote setup
oneshot doctor --repo my-org/my-app             # verify a checkout target
oneshot my-org/my-app "fix the login timeout"   # ship

How it works

oneshot runs an 8-step pipeline. Each run gets its own git worktree in /tmp, so your main branch is never touched. Parallel runs on the same repo are safe.

Step	Engine	What it does
1. Validate	git	Checks the repo exists, fetches latest
2. Worktree	git	Creates an isolated `/tmp` worktree from `origin/main`
3. Classify	Configurable	Picks fast or deep review mode based on task complexity
4. Plan	Configurable	Reads the codebase + `CLAUDE.md`, outputs an implementation plan
5. Execute	Configurable	Implements the plan
6. Draft PR	Configurable	Creates branch, commits, and writes PR metadata; the runtime opens the draft PR
7. Review	Configurable	Reviews the diff for bugs, types, security. Fixes issues directly
8. Finalize	git/gh	Pushes review fixes, marks PR ready

If execute times out with partial changes, the draft PR is still created so nothing is lost.

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>" --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                         # setup and remote health checks
oneshot doctor --repo my-org/my-app    # setup + checkout health

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
`--worktree-root`		Override where temporary git worktrees are created
`--mode`		Skip classification and force `fast` or `deep` mode
`--deep-review`		Force exhaustive review mode
`--local`		Run locally instead of over SSH
`--bg`		Run detached in background (returns 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

Prerequisites

On your laptop: Bun, SSH access to your server

On your server (or local machine with --local):

Bun
Claude Code CLI
Codex CLI
GitHub CLI (authenticated)
ANTHROPIC_API_KEY and OPENAI_API_KEY in env

Configuration

~/.oneshot/config.json, created by oneshot init:

{
  "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 without requiring a duplicate ~/.oneshot/config.json on the server.

Key	Required	Description
`host`	SSH only	SSH target, e.g. `user@192.168.1.10`
`basePath`	No	Where repos live. Default: `~/projects`
`worktreeRoot`	No	Scratch directory for temporary git worktrees. Default: `/tmp`
`anthropicApiKey`	No	Falls back to `ANTHROPIC_API_KEY` env var
`linearApiKey`	No	Enables Linear ticket integration
`claude.model`	No	Legacy default for Claude-backed Plan and PR phases. Default: `opus`
`codex.model`	No	Legacy default for Codex-backed Execute phase. Default: `gpt-5.5`
`codex.reasoningEffort`	No	Legacy default reasoning effort for Codex execution. Default: `xhigh`
`codex.reviewModel`	No	Legacy default for Codex-backed Review phases. Default: same as `codex.model`
`codex.reviewReasoningEffort`	No	Legacy default reasoning effort for Review phases. Default: same as `codex.reasoningEffort`
`phases.<phase>.provider`	No	Agent provider for `classify`, `plan`, `execute`, `review`, `deepReview`, or `pr`. Use `claude` or `codex`
`phases.<phase>.model`	No	Exact model for that phase
`phases.<phase>.reasoningEffort`	Codex only	Codex reasoning effort for that phase, e.g. `medium`, `high`, `xhigh`
`stepTimeouts`	No	Per-step timeout overrides in minutes

phases is optional and backward-compatible. If it is omitted, oneshot keeps the previous sandwich defaults: Claude classifies/plans/creates PR metadata, Codex executes/reviews, and git/gh finalizes the PR.

Repos on the server should live as <org>/<repo> under the base path. Repo slugs are intentionally strict: exactly owner/repo, using only letters, numbers, dot, underscore, and hyphen. Nested paths and .. are rejected before any filesystem access.

~/projects/
  acme/api/
  acme/web/

Linear integration

Pass a Linear URL instead of a task string:

oneshot acme/api https://linear.app/acme/issue/ENG-142

Fetches issue title, description, and comments via GraphQL
Uses ticket as context for the planning step
Uses the issue ID in the branch name (oneshot/eng-142-...)
Moves the ticket to "In Review" and comments the PR URL

Requires linearApiKey in config.

Customization

CLAUDE.md: put one in any repo root. oneshot passes it to the configured agents for planning and execution. Use it for coding standards, architecture decisions, test requirements.

Prompt templates: edit these to change pipeline behavior:

File	Controls
`prompts/plan.txt`	How the plan agent explores and plans
`prompts/execute.txt`	How the execute agent implements changes
`prompts/review.txt`	How the review agent reviews the diff
`prompts/pr.txt`	How the PR agent writes branch/commit/PR metadata

Templates use {{variable}} placeholders replaced at runtime.

The repo's CLAUDE.md is also supplied to the planning and execution steps, so the task string is the primary operator input, not the only context the agents receive.

For dense specs, explainers, review maps, incident reports, design sheets, or one-off editors, the templates allow a self-contained HTML artifact instead of a long markdown document. Durable artifacts should live under docs/artifacts/; throwaway local artifacts should stay under /tmp/oneshot-html-artifacts/.

Events

Every run writes JSONL events to /tmp/oneshot-<runId>.events.jsonl. Use --events-file <path> to mirror to another file:

oneshot acme/api "fix bug" --local --events-file /tmp/run.events.jsonl

Events:

started (includes runtime metadata such as CLI version, host, pid, cwd, platform, and worktree root), classified, step (running/done/failed), completed (success/failed/dry-run)
agent for live agent activity: commands, tools, file changes, todos, web searches, warnings, draft PR creation, and turn/session markers

Doctor and recovery

oneshot doctor checks the installed package freshness against npm, local prerequisites, config file, recent event stream, SSH reachability, and remote binaries when a remote host is configured. Use oneshot doctor --local --json for machine-readable local checks.

Add --repo <owner/repo> to verify the configured local or remote base path actually contains the checkout before dispatch:

oneshot doctor --repo zkp2p/pay
oneshot doctor --local --repo zkp2p/pay --json

Failed runs preserve the worktree under the configured worktreeRoot and write a failed completed event with the error code and completed step timings. Start with oneshot stats, then inspect the event file or preserved worktree path printed in the logs.

Agent skill

Works as an Agent Skill in Claude Code, Codex CLI, Cursor, and other compatible agents.

npx skills add ADWilkinson/oneshot-cli

Or via ClawHub:

clawhub install oneshot-ship

Agents pick it up automatically, or call /oneshot-ship directly.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 77 Commits
.agent-hooks		.agent-hooks
.claude		.claude
.codex		.codex
.github/workflows		.github/workflows
.oneshot		.oneshot
docs		docs
prompts		prompts
scripts		scripts
skills/oneshot-ship		skills/oneshot-ship
src		src
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
bun.lock		bun.lock
package.json		package.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

oneshot

Install

Quick start

How it works

Usage

Flags

Prerequisites

Configuration

Linear integration

Customization

Events

Doctor and recovery

Agent skill

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

oneshot

Install

Quick start

How it works

Usage

Flags

Prerequisites

Configuration

Linear integration

Customization

Events

Doctor and recovery

Agent skill

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages