tracer-cloud--opensre/docs/pi-coding.mdx

---
title: "Pi coding tasks"
description: "Let OpenSRE hand a coding task to the Pi agent, which edits the working tree and returns a diff."
---

The **Pi coding tool** lets OpenSRE submit a coding task to the [Pi](https://pi.dev) agent.
Pi edits files in a workspace to implement the change and returns a summary plus the git diff.
It **does not commit, push, or open a pull request** — it only edits the working tree so you can
review the diff.

This is different from using Pi as your LLM provider (`LLM_PROVIDER=pi`, see
[LLM providers](/llm-providers)). There Pi is the reasoning engine; here Pi is the thing that
actually changes code.

<Warning>
This is a **mutating** tool — it changes files on disk. It is **disabled by default**: it only
becomes available to the agent when `PI_CODING_ENABLED=1`. Enable it only when you want OpenSRE to
make code changes. It never commits, pushes, or opens a PR, so you always review the diff.
</Warning>

## Quick reference

| Env var | What it does |
| --- | --- |
| `PI_CODING_ENABLED` | Opt-in switch. Set to `1` to make the tool available. Off by default. |
| `PI_CODING_MODEL` | Optional Pi model in `provider/model` form (e.g. `anthropic/claude-haiku-4-5`). |
| `PI_CODING_WORKSPACE` | Default repository path Pi edits. Defaults to the current directory. |
| `PI_CODING_TIMEOUT_SECONDS` | Per-task timeout (default 600, clamped 60–1800). |
| `PI_BIN` | Optional explicit path to the `pi` binary. |

## Enable it

1. Install and authenticate the Pi CLI (same binary/credentials as the Pi provider):
   ```bash
   npm i -g @earendil-works/pi-coding-agent
   # then authenticate: run `pi` and use /login, or export a provider key such as GEMINI_API_KEY
   ```
2. Turn the tool on:
   ```bash
   export PI_CODING_ENABLED=1
   export PI_CODING_MODEL=anthropic/claude-haiku-4-5   # optional
   ```
3. Confirm Pi is ready:
   ```bash
   uv run opensre doctor
   ```

## How it works

When the tool runs, it:

1. runs `pi` in headless mode inside the workspace with your task plus a fixed set of rules
   (follow `AGENTS.md`, do not commit or push, do not run destructive git commands, preserve
   unrelated changes, summarize what changed),
2. lets Pi edit the files,
3. returns `success`, a `summary`, the list of `changed_files`, and the `diff` (truncated if large).

You review the diff and decide whether to keep, commit, or revert the changes.

## Example

Once enabled, the tool is available to the agent (investigation surface). Describe a scoped
coding task, for example:

```
add input validation to parse_config() in config/loader.py
```

If the agent calls the tool, Pi edits `PI_CODING_WORKSPACE`, and you get back a summary and the
diff to review. Nothing is committed. (The agent decides whether to call the tool; for a
deterministic run, invoke `pi_coding_task` directly — see the tests.)

## Notes

- Nothing is committed or pushed. Opening a PR is out of scope for now.
- It is **disabled by default**. Only when `PI_CODING_ENABLED=1` does the agent see it and get
  to choose to call it — enable it deliberately, since it edits files.
- If `PI_CODING_ENABLED` is unset, or the Pi CLI is missing or unauthenticated, the tool stays
  unavailable and returns a clear message instead of running.