Pi LocalGPT

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 — 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:

pi install npm:pi-localgpt

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

pi install npm:pi-localgpt -l

Pin a specific version when you want reproducible installs:

pi install npm:pi-localgpt@0.10.4

Or install from GitHub:

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

Try it without permanently installing:

pi -e npm:pi-localgpt

Local development:

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:

{
  "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. Bridge failures may include a short, sanitized localgpt-gen stderr excerpt to help identify relay, protocol, binary, or missing-window causes. 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 for the full workflow guide.

Vault design memos: docs/vault-note-plan-layout.md.

Roblox trend summaries: 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

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 (status, design-log search/save, platform notes).

Run the pack check alone:

npm run pack:check

Release

This package uses npm Trusted Publishing — no NPM_TOKEN required.

npm version patch
git push

See 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.

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