Run Open Run from your terminal

Use openrun sol medium to open your coding agent with the settings you describe. Add schedule to run work later, or use openrun run for a managed task now. Managed runs use a local background worker, so you can close the terminal while the agent works.

Local runs and schedules need no Open Run account, web server, or web build. You need Node.js 22.12 or newer, Git, and at least one coding-agent CLI installed and logged in. Use macOS, Linux, or Windows through WSL2.

Install Open Run

The standalone npm package installs the openrun command and its background worker. Install it globally to use it from any repository:

npm install -g @dennisadriaans/openrun

The interactive interface uses OpenTUI. Install Bun 1.3+, or use Node.js 26.4+; Open Run selects the renderer runtime automatically. The background worker and noninteractive commands still use Node.js 22.12+.

Open your coding agent

openrun sol medium
openrun claude opus high
openrun "create new file x.html gpt 5.5 extra high"
openrun "create new file x.html Astra ultra"
openrun "create new file x.html grok high"
openrun "create new file index-test.html with contents '123' sonnet low"
openrun "review my changes using Sol with medium reasoning"

Your agent opens in its native terminal interface in the current directory, using your existing login. A task is optional. You do not need to register a project or create an Open Run account first. When launched from Home, closing the agent returns you to the input.

Put a model name and effort after a task, such as sonnet low, to select the agent automatically. The file-creation example opens Claude Code with Sonnet and low effort, passing only create new file index-test.html with contents '123' as the task. You can type the same request directly into Home. Complete task requests in this form resolve locally without a picker or hosted interpretation.

Model choices come from your installed agents: Codex, Claude Code, Grok, Gemini CLI, Antigravity (agy) and fx. Names ignore case and accept spaces or hyphens. Nicknames such as Luna, Terra, Sol, Astra, Haiku, Sonnet, Opus and Fable select the newest listed version of that family; Heiku also matches Haiku. Use an explicit runtime when a model is available through several agents: using agy sonnet high selects Antigravity.

Effort choices follow the selected model. extra high means xhigh, and maximum means max; ultra, ultracode and ultrathink are distinct. Unsupported combinations ask you to choose a supported level. Gemini CLI has no effort flag, and fx's model list exposes no effort capabilities, so these use the agent's default effort. For fx, a supplied task runs with fx ask; omit the task to open its interactive session.

Other natural-language interpretation sends the request you type and your available model choices to Open Run and TypeSafe. Repository files are not read or sent. No inference API key is needed. If the service is unavailable or a choice is unclear, Open Run offers local selectors with your request preserved.

Explicit options work without hosted interpretation:

openrun launch --runtime codex --model gpt-5.6-sol --effort medium
openrun launch --runtime claude --prompt "fix the schedule page"
openrun launch --runtime codex --model gpt-5.6-sol --dry-run --json

--prompt and -- pass the task literally, so words such as “schedule” inside it do not schedule work. For native launching, --in selects a local directory. Set OPENRUN_CLOUD_URL=off to disable hosted interpretation; explicit options and the local Home interface remain available.

Start a managed run

Switch to the Git repository you want the agent to work on:

cd /path/to/your/repository
openrun init
openrun run "summarise the recent changes in this repository"

init registers the repository and detects its verification commands. Running it again reuses the existing project. The first command that needs application data starts the background worker automatically.

In a terminal, Open Run preselects your last-used agent, or the first installed, enabled agent on a fresh setup. Press Enter to confirm it, then Enter again on Run now. Use the arrow keys to change a selection.

The command prints openrun show followed by the new run's ID. Run that command to read its status and saved conversation. Repeat it to see new output while the agent is working.

For a project-local npm installation, use npm install --save-dev @dennisadriaans/openrun and invoke commands with npx openrun. A global installation makes the plain openrun command available across projects.

With a source checkout, run pnpm link --global from the Open Run installation directory to make openrun available elsewhere. You can also use pnpm cli … from that directory. Pass --in /path/to/your/repository to run and schedule when your current directory is elsewhere.

Let the CLI guide you

You can start with just a task:

openrun run "explain project in 5 words"

For a registered project, the quick path has two choices:

Which agent? Keep the preselected agent with Enter, or choose another installed agent with the arrow keys.
What next? Press Enter on Run now. Choose Schedule for later for timing options, or Change settings to edit the agent, project, model, prompt, automation name or pull request instructions.

A compact summary shows the task, agent, project path and timing before you start. Open Run remembers your agent after a successful run or schedule. An unregistered checkout leads into project setup; an omitted prompt asks what you want the agent to do.

Run openrun with no arguments to open Home. Type a request at the top:

schedule in 2 minutes "review the open changes" using Sol medium

Home shows active runs, upcoming schedules and automations in aligned columns below the input. They stack when the terminal is narrow. Buttons beneath the overview open scheduling, recent runs and integrations. Paused automations and those needing attention are labeled. Times are displayed in your terminal's timezone, including when connected to a remote worker.

Type a command name or a task. A unique command match opens directly; ambiguous short names offer matching actions. A complete schedule request creates the automation when you press Enter. Open Run asks only for missing details such as the agent, project, task or verification command. Free-form requests use TypeSafe to match the action, agent and model as described above.

The session stays open after actions, so you can keep working without restarting the CLI. Home updates in place when runs start, finish or change status, including work started in another terminal. Your input keeps focus during updates. If the activity connection is unavailable, Home refreshes every three seconds while reconnecting. Older running workers use this fallback until restarted. Type refresh for a manual refresh. Type runs for recent runs, integrations for connections, or automations for the full schedule list. Every Home command also works with a slash — /ls is ls — and / alone lists them all.

Each Home session is saved to ~/.openrun/cli-sessions/ as you type. Type clear (or "start over") to start a new, empty session; the previous one stays saved. Type resume to choose an earlier session by its first request and continue it: its chat returns, runs it started reappear in Activity once the worker reports them, and new requests are added to it. Answers to menus and commands such as ls are not requests, so a session holding only those is not offered. openrun resume (alias openrun sessions) lists saved sessions from a script, and --json includes each transcript's path.

Press Tab to switch between the input and the overview. In the overview, use the arrow keys or Page Up / Page Down to scroll.

Other commands use the same pattern: openrun show offers recent runs, openrun disable offers automations, and openrun integrations guides you through connections and event automation setup. Deleting, disconnecting and stopping work require confirmation, with No preselected.

Invalid command options open an editor with your arguments preserved. Invalid times and other form inputs explain how to correct them inside the prompt. If a request fails, the CLI explains the problem and offers next steps, such as inspecting recent runs or setting up a project. It does not automatically repeat a failed write: work may have started even if the response was lost.

Press Esc or Ctrl+C once to clear the current input. With the input empty, Esc goes back to the previous menu or setup step. Completed choices in run setup stay in your draft so you can change one without starting over. At Home, Esc keeps the session open. Type quit, or press Ctrl+C twice within two seconds at a prompt, to leave. Quitting leaves the background worker, active runs and schedules running.

Explicit commands finish when their action completes. Pressing Esc out of their setup opens Home. --yes, --json and commands outside an interactive terminal keep their scripting behavior.

A run or automation is submitted when you confirm a guided flow or press Enter on a complete command. Project registration and agent settings you already confirmed remain saved.

The interface redraws the current screen and restores your terminal when you leave. Set NO_COLOR=1 for a monochrome palette. For commands without prompts, see Use the CLI in scripts.

Choose an agent and repository

List your registered projects and available agent CLIs:

openrun projects
openrun runtimes
openrun where

where shows the current workspace, runtimes, and local or remote connection. A workspace is the checkout where the agent will work. By default, Open Run uses the registered workspace containing your current directory.

Choose another registered workspace by path or project name, and an agent by its runtime name:

openrun run "review the checkout flow" for claude
openrun run "review the checkout flow" --runtime codex --in ../storefront

Use --model to override the runtime's default model, or change it in the interactive settings. openrun runtimes lets you set a preferred agent, enable or disable agents, and add a built-in preset. If a project name matches several workspaces, the CLI offers a selector; scripts should pass a checkout path or workspace ID.

Schedule work

An automation saves a prompt, runtime, workspace, and schedule. Creating one enables its schedule immediately. Preview the selection and firing time first with --dry-run:

openrun schedule every weekday at 8:30 "sweep dependency updates" \
  --name "Dependency sweep" --dry-run

Remove --dry-run to save it. Add for <runtime> to preselect a particular agent. A preview creates no automation or run and does not register projects or change their checks, but it can start the local worker and initialize its database.

For guided setup, run openrun schedule or choose Schedule for later from a run. Pick tomorrow morning, a delay, a specific time, weekdays, every day, weekly, an interval, or a custom cron expression. Each option offers an editable default, followed by a summary and Create schedule.

Run once or repeat

Use a relative time for a single run, or every for a recurring schedule:

openrun schedule in 20 minutes "check the build"
openrun schedule in 10 minutes "review changes and open a pull request" using sol medium
openrun schedule tomorrow at 9 "review yesterday's changes"
openrun schedule every day at 9 "review new issues"
openrun schedule every 15 minutes "check the build"

at 16:40 means the next occurrence of that time. A one-time automation pauses after its scheduled run starts. Recurring schedules stay enabled until you pause or delete them. Times use your local timezone; keep the machine awake and the worker running for work to start.

For a calendar pattern, use a quoted cron expression:

openrun schedule cron "0 9 * * 1-5" --prompt "review new issues"

Minute intervals must divide 60 evenly, and hour intervals must divide 24. For example, every 15 minutes and every 6 hours are supported. These are calendar intervals: every 15 minutes fires on the quarter-hour.

Set verification commands

Unattended work uses the same verification and Git prerequisites as automations created in the web app. If init found no checks, interactive setup asks for a verification command before saving the schedule. You can also register commands explicitly. For a project with these pnpm scripts:

openrun init --check "pnpm typecheck" --check "pnpm test"

Repeated --check options replace the project's detected or previously saved checks. Scheduled runs get a fresh execution directory pinned to the Git commit resolved for that run; Open Run creates it for you. A manual openrun run starts a conversation in the selected checkout.

Pass prompt text literally

Use --prompt or put all prompt text after -- when it contains words that could describe a schedule:

openrun run --prompt "explain what runs every day at 9"
openrun run --runtime claude -- explain what runs every day at 9

Put options before --. Literal prompts do not infer an instruction to push or open a pull request; include those instructions in the prompt when wanted.

Continue a scheduled conversation in its agent

Scheduling saves the selected model, effort and task in Open Run and returns without opening an interactive agent. Once execution finishes:

openrun runs
openrun continue <run-id>

continue opens the same native Codex or Claude Code session using its stored session ID and execution directory. Scheduled work can run in an isolated worktree, so the session can be scoped to that directory in the native agent's history. Resume on the machine that ran the task, while the session and directory still exist. Active runs must finish or be stopped first.

Open Run retains the scheduled execution's transcript. Further messages sent directly in the native agent stay in its history; they are not streamed back into the existing Open Run run.

Inspect runs and manage automations

List recent runs, then use an ID from the list to read or cancel one:

openrun runs --limit 20
openrun show <run-id>
openrun cancel <run-id>

show prints the saved status, prompt, and conversation. cancel stops an active run. Omit the ID to choose one interactively. openrun runs offers a selector that opens the saved conversation; add --yes for a plain list.

Manage an automation by name or ID:

openrun automations list
openrun now "Dependency sweep"
openrun disable "Dependency sweep"
openrun enable "Dependency sweep"

now starts an existing automation immediately and prints the run ID. disable pauses future scheduled runs; use cancel to stop a run already in progress. enable resumes the schedule. To delete an automation, use openrun rm <automation-name-or-id>.

You can omit the name or ID on these commands to choose an automation. openrun automations also offers actions for each saved automation.

Keep schedules running

The worker handles runs, schedules, and integration deliveries in the background. Closing the terminal leaves it running. It does not install a service that starts at login or boot: after a reboot, start the worker again.

openrun worker status
openrun worker start
openrun worker logs

status reports whether the worker or web app is running without starting anything. start reuses an existing process when one is already running. logs prints the worker log. Help, API discovery, and API previews also work without starting a worker.

To shut down the worker:

openrun worker stop

Stopping cancels active runs and stops scheduling until you start Open Run again. Run history and automations remain saved.

Switch to the web app

The CLI and web app share the same scheduler and database. Only one process may own that database at a time. The npm package contains the CLI and worker; to use the browser UI, follow the web app installation. Stop the worker, then start the web app from its installation directory:

openrun worker stop
cd /path/to/openrun
pnpm dev

Open http://localhost:3000 to see your existing automations and runs. Subsequent CLI commands connect to that web process automatically. To return to the worker, stop the web app from its terminal, then run openrun worker start.

State lives in ~/.openrun/openrun.db by default. If you set OPENRUN_HOME, use the same value for the CLI and web app to share history. See where things live.

Connect an issue tracker

You can authorize a provider and create an automation from the terminal:

openrun integrations connect github
openrun integrations configure

The command prints an authorization URL for you to open in your browser. Provider authorization and event delivery use Open Run Cloud. Local scheduling, execution, and history work without it, including with OPENRUN_CLOUD_URL=off.

Follow Connect from the terminal to choose events, customize the prompt, and manage connections.

Use the CLI in scripts

Add --yes (or -y) to skip interactive prompts. Supply the runtime when several are available, and pass IDs or names for operations that need them:

openrun run --runtime codex --prompt "review the checkout flow" --yes
openrun disable "Dependency sweep" --yes

--yes skips confirmations, including destructive ones. It does not guess between ambiguous resources. Redirected input or output and CI environments also disable interactive prompts.

Add --json for structured results; it always disables prompts. Diagnostics go to stderr, keeping stdout available for JSON:

openrun runs --limit 20 --json
openrun show <run-id> --json

For capabilities beyond the named commands, openrun api lists application operations and their input fields interactively. Add --yes for a plain list. Pass an operation name and a JSON object to call one. This includes follow-up messages, approvals, runtime settings, MCP configuration, and automation filters, with the same validation as the web app.

openrun api --yes
openrun api runs.get '{"id":"run_123"}'
openrun api tasks.toggle '{"id":"task_123","enabled":false}' --dry-run

Replace the example IDs with your own. An API dry run prints the operation and input without sending or validating the request on the server.

Connect to another Open Run server

Set --url or OPENRUN_URL to use an existing HTTP server. For a server configured for remote access:

openrun runs --url https://openrun.example.com
openrun init /srv/storefront --url https://openrun.example.com

Use that server's access token through OPENRUN_ACCESS_TOKEN or --token. The CLI only reads your local access-token file automatically for loopback URLs. A failed remote request reports an error without switching to local data.

Remote init requires an absolute repository path on the server. For runs and schedules, use --in to select a workspace on that server. One-time dates are resolved in the CLI machine's timezone; recurring cron schedules use the server's timezone. Worker controls are local: remove --url and unset OPENRUN_URL to use them.

Troubleshooting

openrun is not found after an npm install. Use npm install -g for a command available across projects. With a local installation, use npx openrun from that project. Ensure npm's global bin directory is on your shell's PATH.

openrun is not found in a source installation. Run pnpm link --global from the Open Run installation directory. If pnpm reports that its global bin directory is missing, run pnpm setup, reopen your terminal, and link again. You can use pnpm cli … from the installation directory in the meantime.

No prompts appear. Prompts need a terminal on stdin, stdout and stderr. Remove --yes or --json, avoid piping or redirecting the command, and check that CI is not set in your interactive shell.

A script cannot choose a runtime or workspace. Run openrun runtimes --yes and openrun where. Register your checkout with openrun init, then pass --runtime and --in explicitly.

A schedule did not fire. Check openrun worker status and openrun automations list. Keep the machine awake, start the worker after a reboot, and check openrun worker logs for a failed prerequisite.

The web app says the database is already owned. Run openrun worker stop before starting the web app. If status identifies a web process, stop it from its terminal instead.

For command options and more examples, run openrun <command> --help.