PW Agent 🧠

CLI coding assistant powered by your Ollama GPUs via PastaWater.

Install

The recommended way to install pw-agent is using pipx to keep it isolated from your other Python packages:

pipx install pw-agent

Alternatively, you can use standard pip: pip install pw-agent

Usage

pw-agent

First run guides you through setup — paste your API token, pick a GPU, start chatting.

Features

  • Interactive REPL with real-time streaming and a premium dashboard status bar.
  • Plan vs Build Modes: Use /plan for read-only analysis and /build for execution.
  • Context Discovery: Automatically finds PW_AGENT.md for project-specific rules.
  • Tab Autocomplete for commands, file paths, and GPU slots.
  • Session Control: Fresh sessions by default; use -c to resume where you left off.
  • File Injection: /add file.py or @file.py — inject files into the LLM's context.
  • Batch Processing: Model can run multiple tool calls in a single turn.
  • GPU Fleet Control: /models to view GPUs and /use N to switch connections or slots.
  • AI Commits: /commit to generate and apply git commit messages based on your diff.
  • Safety First: -y flag for auto-approve; otherwise, every file edit requires confirmation.

Connect

  • Cloud mode: Use your PastaWater API token to access your remote fleet.
  • Direct mode: Point at a local Ollama instance (--brain http://localhost:11434).

Get your token at pastawater.io/settings

Model compatibility (tool calling)

Agentic tool use needs both a capable model AND an Ollama whose tool-call parser tolerates that model's output drift.

Model Ollama Tool calling Notes
qwen3-coder:30b >= 0.31.2, pw-agent >= 1.52.0 verified needs native tools mode (below); ~20 GB resident on a single 24 GB card
qwen3-coder:30b >= 0.31.2, pw-agent <= 1.51.x broken every tool-requiring prompt dies on turn 0 with [Empty response from model], exit 3
qwen3-coder:30b 0.21.x broken intermittent qwen tool call parsing failed: EOF — session degrades to plain chat
llama3.1:8b any recent works weaker coder; fine for pipeline text tasks

Native tools mode

Ollama >= 0.31 ships built-in renderer/parser pairs for some model families (template selection ... selected=renderer_parser renderer=qwen3-coder). For those models the server intercepts every <tool_call> tag the model emits and parses it with that family's native grammar. pw-agent's textual protocol puts JSON inside <tool_call>, which is not that grammar, so the server-side parser dies with qwen tool call parsing failed: EOF, discards the whole assistant message, and answers /api/chat with {"error":"EOF"}.

From 1.52.0 pw-agent sends Ollama's native tools schemas for these models, drops the textual protocol from the system prompt, and reads structured message.tool_calls back. Two safety nets:

  • Any model that hits a server-side parse failure is flagged automatically and the turn is replayed with native tools — no failed run, just a slower first turn.
  • PW_NATIVE_TOOLS=1 forces it on, PW_NATIVE_TOOLS=0 forces it off (the off case now reports the parse failure as a named error rather than an empty response).

Side effect: the system prompt drops from ~4.7 KB to ~1.7 KB for these models, since the renderer injects the tool definitions itself.

Failure signals

A session that ends without executing any tool due to parse failure/stall emits {"type":"result","subtype":"degraded","degraded_reason":..., "is_error":true} and exits with code 3; a missing model or dead endpoint fails preflight with the installed-model list and exits with code 2. Ollama-level errors (including tool-parse failures) are surfaced verbatim as [Error: Ollama: ...] instead of an empty response.

Only one large model fits a 24 GB card at a time — requesting a second large tag while one is resident forces CPU offload.

Debugging a silent run

--debug (or PW_DEBUG=1) dumps the model name, native-tools decision, num_ctx, every request message, the full assembled tool schema, and the raw model completion. All of it goes to stderr, so --output-format stream-json on stdout stays machine-parseable:

pw-agent --instance 0 --yes --debug \
  --output-format stream-json --print "..." 2>debug.log

--model is optional: omit it and pw-agent uses whatever the instance currently has resident (brain's last_known_chat_model, else the loaded model, else /api/tags). Pinning a tag the slot isn't serving is only useful when you want Ollama to swap.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for levmor from gravatar.com levmor

Credits

Author: PastaWater

License

MIT License

Requires

Python >=3.10

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pw_agent-1.52.0.tar.gz (128.5 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

pw_agent-1.52.0-py3-none-any.whl (134.0 kB view details)

Uploaded Python 3

File details

Details for the file pw_agent-1.52.0.tar.gz.

File metadata

  • Download URL: pw_agent-1.52.0.tar.gz
  • Upload date:
  • Size: 128.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for pw_agent-1.52.0.tar.gz
Algorithm Hash digest
SHA256 578fda0b24ef6980a052b031be8065c7f18226a4477d808b18b9460e38011cf9
MD5 26f14ce3f31705ecc73fb30f5061a422
BLAKE2b-256 d68cd5dc00977fc9a81559401f1e76e2feb5506ccf4ee3fce46e9d34d1ccb3ba

See more details on using hashes here.

File details

Details for the file pw_agent-1.52.0-py3-none-any.whl.

File metadata

  • Download URL: pw_agent-1.52.0-py3-none-any.whl
  • Upload date:
  • Size: 134.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for pw_agent-1.52.0-py3-none-any.whl
Algorithm Hash digest
SHA256 df17c41929be520a47af87fdb5d24d942da16ec4d9dcd36619939141251ef5f9
MD5 5e11c6ea009cda983fb31aecbc25ecc2
BLAKE2b-256 8cf0086ecff48386c0b1dfe21b7a6a5020d574db2708eb73df368efa96da0294

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

1.52.0

1.51.0

1.50.40

1.50.39

1.50.38

1.50.37

1.50.36

1.50.35

1.50.34

1.50.33

1.50.32

1.50.31

1.50.30

1.50.29

1.50.28

1.50.27

1.50.24

1.50.23

1.50.18

1.50.17

1.50.16

1.50.15

1.50.14

1.50.13

1.50.12

1.50.11

1.50.10

1.50.9

1.50.8

1.50.7

1.50.6

1.50.5

1.50.4

1.50.3

1.50.2

1.50.1

1.50.0

1.49.1

1.49.0

1.48.1

1.48.0

1.47.11

1.47.10

1.47.9

1.47.8

1.47.7

1.47.6

1.47.5

1.47.4

1.47.3

1.47.2

1.47.1

1.47.0

1.46.7

1.46.6

1.46.5

1.46.4

1.46.3

1.46.2

1.46.1

1.46.0

1.45.1

1.45.0

1.44.2

1.44.1

1.44.0

1.43.2

1.43.1

1.43.0

1.42.0

1.41.1

1.41.0

1.40.4

1.40.3

1.40.2

1.40.1

1.40.0

1.39.3

1.39.2

1.39.1

1.39.0

1.38.3

1.38.2

1.38.1

1.38.0

1.37.0

1.36.0

1.35.0

1.34.0

1.33.0

1.32.4

1.32.3

1.32.2

1.32.1

1.32.0

1.31.0

1.30.7

1.30.6

1.30.5

1.30.4

1.30.3

1.30.2

1.30.1

1.30.0

1.29.0

1.28.0

1.16.5

1.16.4

1.16.3

1.16.2

1.16.1

1.16.0

1.15.8

1.15.7

1.15.6

1.15.5

1.15.4

1.15.3

1.15.2

1.15.1

1.15.0

1.14.5

1.14.4

1.14.3

1.14.2

1.14.1

1.14.0

1.13.4

1.13.3

1.13.2

1.13.1

1.13.0

1.12.9

1.12.8

1.12.7

1.12.6

1.12.5

1.12.4

1.12.3

1.12.2

1.12.1

1.12.0

1.11.1

1.11.0

1.10.0

1.9.5

1.9.4

1.9.3

1.9.2

1.9.1

1.9.0

1.8.4

1.8.3

1.8.2

1.8.1

1.8.0

1.7.9

1.7.8

1.7.7

1.7.6

1.7.5

1.7.4

1.7.3

1.7.1

1.7.0

1.6.7

1.6.6

1.6.5

1.6.4

1.6.2

1.6.1

1.6.0

1.5.8

1.5.7

1.5.6

1.5.5

1.5.3

1.5.2

1.5.1

1.5.0

1.4.9

1.4.8

1.4.7

1.4.5

1.4.4

1.4.3

1.4.1

1.4.0

1.3.8

1.3.7

1.3.6

1.3.5

1.3.3

1.3.2

1.3.1

1.3.0

1.2.4

1.2.3

1.2.2

1.2.1

1.2.0

1.1.9

1.1.8

1.1.7

1.1.6

1.1.5

1.1.4

1.1.3

1.1.2

1.1.1

1.1.0

1.0.6

1.0.5

1.0.4

1.0.3

1.0.2

1.0.1

1.0.0

0.9.4

0.9.3

0.9.2

0.9.1

0.9.0

0.8.7

0.8.6

0.8.5

0.8.4

0.8.3

0.8.2

0.8.1

0.8.0

0.7.9

0.7.8

0.7.7

0.7.6

0.7.5

0.7.4

0.7.3

0.7.2

0.7.1

0.7.0

0.6.9

0.6.8

0.6.7

0.6.6

0.6.5

0.6.4

0.6.3

0.6.2

0.6.1

0.6.0

0.5.2

0.5.1

0.5.0

0.4.4

0.4.3

0.4.2

0.4.1

0.4.0

0.3.1

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page