Parallel Works
View as Markdown
Share:

pw code

pw code is an AI coding agent that runs in your terminal. It can read, write, and edit the files in your workspace (the directory you start it in), run shell commands, and carry out multi-step tasks autonomously using tool calling. Responses stream in real time and are rendered as formatted markdown directly in your terminal.

Feature may not be available on all platforms

pw code requires at least one AI provider to be configured. If no models are available in your account, contact your administrator.

Prerequisites

  • PW CLI installed: See the CLI documentation for installation instructions.
  • Authenticated: Run pw auth and paste your credential when prompted. On ACTIVATE user workspaces and clusters the CLI is pre-authenticated. See Authentication.
  • An AI provider: At least one AI provider must be configured by you or shared with you. See AI Providers.

Quick Start

Start the agent from the directory you want to work in:

pw code

If you do not specify a model, pw code opens an interactive picker so you can choose one; there is nothing to look up first. Inside a session, run /model to reopen the picker and switch at any time.

You can also start with a specific model by passing its ID:

pw code owner:provider-name/model-name

Model IDs have the form owner:provider-name/model-name. For a personal provider, the owner is the username of the person who owns the provider (for example Jake.Thayne:openai/gpt-5.2). Organization provider models use the org: prefix and require a budget allocation, a named spending budget your organization grants you. When you need an ID outside a session, such as for non-interactive runs, list them with pw ai models ls.

What to expect on first launch

If the directory contains configuration files (a .mcp.json file or a .agents/ folder), pw code lists them at first launch and asks whether to apply them. See Workspace Trust.

By default, the agent edits workspace files freely but asks before each shell command. See Permissions.

A short session looks like this:

Jake.Thayne
fix the failing test in parser_test.go
Jake.Thayne:openai/gpt-5.2
I'll look at the failing test and fix the parser.
● ReadFile(file_path: "parser_test.go")
⎿ 214 lines
● EditFile(file_path: "parser.go")
- return cfg
+ return cfg, nil
⎿ ok
Permission approval required
Tool Bash
Mode accept-edits
Reason shell command
Command go test ./...
> Yes, allow this command
Yes, and allow this directory for the session
No, deny this command
No, and provide feedback to the agent
↑/↓ navigate · enter select · esc deny
Jake.Thayne:openai/gpt-5.2

Capabilities

  • Sessions & Resume: Every run is saved as a local session on your machine that you can resume later, from the command line or an interactive picker.
  • Permissions: Control what the agent may do without asking, from read-only exploration to fully autonomous edits.
  • Interface & Shortcuts: The full-screen terminal interface, keyboard shortcuts, @ file references, and ! shell mode.
  • Models & Allocations: Pick from the models your providers offer, and browse budget allocations interactively when using organization providers.
  • Settings: Global and per-workspace configuration, and the in-session /settings menu.
  • Slash Commands: Type / in a session to run built-in commands, plus custom commands defined in your project.
  • Project Instructions: Guide the agent with an AGENTS.md file checked into your project.
  • MCP Servers: Connect Model Context Protocol servers to give the agent additional tools.
  • Subagents: Delegate work to subagents that run in parallel alongside your session.
  • Custom Agents: Define specialized agents with their own instructions, tool access, and model.
  • Non-Interactive Mode: Run one-shot prompts with text or JSON output for scripting and automation.

Command-Line Flags

FlagDescription
-m, --modelModel ID (can also be passed as a positional argument).
--allocationBudget allocation name. Required for org: provider models.
-p, --promptSend a single prompt and exit. See Non-Interactive Mode.
-w, --workspaceWorkspace root directory. Defaults to the current directory.
--permission-moderead-only, accept-edits (default), bypass-permissions, or plan. See Permissions.
--allowedToolsTools pre-approved without prompting, for example ReadFile or 'Bash(git status:*)'.
--add-dirDirectories outside the workspace the agent may read without prompting (repeatable).
-o, --outputOutput format for one-shot runs: text (default) or json.
-r, --resumeResume a local session by ID or latest; used alone, opens an interactive session picker.
--no-toolsDisable tool calling (chat-only mode).
--agentRun a custom agent definition as the main session.

For the complete command reference, see pw code.

pw code and Your Account Chats

pw code sessions are local to your machine: they are not uploaded to your account and do not appear in the Chat list in the web interface. See Sessions & Resume for how local sessions are stored.

Chats saved to your account, such as conversations from the web Chat interface, are managed separately with the pw ai chats commands:

# List chats saved to your account
pw ai chats ls
 
# View a chat's messages
pw ai chats get <id>
 
# Delete a chat
pw ai chats delete <id>

Related Documentation