# pw code

> Source: https://parallelworks.com/docs/ai/code

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

:::info 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](/docs/cli) 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](/docs/cli#authentication).
- **An AI provider**: At least one AI provider must be configured by you or shared with you. See [AI Providers](/docs/ai/ai-providers).

## Quick Start

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

```bash
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:

```bash
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](/docs/ai/code/models#allocations), a named spending budget your organization grants you. When you need an ID outside a session, such as for [non-interactive runs](/docs/ai/code/non-interactive), 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](/docs/ai/code/settings#workspace-trust).

By default, the agent edits workspace files freely but asks before each shell command. See [Permissions](/docs/ai/code/permissions).

A short session looks like this:

<TerminalWindow>
  <TermUser name="Jake.Thayne">fix the failing test in parser_test.go</TermUser>
  <TermAgent model="Jake.Thayne:openai/gpt-5.2">I'll look at the failing test and fix the parser.</TermAgent>
  
  <TermResult>214 lines</TermResult>
  
  <TermDiffDel>return cfg</TermDiffDel>
  <TermDiffAdd>return cfg, nil</TermDiffAdd>
  <TermResult>ok</TermResult>
  
  
</TerminalWindow>

## Capabilities

- **[Sessions & Resume](/docs/ai/code/sessions)**: 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](/docs/ai/code/permissions)**: Control what the agent may do without asking, from read-only exploration to fully autonomous edits.
- **[Interface & Shortcuts](/docs/ai/code/interface)**: The full-screen terminal interface, keyboard shortcuts, `@` file references, and `!` shell mode.
- **[Models & Allocations](/docs/ai/code/models)**: Pick from the models your providers offer, and browse budget allocations interactively when using organization providers.
- **[Settings](/docs/ai/code/settings)**: Global and per-workspace configuration, and the in-session `/settings` menu.
- **[Slash Commands](/docs/ai/code/slash-commands)**: Type `/` in a session to run built-in commands, plus custom commands defined in your project.
- **[Project Instructions](/docs/ai/code/project-instructions)**: Guide the agent with an `AGENTS.md` file checked into your project.
- **[MCP Servers](/docs/ai/code/mcp)**: Connect Model Context Protocol servers to give the agent additional tools.
- **[Subagents](/docs/ai/code/subagents)**: Delegate work to subagents that run in parallel alongside your session.
- **[Custom Agents](/docs/ai/code/custom-agents)**: Define specialized agents with their own instructions, tool access, and model.
- **[Non-Interactive Mode](/docs/ai/code/non-interactive)**: Run one-shot prompts with text or JSON output for scripting and automation.

## Command-Line Flags

| Flag | Description |
| --- | --- |
| `-m`, `--model` | Model ID (can also be passed as a positional argument). |
| `--allocation` | Budget allocation name. Required for `org:` provider models. |
| `-p`, `--prompt` | Send a single prompt and exit. See [Non-Interactive Mode](/docs/ai/code/non-interactive). |
| `-w`, `--workspace` | Workspace root directory. Defaults to the current directory. |
| `--permission-mode` | `read-only`, `accept-edits` (default), `bypass-permissions`, or `plan`. See [Permissions](/docs/ai/code/permissions). |
| `--allowedTools` | Tools pre-approved without prompting, for example `ReadFile` or `'Bash(git status:*)'`. |
| `--add-dir` | Directories outside the workspace the agent may read without prompting (repeatable). |
| `-o`, `--output` | Output format for one-shot runs: `text` (default) or `json`. |
| `-r`, `--resume` | Resume a local session by ID or `latest`; used alone, opens an interactive session picker. |
| `--no-tools` | Disable tool calling (chat-only mode). |
| `--agent` | Run a [custom agent](/docs/ai/code/custom-agents) definition as the main session. |

For the complete command reference, see [pw code](/docs/cli/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](/docs/ai/chat) list in the web interface. See [Sessions & Resume](/docs/ai/code/sessions) 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:

```bash
# 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

- [Usage & Costs](/docs/ai/code/usage-and-costs): Token usage and cost estimates
- [Troubleshooting](/docs/ai/code/troubleshooting): Resolve common issues
- [Chat](/docs/ai/chat): The web chat interface
- [AI Providers](/docs/ai/ai-providers): Configure AI providers
- [pw code command reference](/docs/cli/pw/code): Full CLI reference