---
slug: "pi-troupe"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/denismrvoljak/pi-troupe@main/README.md"
repo: "https://github.com/denismrvoljak/pi-troupe"
source_file: "README.md"
branch: "main"
---
# Pi Troupe

Pi Troupe is a Pi extension for running LLM-powered simulations: focus groups, surveys, interviews, UX tests, brainstorming sessions, market research sketches, and small persona worlds.

It lets you ask simulated people to review product ideas, roast docs, test landing pages, critique ad creative, debate pricing, inspect screenshots, or surface risks before you spend time building the wrong thing.

Features:

- guided `/troupe` setup for common simulation types
- ready-made demos like `roast-my-readme`, pricing surveys, ad tests, and onboarding UX tests
- explicit personas with roles, goals, traits, and constraints
- local run artifacts: prompt, report, event log, manifest, CSV, JSONL
- survey batching with response exports
- visual inputs through screenshot/image paths
- share cards for posting results without leaking local paths

Pi Troupe is inspired by [Microsoft TinyTroupe](https://github.com/microsoft/TinyTroupe). TinyTroupe showed how useful LLM personas and small worlds can be. Pi Troupe is not a fork or wrapper; it brings the pattern into Pi so you can use your existing Pi model subscription/config instead of wiring separate API-token simulations.

> Synthetic feedback, not real research. Use it to find blind spots, draft hypotheses, and design better real user tests.

## Setup

```bash
pi install npm:pi-troupe
pi
```

Local development install:

```bash
pi install /Users/denis/programming_personal/pi-troupe
```

## Quickstart: roast your README

From any project with a `README.md`:

```text
/troupe demo roast-my-readme
```

Pi Troupe reads the README, creates a small panel, and returns blunt feedback from simulated developer personas.

You can also pass a public landing page URL. Pi Troupe will fetch page text first, then run a text-only landing page/ad critique:

```text
/troupe https://example.com/
```

Useful follow-ups:

```text
/troupe templates
/troupe status
/troupe logs
/troupe share
```

## Example: README roast

Pi Troupe can read your current `README.md`, create a small panel, and return blunt feedback.

```text
/troupe demo roast-my-readme
```

Example output from a roast run:

```md
Impatient Hacker: “I get it fast: simulated people roast my stuff before I waste time. That is useful. But show me one command, one output snippet, one ‘ouch, that helped’ example immediately.”

Skeptical Engineer: “The value proposition is clear enough, but the trust model is thin. For a simulation tool, data handling is not a footnote.”

Indie Builder: “This is aimed at me. Landing pages, pricing, docs, onboarding tests — that is exactly the pre-build feedback loop I want.”

OSS Maintainer: “The Pi subscription/config angle is the biggest differentiator. Make it a headline: no separate API-token plumbing, model config reuse, Pi-native install and commands.”
```

Typical findings:

- Core idea is understandable: LLM-powered simulated personas for feedback before real research.
- Strongest line: “surface risks before you spend time building the wrong thing.”
- Pi subscription/config benefit matters; do not bury it.
- Safety is good, but say what leaves your machine and where artifacts are written.

Full sample: [examples/roast-my-readme.sample.md](https://github.com/denismrvoljak/pi-troupe/blob/HEAD/examples/roast-my-readme.sample.md).

## Try a landing page URL

Pass a public URL directly:

```text
/troupe https://your-landing-page.com/
```

Pi Troupe fetches the page text, extracts the title, meta description, headings, CTA/link text, and readable body copy, then runs a landing-page/ad critique on that content.

Good things to try:

- `/troupe https://your-landing-page.com/` — broad landing page critique
- `/troupe review this pricing page: https://your-site.com/pricing` — pricing clarity and objections
- `/troupe test this ad landing page for skeptical buyers: https://your-site.com/` — audience-specific critique
- `/troupe compare the CTA and trust signals on https://your-site.com/` — focused copy review

URL review fetches page content automatically. For visual critique, Pi Troupe can use screenshots too:

- If your Pi workflow has the separate Playwright browser tool available, it can capture a screenshot and pass it to Pi Troupe.
- If not, provide a local screenshot path yourself, for example: `/troupe review this landing page screenshot: ./homepage.png`.

## What you can simulate

- README or docs roast
- landing page URL review
- landing page focus group
- pricing survey
- ad creative test
- screenshot usability test
- Product Hunt launch roast
- feature prioritization debate
- onboarding UX test
- custom interview, survey, brainstorm, or small world

## Why use this instead of plain chat?

- **Personas stay explicit**: roles, goals, fears, constraints.
- **Disagreement is expected**: panel members push against each other.
- **Runs are logged**: prompt, events, report, manifest, exports.
- **Pi-native**: child `pi -p` runs use your configured provider/model.
- **Safer boundary**: child simulations run with `--no-tools --no-session`.
- **Shareable**: `/troupe share` creates compact copy without local paths.

## Relation to Microsoft TinyTroupe

[Microsoft TinyTroupe](https://github.com/microsoft/TinyTroupe) explores LLM-powered personas living in simulated worlds.

Pi Troupe borrows that mental model, but focuses on Pi workflows:

| Microsoft TinyTroupe | Pi Troupe |
| --- | --- |
| Python simulation framework | Pi extension/package |
| Rich agents and worlds | Developer-facing focus groups, surveys, roasts |
| Separate setup/API wiring | Uses your active Pi model setup |
| General simulation toolkit | Fast product/docs/UX critique inside Pi |

Pi Troupe is independent and not affiliated with Microsoft.

## Commands

| Command | Purpose |
| --- | --- |
| `/troupe` | guided TUI flow |
| `/troupe <request>` | natural-language simulation |
| `/troupe demo [id]` | run bundled template |
| `/troupe templates` | list templates |
| `/troupe status` | list recent runs |
| `/troupe logs [id]` | inspect state/events/report |
| `/troupe share [id]` | generate share card |
| `/troupe export [csv\|jsonl] [id]` | print response export |

## Demo templates

```text
/troupe demo roast-my-readme
/troupe demo pricing-survey
/troupe demo ad-creative-test
/troupe demo screenshot-usability-test
/troupe demo product-hunt-launch-roast
/troupe demo pricing-page-review
/troupe demo landing-page-focus-group
/troupe demo feature-prioritization
/troupe demo onboarding-ux-test
```

More recipes: [docs/RECIPES.md](https://github.com/denismrvoljak/pi-troupe/blob/HEAD/docs/RECIPES.md).

## Safety and limits

Pi Troupe generates synthetic feedback from LLM personas. It does **not** replace interviews, usability tests, security review, analytics, or market research.

Default boundary:

- Child simulations run as `pi -p --no-tools --no-session`.
- Personas cannot execute tools in child runs.
- Logs are local by default under `~/.pi/troupe/...`.
- Prompt content, fetched URL text, pasted text, and attached images may be sent to your configured Pi model/provider.
- Run artifacts are written locally under the log directory.
- Outputs are hypotheses, not evidence.
- Avoid sending secrets or private user data unless your configured provider/model is appropriate for that data.

Read [docs/SAFETY.md](https://github.com/denismrvoljak/pi-troupe/blob/HEAD/docs/SAFETY.md) and [docs/EVALS.md](https://github.com/denismrvoljak/pi-troupe/blob/HEAD/docs/EVALS.md).

## Artifacts

Each run writes:

```text
~/.pi/troupe/<project-slug>/runs/<run-id>/
  state.json
  events.jsonl
  prompt.md
  report.md
  manifest.json
  responses.csv
  responses.jsonl
  survey-manifest.json
```

Override root:

```bash
PI_TROUPE_DIR=/tmp/pi-troupe pi
```

## Development

```bash
npm install
npm run check
npm run pack:smoke
```

## Release

```bash
npm run check
npm run pack:smoke
npm publish --access public
```

## License

MIT