@codeworksh/cli

Run coding-agent sessions in your repo or a sandbox.

Installation

pnpm add -g @codeworksh/cli
# or run directly
pnpm dlx @codeworksh/cli <command>

After install, every command is codework <command>.

Development

From packages/codework, or pnpm cli at the repo root:

pnpm start -- --help
pnpm start -- models
pnpm start -- run "Inspect the failing tests"

start runs src/index.ts with --conditions=development so workspace packages resolve to source. The published codework binary is the packed dist build.

Commands

codework run

Run an agent session with a prompt.

# Start a new session
codework run "Inspect and fix the failing tests"

# Create a session with explicit provider and model
codework run --provider openai --model gpt-5.5 --thinking high "Plan database migration"

# Continue an existing session (its main thread)
codework run --session ses_01a070f0 "Now implement the migration script"

# Continue one of its threads
codework run --session ses_01a070f0 --thread thr_01a071c2 "Try it without the cache"

# Run in an isolated sandbox (local, daytona, vercel, memory, sqldb)
codework run --sandbox-driver daytona "Inspect repository"
codework run --sandbox-driver daytona --sandbox-provider-id <remote-id> "Continue in sandbox"

Flags:

• --server <url> — Connect to a running RPC server, e.g. ws://127.0.0.1:7433/rpc/v1.
• -s, --session <id> — Continue an existing session.
• --thread <id> — Thread of --session to continue: a thread ID, or main (default).
• -C, --cwd <path> — Working directory for a new session.
• --sandbox-driver <driver> — Sandbox driver (local, daytona, vercel, memory, sqldb). Default: local.
• --sandbox-id <id> — Reuse an existing sandbox instance; mutually exclusive with driver/provider coordinates.
• --sandbox-provider-id <id> — Provider ID of an existing remote sandbox.
• --provider <id> — Model catalog provider ID.
• --model <id> — Model ID.
• --thinking <level> — Reasoning effort the model uses before answering (off, minimal, low, medium, high, xhigh, max).

Global flags: --user-config-dir, --home, --database.

codework thread

A session holds one or more threads: its main thread, and the forks made from it. These commands talk to a running server (--server, default http://127.0.0.1:7433).

# List a session's threads with their model and usage
codework thread list ses_01a070f0

# Start a new thread through an entry, or just before a prompt to send it again
codework thread fork ses_01a070f0 --at <entry-id>
codework thread fork ses_01a070f0 --thread thr_01a071c2 --before <entry-id>

# Move one thread into another checkout of the project, keeping its position under it;
# the rest of the session stays where it is
codework session relink ses_01a070f0 --thread thr_01a071c2 -C ~/work/api

thread fork prints the new thread ID, then for --before the text of the prompt it left out. --json prints the wire form.

codework serve

Start a persistent server that owns sessions and sandboxes:

codework serve --host 127.0.0.1 --port 7433
codework run --server ws://127.0.0.1:7433/rpc/v1 "Inspect the failing tests"
codework run --server ws://127.0.0.1:7433/rpc/v1 --session <id> "Now fix them"
codework run --server ws://127.0.0.1:7433/rpc/v1 --sandbox-id <sandbox-id> "Start another session in this sandbox"

The default address is 127.0.0.1:7433; --port 0 picks an available port and prints the actual URL. Set --home, --database, and --user-config-dir on the server. Model credentials, plugins, and working directories are resolved by the server. A remote run does not boot a local harness.

Events are live and not replayed. The client subscribes before admitting its prompt and waits for execution completion after rendering. Lost connections and overflow fail the command; disconnecting leaves server work running. Ctrl-C sends thread.interrupt, which stops the thread the run prompted. Remote runs print the sandbox ID for reuse. thread.interrupt returns { interrupted } as soon as the stop is accepted; thread.wait is the separate cleanup barrier, and session.interrupt stops every thread of a session. A busy period reports itself as session.execution.started followed by exactly one of succeeded, failed, or interrupted -- a failure carries a category (provider-authentication-error, model-not-found-error, sandbox-mount-error, ...) that the client renders, and an interruption carries whether it was the user or a server shutdown. Managed sandboxes remain available until explicitly stopped or server shutdown; external sandboxes are not stopped.

The v0 endpoint has no authentication; its default binding is loopback. Plugins publish their own event types by declaring them (Plugin.define({ events: [...] }), namespaced plugin.<plugin-id>.*); the feed carries those and skips types nothing declared. Invalid payloads for declared types fail with a typed encoding error.

codework auth login|status|refresh|logout

Sign in to OpenAI Codex with your ChatGPT account, or to GitHub Copilot with your GitHub account. Credentials are stored under the selected Codework home and are loaded automatically when a run uses an openai-codex or github-copilot model.

# Sign in
codework auth login --openai-codex
codework auth login --github-copilot

# Codex without a local callback port (SSH, containers, port 1455 in use)
codework auth login --openai-codex --device

# Inspect credential metadata without printing tokens
codework auth status --openai-codex
codework auth status --github-copilot

# Renew an expired login, or clear one
codework auth refresh --openai-codex
codework auth logout --github-copilot

# Authenticate the home owned by a running RPC server
codework auth login --openai-codex --server ws://127.0.0.1:7433/rpc/v1

--home keeps authentication alongside the rest of that Codework installation; --auth-file overrides the credential file directly. Both providers share one auth.json, keyed by provider, so signing out of one leaves the other alone. With --server, the CLI runs the interactive login locally -- a browser callback and a device prompt both need this terminal -- and sends only the resulting credentials to the RPC server for storage.

OpenAI Codex has two flows. The default keeps Aikit's registered http://localhost:1455/auth/callback redirect, and falls back to asking for the redirect URL if the callback never arrives. --device instead prints a code to enter at auth.openai.com/codex/device and needs no local port at all — use it over SSH, inside a container, or when another sign-in already holds 1455. That port is fixed by the redirect registered against the OAuth client, so it cannot move.

GitHub Copilot uses the GitHub device flow: the CLI prints a user code, opens github.com/login/device, and waits. The token does not expire, so there is no --refresh -- sign in again on persistent 401s. --enterprise <domain> logs into a GitHub Enterprise host, and --enable-models turns on catalog models the account has left unconfigured. Login records the plan-specific Copilot API host, which later runs use in place of the catalog default.

codework models

List catalog models as provider/model, one per line.

# List all models across all providers
codework models

# List models for a specific provider
codework models --provider openai

# List all supported provider IDs
codework models providers

codework models refresh

The model catalog lives at <home>/models.gen.json (~/.codework unless --home says otherwise). Every local command checks it before use and downloads a new one once it is older than 15 minutes (CODEWORK_MODELS_TTL, e.g. "1 hour"); codework serve also re-checks every minute and reloads the file whenever it changes. A failed download keeps the previous catalog.

# Download the catalog if it is missing or stale; no network call otherwise
codework models refresh

# Download it now
codework models refresh --force

codework plugin add / codework plugin remove

Install a plugin and record it in a settings file, or take it back out. Scoping follows npm: the project is the default, -g is user-wide.

# This project: edits .codework/settings.jsonc, creating .codework/ here if no ancestor has one
codework plugin add @acme/[email protected]

# Every project this user runs: writes ~/.codework/settings.jsonc
codework plugin add @acme/[email protected] -g

# Remove it, along with any configuration written against it
codework plugin remove @acme/codework-tool-proc

The project is found the way the harness finds it, and the way git finds a repository: the nearest ancestor holding a .codework directory. Run from packages/app, the command edits the repository's own .codework/settings.jsonc rather than starting a second project beside it. An empty .codework/ is enough — the marker is the directory, so creating it is how you say a project begins here. When no ancestor has one, add creates .codework/ in the directory you are in and prints the path, because that decides where every later plugin entry lands.

add installs and imports the module before writing anything, so a spec that is not a plugin fails with its own error and leaves the file untouched; the line it prints names the plugin ID the module actually declared. Adding a plugin that is already configured under another spelling — a different version, or the path instead of the package — rewrites that entry in place rather than leaving a second loader behind, the way npm install pkg@2 updates the spec already recorded. Configuration written against the plugin is left where it is. Edits preserve comments, key order and formatting, and are written through a temp file so an interrupted run cannot truncate your settings.

remove drops the module entry and any configuration object naming the same plugin, whichever spelling each was written with: the version it was added with is not part of its identity, and the ID a module declares removes the entry that loads it. Resolving an ID reads what is installed and never fetches anything. A plugin can also be kept but switched off without removing it, with { "plugin": "acme.tool.proc", "enabled": false }.

Flags:

Plugin entries accumulate across settings layers, so a user-wide plugin still applies inside a project that declares its own. A project that wants an inherited plugin gone says so in its own file, with { "plugin": "<id>", "enabled": false }.

Environment Variables

License

MIT