---
title: "Pi Development Workflow"
summary: "Developer workflow for Pi integration: build, test, and live validation"
read_when:
  - Working on Pi integration code or tests
  - Running Pi-specific lint, typecheck, and live test flows
---

# Pi Development Workflow

This guide summarizes a sane workflow for working on the pi integration in Fased.

## Type Checking and Linting

- Type check and build: `pnpm build`
- Lint: `pnpm lint`
- Format check: `pnpm format`
- Full gate before pushing: `pnpm lint && pnpm build && pnpm test`

## Running Pi Tests

Run the Pi-focused test set directly with Vitest:

```bash
pnpm test -- \
  "src/agents/pi-*.test.ts" \
  "src/agents/pi-embedded-*.test.ts" \
  "src/agents/pi-tools*.test.ts" \
  "src/agents/pi-settings.test.ts" \
  "src/agents/pi-tool-definition-adapter*.test.ts" \
  "src/agents/pi-extensions/**/*.test.ts"
```

To include the live provider exercise:

```bash
FASED_LIVE_TEST=1 pnpm test -- src/agents/pi-embedded-runner-extraparams.live.test.ts
```

This covers the main Pi unit suites:

- `src/agents/pi-*.test.ts`
- `src/agents/pi-embedded-*.test.ts`
- `src/agents/pi-tools*.test.ts`
- `src/agents/pi-settings.test.ts`
- `src/agents/pi-tool-definition-adapter.test.ts`
- `src/agents/pi-extensions/*.test.ts`

## Manual Testing

Recommended flow:

- Run the gateway in dev mode from the repo checkout:
  - `pnpm gateway:dev`
- Trigger the agent directly:
  - `fased agent --message "Hello" --thinking low`
- Use the TUI for interactive debugging:
  - `pnpm tui`

For tool call behavior, prompt for a `read` or `exec` action so you can see tool streaming and payload handling.

## Clean Slate Reset

State lives under the Fased state directory. Default is `~/.fased`. If
`FASED_STATE_DIR` is set, use that directory.

To reset everything:

- `fased.json` for config
- `credentials/` for auth profiles and tokens
- `agents/<agentId>/sessions/` for agent session history
- `agents/<agentId>/sessions.json` for the session index
- `sessions/` if legacy paths exist
- `workspace/` if you want a blank workspace

If you only want to reset sessions, delete these paths for that agent:

- `agents/<agentId>/sessions/`
- `agents/<agentId>/sessions.json`

Keep `credentials/` if you do not want to reauthenticate.

## References

- [Testing](/help/testing)
- [Getting Started](/start/getting-started)
