omp packages

pi-localgpt0.10.15

Pi extension for LocalGPT — unified MCP bridge. 51 curated tools for design-log + Gen 3D world building.

GitHub Actions Published 4 hours ago MIT ~665 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Did it work for you?

Result

One report per person. A new report replaces your old one.

Reports 0

No reports yet.

Readme

Pi LocalGPT

Join dotfield.xyz on Discord

CI Publish npm version npm downloads License: MIT Pi package Trusted Publishing Buy Me A Coffee

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

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. If it is unreachable, keep the interactive Bevy window open, verify 127.0.0.1:9878, and confirm localgpt-gen is on this Pi session's PATH.
  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.

End-to-end WorldGen transcript: examples/worldgen-pipeline.md.

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 and Pi SDK smoke)
docs/ Supporting docs (release, manual checklist, SDK verification evidence)

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_memory_search / _get / _save / _log Deprecated legacy aliases for the design-log tools above — planned removal in v0.12.0
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, the isolated Pi SDK 1.2.0 host smoke, 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.

Version bumps merged to main do not trigger a release or npm publication. An authorized human must start the release workflow; see docs/release.md for 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

License

MIT