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

[![CI](https://github.com/eiei114/pi-localgpt/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-localgpt/actions/workflows/ci.yml)
[![Publish](https://github.com/eiei114/pi-localgpt/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-localgpt/actions/workflows/publish.yml)
[![npm version](https://img.shields.io/npm/v/pi-localgpt.svg)](https://www.npmjs.com/package/pi-localgpt)
[![npm downloads](https://img.shields.io/npm/dm/pi-localgpt.svg)](https://www.npmjs.com/package/pi-localgpt)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Pi package](https://img.shields.io/badge/pi-package-purple.svg)](https://pi.dev/packages)
[![Trusted Publishing](https://img.shields.io/badge/npm-Trusted%20Publishing-blue.svg)](docs/release.md)
<a href="https://buymeacoffee.com/ekawano114m"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" width="217" height="60"></a>

> 51 curated tools for LocalGPT Gen 3D world building, via unified 1-shot MCP bridge.

## What this is

`pi-localgpt` gives Pi agents tools to work with **[LocalGPT](https://localgpt.app/)** — a Rust-powered real-time 3D level design tool (Bevy engine, 80+ MCP tools).

All tools use a **1-shot MCP bridge**: each call spawns `localgpt-gen mcp-server --connect`, sends one request, and exits. No persistent background process.

> **Not** the unrelated Python RAG project also named "LocalGPT".

## Features

- **Scene building** — spawn/modify/delete entities, camera, lighting, environment
- **WorldGen pipeline** — text description → layout plan → blockout → populate → evaluate → refine
- **Game mechanics** — player, NPC, triggers, teleporters, collectibles, doors, physics
- **Terrain & environment** — procedural terrain, water, foliage, sky, audio
- **Export** — screenshot (including vault `4_Project/<project>/screenshots/`), glTF, HTML, world skills, prompt-pack (vault `4_Project/<project>/prompt-packs/`)
- **Generic call** — unwrapped tools accessible via `localgpt_gen_call`

## Prerequisites

- `localgpt-gen` installed (`cargo install localgpt-gen`)
- **localgpt-gen running interactively** (Bevy window open) — all tools connect via `--connect` relay on port 9878

## Install

Install the published npm package with Pi:

```bash
pi install npm:pi-localgpt
```

Install into the current project instead of your user Pi settings:

```bash
pi install npm:pi-localgpt -l
```

Pin a specific version when you want reproducible installs:

```bash
pi install npm:pi-localgpt@0.10.1
```

Or install from GitHub:

```bash
pi install git:github.com/eiei114/pi-localgpt
```

Try it without permanently installing:

```bash
pi -e npm:pi-localgpt
```

Local development:

```bash
git clone https://github.com/eiei114/pi-localgpt.git
cd pi-localgpt
npm install
pi -e .
```

### Alternative: raw `.mcp.json`

If you only need the upstream LocalGPT MCP server (without Pi extension tools, skills, or curated wrappers), add this to your Pi `.mcp.json`:

```json
{
  "mcpServers": {
    "localgpt-gen": {
      "command": "localgpt-gen",
      "args": ["mcp-server", "--connect"]
    }
  }
}
```

`localgpt-gen` must still be running interactively (Bevy window open) so the `--connect` relay on port 9878 is available. Prefer `pi install npm:pi-localgpt` when you want the curated tool surface, Agent Skills, and vault workflows documented in this repo.

## Quick start

1. Start `localgpt-gen` interactively (Bevy window opens)
2. Check relay: `/localgpt:gen-status` or `localgpt_gen_status`
3. Build world: `localgpt_gen_plan_from_roblox_trend` (Roblox trend summary), `localgpt_gen_plan_from_note` (vault memo), or `localgpt_gen_plan` (short text) → `localgpt_gen_blockout` → `localgpt_gen_populate`
4. Save design: `localgpt_design_log_save`

See [`skills/localgpt-gen/SKILL.md`](https://github.com/eiei114/pi-localgpt/blob/HEAD/skills/localgpt-gen/SKILL.md) for the full workflow guide.

Vault design memos: [`docs/vault-note-plan-layout.md`](https://github.com/eiei114/pi-localgpt/blob/HEAD/docs/vault-note-plan-layout.md).

Roblox trend summaries: [`docs/roblox-trend-prototype.md`](https://github.com/eiei114/pi-localgpt/blob/HEAD/docs/roblox-trend-prototype.md).

## Package contents

| Path | Purpose |
|---|---|
| `extensions/` | Pi TypeScript extension entrypoints |
| `lib/` | Shared TypeScript helpers (MCP client, gen tools) |
| `skills/` | Agent Skills (`localgpt-gen`) |
| `scripts/` | CI helpers (version bump check) |
| `docs/` | Supporting docs (release, manual test checklist) |

## Tools

### Status

| Tool | Purpose |
|---|---|
| `localgpt_gen_status` | Binary + relay check |
| `localgpt_gen_call` | Generic tool wrapper |

### Memory & Design Log

| Tool | Purpose |
|---|---|
| `localgpt_design_log_search` / `_get` / `_save` / `_log` | Design log search, read, durable save, daily append |
| `localgpt_remember_worldgen` | Save design rationale linked to plan/evaluate/export/world artifacts |

### Scene

| Tool | Purpose |
|---|---|
| `localgpt_gen_screenshot` | Viewport screenshot |
| `localgpt_gen_scene` | Scene hierarchy |
| `localgpt_gen_entity` | Entity details |
| `localgpt_gen_spawn` / `_batch` | Spawn primitives |
| `localgpt_gen_modify` / `_delete` | Entity changes |
| `localgpt_gen_camera` / `_light` / `_environment` | Camera & lighting |
| `localgpt_gen_undo` / `_redo` / `_clear` | History & reset |

### Player & NPC

| Tool | Purpose |
|---|---|
| `localgpt_gen_spawn_player` | Spawn player character |
| `localgpt_gen_add_npc` | Create NPC |
| `localgpt_gen_npc_dialogue` | Conversation tree |

### Interactions

| Tool | Purpose |
|---|---|
| `localgpt_gen_add_trigger` | Proximity/click/area trigger |
| `localgpt_gen_add_teleporter` | Teleporter portal |
| `localgpt_gen_add_collectible` | Collectible pickup |
| `localgpt_gen_add_door` | Interactive door |

### Physics

| Tool | Purpose |
|---|---|
| `localgpt_gen_set_physics` | Physics body |
| `localgpt_gen_add_collider` | Collision shape |
| `localgpt_gen_add_force` | Force / impulse |
| `localgpt_gen_set_gravity` | Gravity preset |

### Terrain & Sky

| Tool | Purpose |
|---|---|
| `localgpt_gen_add_terrain` | Procedural terrain |
| `localgpt_gen_add_water` | Water plane |
| `localgpt_gen_add_foliage` | Vegetation scatter |
| `localgpt_gen_set_sky` | Sky & atmosphere |

### Audio

| Tool | Purpose |
|---|---|
| `localgpt_gen_set_ambience` | Ambient soundscape |
| `localgpt_gen_audio_emitter` | Positional audio |

### WorldGen Pipeline

| Tool | Purpose |
|---|---|
| `localgpt_gen_plan` | Text → layout plan |
| `localgpt_gen_plan_from_note` | Vault markdown note → layout plan |
| `localgpt_gen_plan_from_roblox_trend` | Roblox trend summary → layout plan |
| `localgpt_gen_blockout` | Apply blockout |
| `localgpt_gen_modify_blockout` | Edit blockout |
| `localgpt_gen_populate` | Fill region |
| `localgpt_gen_set_tier` / `_role` | Entity tier/role |
| `localgpt_gen_evaluate` | Scene evaluation |
| `localgpt_gen_refine` | Auto-improvement loop |
| `localgpt_gen_navmesh` | Walkability grid |
| `localgpt_gen_regenerate` | Refresh regions |

### Export & World Skills

| Tool | Purpose |
|---|---|
| `localgpt_gen_export_screenshot` | Screenshot to file |
| `localgpt_gen_export_gltf` | Export glTF |
| `localgpt_gen_export_html` | Export HTML |
| `localgpt_gen_save` / `_load` | World skills |

### Commands

| Command | Purpose |
|---|---|
| `/localgpt:gen-status` | Check binary + relay |
| `/localgpt:plan-from-note <path>` | Plan layout from vault markdown file |
| `/localgpt:plan-from-roblox-trend <path>` | Plan layout from Roblox trend JSON file |
| `/localgpt:remember-worldgen` | Save WorldGen design rationale (rationale only; use the tool to attach references) |

Arguments are not required. Details are entered after the command runs.

## Development

```bash
npm install
npm run ci
```

`npm run ci` runs typecheck, tests, and `npm pack --dry-run` (via `pack:check`) so the published tarball matches `package.json` `files`.

Before release, run the manual smoke checks in [`docs/manual-test-checklist.md`](https://github.com/eiei114/pi-localgpt/blob/HEAD/docs/manual-test-checklist.md) (status, design-log search/save, platform notes).

Run the pack check alone:

```bash
npm run pack:check
```

## Release

This package uses npm Trusted Publishing — no `NPM_TOKEN` required.

```bash
npm version patch
git push
```

See [`docs/release.md`](https://github.com/eiei114/pi-localgpt/blob/HEAD/docs/release.md) for setup details.

## Security

Pi packages can execute code with your local permissions. Gen tools drive the Bevy 3D window via the `--connect` relay.

For vulnerability reporting, see [`SECURITY.md`](https://github.com/eiei114/pi-localgpt/blob/HEAD/SECURITY.md).

## Links

- npm: https://www.npmjs.com/package/pi-localgpt
- GitHub: https://github.com/eiei114/pi-localgpt
- Issues: https://github.com/eiei114/pi-localgpt/issues

## License

MIT