> ## Documentation Index
> Fetch the complete documentation index at: https://opensre.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Pi coding tasks

> Let OpenSRE hand a coding task to the Pi agent, which edits the working tree and returns a diff.

## Overview

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](/docs/platform/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>

## Prerequisites

* Pi CLI installed and authenticated (same binary/credentials as the Pi provider)
* Explicit opt-in via `PI_CODING_ENABLED=1`

## Setup

There is no `opensre integrations setup` target for Pi coding. Enable it with environment variables.

### Enable it

1. Install and authenticate the Pi CLI:
   ```bash theme={null}
   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 theme={null}
   export PI_CODING_ENABLED=1
   export PI_CODING_MODEL=anthropic/claude-haiku-4-5   # optional
   ```
3. Confirm Pi is ready:
   ```bash theme={null}
   uv run opensre doctor
   ```

| 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 (for example `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.                                             |

## Credentials

Pi coding shares the `pi` binary and provider credentials with the LLM-provider Pi path. Authenticate once with `/login` inside `pi`, or export the provider API key your Pi model needs. OpenSRE does not store a separate Pi coding token.

## Tools

| Tool             | What it does                                                                |
| ---------------- | --------------------------------------------------------------------------- |
| `pi_coding_task` | Run Pi headlessly on a coding task; return summary, changed files, and diff |

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

## Verify

There is no dedicated `integrations verify` target. Confirm readiness with:

```bash theme={null}
uv run opensre doctor
```

In-tool readiness also checks the Pi binary and auth via `verify_pi_coding()`. 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.

## Troubleshooting

| Symptom                          | Fix                                                                                      |
| -------------------------------- | ---------------------------------------------------------------------------------------- |
| **Tool never offered**           | Set `PI_CODING_ENABLED=1`                                                                |
| **Pi missing / unauthenticated** | Install `@earendil-works/pi-coding-agent` and complete `/login` or export a provider key |
| **Wrong workspace**              | Set `PI_CODING_WORKSPACE` to the repo path                                               |
| **Timeouts**                     | Raise `PI_CODING_TIMEOUT_SECONDS` (max 1800)                                             |

## Security

* Disabled by default — enable deliberately.
* Edits the working tree only — never commits, pushes, or opens a PR.
* Review every diff before you keep changes.