@codeworksh/cli weekly downloads statistics

@codeworksh/cli

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

Installation

After install, every command is codework .

Development

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

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.

Flags:

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

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

codework serve

Start a persistent server that owns sessions and sandboxes:

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 session.interrupt, which interrupts the shared session. Remote runs print the sandbox ID for reuse. session.interrupt returns { interrupted } as soon as the stop is accepted; session.wait is the separate cleanup barrier. 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..*); 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.

--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 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.

codework models refresh

The model catalog lives at /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.

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.

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.…

Description from the npm listing.