Cowork Code

Install

Install Node.js with npm first. Supported versions are Node.js 22.19 or later on the 22.x line, or Node.js 24 or later. Node.js 23 is not supported. Then run:

npm i -g --silent https://agentcowork.net/cli
agent --version
agent login
cd your-project
agent

• Windows: use PowerShell on Windows 10 or later. If execution policy blocks npm's PowerShell wrapper, use npm.cmd in the install command.
• macOS: use Terminal with a supported Node.js installation.
• Linux: use your shell with a supported Node.js installation.

The latest CLI package was installed and checked on macOS. Physical Windows and Linux runtime checks remain separate from package validation. Installation downloads the coding engine and its dependencies from npm and requires internet access.

You can also download the archive and run npm i -g --silent ./cowork-code.tgz. The package identifier is @agentcowork/cli; registry publication is separate, so install the archive URL above. The command is agent. The earlier names cowork-code, agent-cowork-code, agent-cowork and cowork are installed as aliases for it and keep working unchanged, so nothing you have already scripted breaks.

Connect your account

The interactive start screen lets you choose actions with arrow keys or a number, then press Enter. Models and saved conversations have selection menus. In a conversation, type / to discover commands and use Tab to complete a suggestion.

During sign-in, the terminal confirms when your browser opens. Press Enter or R to reopen the same connection page, or Ctrl+C to cancel. The fallback link includes your verification code.

Agent-Reach is included for public web reading through Jina Reader. Ask Cowork to read a public URL or check which sources are available. Optional platform tools and authenticated sources need their own connection; private pages use your connected browser.

Run agent login. Code opens your browser and displays a device code. Sign in to Agent Cowork, verify that the code matches, and approve the connection. If the browser does not open, use the verification address printed in your terminal. Your password is entered on the website, never in the CLI.

Reconnect after 24 hours, or earlier if the server grants a shorter session. An open engine closes at expiry. Use /login to reconnect, then continue your saved conversation. Sign-in alone does not create a paid subscription: your account controls the models and allowance available to you.

agent logout removes the local credential. Use account key management when you need remote revocation. Local daily expiry is enforced by Code; server-side credential expiry also requires the corresponding platform deployment.

Projects and permissions

Start from your project folder or pass --cwd PATH. Code asks you to trust a workspace before first interactive use. Its real coding engine can read and edit files, execute commands, and use configured tools with your operating-system user's permissions.

The selected working directory is not an operating-system security boundary. There is no OS sandbox. When the engine needs your permission for an action, or has a question, it asks in the terminal and waits for your answer. Only trust projects and instructions you intend to run.

agent "Fix the failing test and explain the change"
agent --cwd ./my-project
agent --continue
agent -p "Explain the failing test" --trust-workspace

--continue reopens your most recent conversation in the current project. -p runs one task and exits. Unattended runs need a previously trusted workspace or explicit --trust-workspace. Ctrl+C stops the engine and exits the terminal session; it does not undo completed edits or external actions. Review your Git diff and test results before committing.

agent --approval read-only
agent --approval default
agent -p "Build the landing page" --approval full --trust-workspace

--approval sets how much the agent may do on its own, the same choices as the desktop app. default (used when you pass nothing) edits files and runs commands inside the project without asking, like the desktop app; risky commands, such as recursive deletes, force pushes, dropped database tables and shutdowns, still ask. read-only asks before every edit and command. full also generates images from your allowance without asking. In a -p run nobody can answer, so a step that would ask is skipped and the agent finishes the task another way, telling you what it skipped. You can set the preset once with the AGENT_COWORK_APPROVAL environment variable.

Live output and side notes

The answer streams into the terminal as it is written. Tool activity, such as files read, edits made and commands run, is shown as it happens, and each turn ends with a short summary. Questions and approval requests from the engine appear inline; answer them in the terminal to continue.

The input box sits between two rules, with a footer showing the model, the workspace, the approval mode and any queued notes. Your own messages are highlighted in the feed so they stand out from the answer. Press \+Enter, Ctrl+J or Alt+Enter for a new line; Enter sends. Multi-line paste is kept intact.

The input stays open while a turn is running. Anything you type is passed along as a side note for the current task, without interrupting it; /btw does the same explicitly. ↑ recalls your last note for editing.

The typing box is a real editor, not a single line: ← and → move by character and Alt with them by word, Home and End jump to the ends of a line, and a long or pasted message wraps and scrolls instead of running off the edge. Your draft survives a turn finishing underneath it.

agent --verbose
agent --show-thinking
agent --continue

--verbose prints more detail about each tool step. --show-thinking reveals the engine's reasoning as it works. Inside a conversation, /summary recaps what has been done so far.

Warm engine

Since 1.8.22 the first command in a project starts a small background helper that keeps the coding engine warm. Later commands attach to it in milliseconds instead of booting the engine again, so a task starts answering in a few seconds rather than fifteen. Engines are kept per project, model and account, are released after 15 minutes of inactivity (at most three stay warm), and are retired when you sign out, change account or update. The helper only talks to this machine over a user-private channel; nothing changes in what is sent to Agent Cowork or in how usage is counted.

agent daemon status
agent daemon stop
agent daemon start

Set AGENT_COWORK_NO_DAEMON=1 to run without the helper, or AGENT_COWORK_DAEMON_IDLE_MS to change the idle window.

Models and usage

Agent Cowork picks the best model for each part of your task. You only pay for what it uses.

Code connects through your Agent Cowork account. Check your subscription if a desired model is unavailable.

/usage retrieves a current snapshot of your allowance. It is shown as percentages, never as an amount of money. You see how much of the monthly allowance is left, how it was divided between the models, and how much is currently held for requests still in flight. Verified recovery times appear in your computer's locale and timezone. Minutes shown are relative to that server snapshot; run /usage again to refresh. Legacy server responses without reliable recovery data do not get an invented countdown.

A top-up balance is reported separately, on its own scale, because it does not expire with the month: it stays until you use it, and it is only drawn on once the monthly allowance is finished. Folding the two together is what used to produce a percentage that did not match the month. An AI Images counter joins the same display in the next update.

Usage is always shown as your plan allowance and your balance, never in model units. Long conversations are summarised automatically so they keep working. Refer to your plan for its allowance.

Your account's current billing policy determines rates and model allowances. Desktop and Code usage count toward the same account limits. Check /usage and your dashboard for the limits that apply to your current period.

Attachments and voice

Use /attach "path/to/file.pdf" to attach a PDF, Word DOC/DOCX, Markdown or text document directly to your draft. PNG, JPEG, GIF and WebP images are also supported. Use /attachments to review and /detach 1 to remove an item before sending. Images need an image-capable model; documents are read as extracted text. Scanned PDFs need OCR or page images.

Use /voice to dictate. On first use, Cowork downloads and verifies a multilingual speech model (about 547 MiB). Audio is transcribed locally. Automatic language detection is the default, with Arabic, English, French, Spanish, German, Portuguese, Hindi and Chinese available explicitly. Dialect accuracy varies; review the text before sending. Tiny and Base remain available with /voice-model.

On Mac, allow your terminal to use the microphone in System Settings → Privacy & Security → Microphone. The default device follows macOS Sound settings. On Windows, choose a device with /voice-devices and /voice-device.

Chrome browser access

Run agent browser in a second terminal and leave it open. Install the Chrome extension and approve the connection there. Your coding session can then inspect pages, click, type and capture screenshots. A connected desktop app can also provide the browser connection. Visual screenshot inspection requires an image-capable model; text and element inspection remain available otherwise.

agent browser

Install Agent Cowork for Chrome 3.0 or later from the Chrome Web Store. The agent works in its own Chrome window, so your tabs are left alone. The extension also has its own side panel chat and screen recorder; see Chrome in the main guide.

Smart next steps

After an interactive task, Code can suggest up to three actions based on your request, reported outcome, and observed tool names: investigate a failure, review changes, validate behavior, continue unfinished work, plan findings, or inspect generated media. Suggestions require no extra model call.

/next
/next 1

/next displays the current choices. /next 1 runs the first; use another displayed number to choose that action. Nothing runs until you choose it, and you can always type your own task. Suggestions refresh every turn and clear when you switch conversations or accounts. One-shot -p output stays free of suggestion menus.

Sessions and command reference

The commands above are typed inside a conversation. Outside one, the same work is done by the agent command itself:

Resume with --resume SESSION_ID, or --continue for the most recent conversation. A session belongs to its original project; use --cwd THAT_FOLDER --resume SESSION_ID when needed.

Code keeps its own sessions. Desktop conversations are not imported automatically, and logging out does not erase local history.

Default skills and media tools

The bundled skills (design, documents, video, planning and more) install on first use: the terminal installs the set that fits your machine and your projects, the same way the desktop app decides it. Run /skills to see the list. Add a folder containing SKILL.md under ~/.agent-cowork/cli/skills for your own skill. Upgrades refresh untouched bundled copies while preserving your edits and additions.

Skills are instructions, not subscriptions or executable installers. Vendor accounts, tools, and MCP connections may need separate setup. Palmier editing requires Palmier Pro on macOS and its MCP connection. Agent Cowork's own Remotion guide is bundled; it is not the official Remotion skill pack. Install the relevant Remotion or FFmpeg dependencies for those workflows.

The terminal preview does not automatically import desktop MCP connections and does not include the desktop media preview panel.

Storage and security

Code stores its local data in ~/.agent-cowork/cli, or %USERPROFILE%\.agent-cowork\cli on Windows. Set AGENT_COWORK_CLI_HOME to use another directory. It contains credentials, workspace trust preferences, skills, and persisted conversation history.

To close your account, use connections in your dashboard; deletion there removes the account and its data, and signs out every connected app including this one. What is kept, for how long, and why is set out on the privacy page.

Windows credentials use DPAPI tied to your Windows account. Other systems use credential files restricted to the current user. Account keys stay out of engine settings and command arguments; a temporary authenticated loopback gateway forwards requests during a valid session. Protect your CLI home and backups because history and project output can contain private information. Never share credential files.

Update and uninstall

Run /update inside a conversation, or agent update from your terminal. Relaunch agent after installation. Versioned archives remain unchanged. Code updates through npm, separately from the desktop updater; existing sessions and skills are preserved.

agent logout
npm uninstall --global @agentcowork/cli

Uninstall removes the command package, not local history or skills. If you also want to remove local data, review and back up the CLI home before deleting that directory yourself.

Troubleshooting

• Command not found: reopen your terminal; check npm prefix --global and that npm's executable directory is on PATH.
• Something else answers to agent: if another global npm package already provides an agent command, the first one on your PATH wins. The CLI detects this on its first run and after agent update, and prints one line naming an alias that reaches it, for example agent-cowork.
• Unsupported Node: check node --version and use a version listed above.
• Installation permission error: use an npm installation directory owned by your account. Avoid running coding sessions as administrator or root.
• Browser or code problem: open the displayed verification address, or run login again for a fresh code.
• Expired session or missing model: reconnect, refresh /models, and check your subscription.
• Engine missing: reinstall the archive with dependencies and run doctor. Developers may set AGENT_COWORK_ENGINE_DIR to a built desktop engine; ordinary npm installs do not need it.
• Skill or tool unavailable: check its platform, installed runtime, vendor account, and MCP prerequisites.
• Unexpected edits: stop with Ctrl+C, inspect the project diff, and restore selected files through version control.

For help, open a support ticket and follow replies in your account. Include the Code version, operating system, and a redacted error message; omit credentials and private project content.

How it works and its limits

Cowork Code uses the real coding engine. It works like the desktop agent: it keeps a checklist of what you asked for, notes what it is doing, and keeps going until the work is done. It does not yet provide a full-screen terminal UI, interactive diff approval, an OS sandbox or the desktop media previews.