GedPi

A batteries-included Pi package with an always-on workflow for clarifying, documenting the spec, and implementing work in bounded slices.

Requires Node.js 22 or newer.

What It Does

• Starts with the full Ged workflow always active — the agent clarifies, runs skill-fit, plans, implements, and verifies in bounded slices.
• Keeps approved standards and concise project facts durable without generating placeholder documents.
• Scopes specs, tasks, verification, attempt history, and recovery evidence by immutable work ID while authoritative runtime state stays machine-readable.
• Adds a repo map that indexes supported source files, ranks them by structure plus recent activity, and injects a compact codebase-awareness block into Ged prompts.
• Bundles web search, native micro-UI via Glimpse, native git diff review, prompt-template-powered workflow commands, and automatic updates out of the box.
• Documents a main-owned intelligence orchestration model: keep the Ged brain as decision owner while using explorer, planner, reviewer, verifier, and optional worker subagents for additional throughput.

Install

npm install -g gedpi

Then run it in any project:

cd your-project
gedpi

Features

Bundled Skills

GedPi ships skills that power the Ged workflow and skill-discovery stack:

• ged-init — first-turn .ged/ initialization and migration
• ged-planning — spec writing and task decomposition into bounded slices
• ged-execution — implementation of individual task slices
• ged-verification — post-implementation checks and state updates
• ged-escalation — automatic escalation when a slice repeatedly fails
• find-skills — discovering relevant skills from registries and repos
• skill-creator — creating reusable project-specific skills only when a real capability gap warrants durable knowledge
• brainstorming — structured planning and task creation flows

Repo Map

GedPi now includes a SoulForge-style repo map for codebase awareness.

The first shipped version includes:

• incremental indexing of supported repo files while respecting .gitignore
• symbol/import extraction for TypeScript/JavaScript-family files with graceful fallback for partial/unsupported cases
• graph-aware ranking blended with current-turn boosts from recent reads, edits, writes, and prompt mentions
• budget-aware prompt rendering so Ged gets a compact ranked view of important files and exported symbols
• runtime cache storage under .pi/repo-map/ rather than durable .ged/ memory

Current deferred roadmap items remain intentional and visible in docs rather than hidden in code:

• semantic symbol summaries
• git co-change ranking
• richer analysis views such as dead-code or clone-detection signals
• broader parser/language coverage as needed

Bundled Extensions

Extension	What it does
ged-core	Brain workflow, .ged/ durable memory bootstrap, header, session init, shortcuts, updater, and system prompt injection
glimpseui	Native micro-UI windows and the optional floating companion widget
pi-web-access	Web search and fetch tools for the agent
pi-subagents	workflowScript subagent runtime for Ged explorer/planner/plan-reviewer/verifier roles, native child-supervisor coordination, and optional settings-gated workers; generic builtins are hidden by default
pi-intercom	Optional messaging between independent Pi sessions; spawned-child decisions use pi-subagents' native supervisor channel
pi-diff-review	Native git diff review window that inserts structured review feedback into the editor
pi-prompt-template-model	Prompt templates can set thinking/model behavior and back commands like /commit and /push
@plannotator/pi-extension	Plan/code review UI; GedPi planned-work approval prefers native Glimpse, falls back to Plannotator's browser UI, and binds approval to the exact current plan artifacts
~/.gedoc/settings.json	GedPi workflow preferences (commit behavior, draft-plan review) via /ged-settings command
native Pi UI	GedPi uses Pi's native input, footer, working indicator, command palette, user-message, tool, and read rendering

Native Micro-UI

GedPi bundles Glimpse for native micro-UI windows. The bundled glimpse skill lets the agent open native dialogs, forms, previews, and other rich UI when a task benefits from it.

Commands

Command	Description
/diff-review	Open a native git diff review window and insert feedback into the editor
/commit	Review local changes and create a descriptive conventional commit
/push	Push the current branch, with automatic recovery flow if the first push fails
/settings	Open Pi settings, including native Pi theme selection
/update	Check for GedPi updates
/grill-me	Ask one concise question at a time when a genuine user-owned decision is unresolved
/rtk	Install RTK and check Ged's automatic bash-side RTK routing (status, install)
/ged-agents	Configure adaptive/role-specific staffing, models, canonical thinking levels, ordered fallbacks, critique, native supervisor coordination, opt-in peer messaging, and writer capacity. Use /ged-agents profile adaptive for the validated GPT-5.6 profile and /ged-agents status for diagnostics.
/ged-settings	Configure workflow preferences, including accepted-plan review: no extra review, chat approval, or visual approval (Glimpse preferred, browser fallback)

Auto-Updater

GedPi checks for new versions on startup (cached, re-checks every 4 hours). When an update is available, it prompts to install and restart. Pi's own update notification is suppressed to avoid duplication.

Ged Workflow

GedPi uses three governance modes, independent of optional execution staffing:

• read-only — inspect, explain, research, or report without repository mutation;
• direct-change — clear, bounded, reversible work with a deterministic check;
• planned-change — ambiguous, high-risk, explicitly planned, or otherwise direct-change-ineligible work.

For mutation, the brain opens task-scoped work with ged_work. The runtime resolves mode from structured ambiguity, risk, minimum-mode, and direct-change evidence, then stores the authoritative decision in .ged/runtime/<work-id>/governance.json. A fresh request must explicitly open or continue the exact work item before mutation.

The governed ged_memory tool creates substantive PROJECT summaries, read-only reports, root CONTEXT, ADRs, and explicit handoff projections only when needed. ged_skill separately creates reusable Pi-native project skills with durable reason and content-hash provenance; neither tool turns Markdown into authority.

Planned-change work may write its active SPEC.md, TASKS.md, and TESTS.md before acceptance. With visual review selected, the final artifacts are shown through gedpi_plan_review; approval is bound to their exact current bytes before ged_governance accept-plan, so changed or stale plans require another review. Source mutation then requires role-neutral accepted-plan evidence bound to those exact bytes. Codex and other models use Pi's native read, bash, write, and edit tools; GedPi does not install compatibility aliases. The runtime snapshots known and unknown mutation-capable tools, executes declared verification commands, and requires the already-staged work scope to exactly match the verified repository snapshot before commit. Proven HEAD advances become milestones and do not close work automatically. ged_lifecycle explicitly pauses, resumes, completes, abandons, or supersedes an exact work ID with an auditable reason and timestamp; terminal work never reopens.

On the first agent turn GedPi also:

• initializes only required machine metadata and lazily creates substantive human artifacts;
• preserves legacy branch/root checkpoint data in ignored byte-exact backups, never as authorization;
• migrates substantive legacy glossary and decision content to root CONTEXT.md and sparse docs/adr/ records while retaining ambiguous data;
• discovers external project standards and asks whether to retain them;
• maintains a compact runtime repo map under ignored .pi/ state;
• runs skill-fit and installs/creates project skills only for real reusable capability gaps.

Execution Staffing

/ged-agents on|off changes available capacity, not governance. GedPi recommends solo, assisted, coordinated, or high-stakes staffing from decomposability, context spread, difficulty, and budget; the coordinator owns the final profile. Scout, planner/reviewer, verifier, Worker, and Smart Worker capabilities are distinct from their model bindings. Their results are evidence proposals only: no role name, launch, completion, or fallback authorizes mutation.

/ged-agents profile adaptive validates the live registry before saving. Its defaults are GPT-5.6 Sol/low for Scout, Luna/max for Worker, and Sol/high for Smart Worker, with explicit same-provider fallbacks; existing role overrides win. Missing configured chains produce diagnostics without silently switching providers or preventing startup. maximum and legacy reasoningEffort migrate to Pi's canonical max.

GedPi permits one writer in the current checkout at a time. Parallel writers must use pi-subagents managed worktree: true; dynamic or aliased workflow launches fail closed when isolation cannot be proven. Ordinary Workers are leaf agents. Read-only role contracts omit bash/edit/write. Smart Worker has depth-one fanout, and an inherited public pi-subagents capability ceiling limits nested children to read-only Ged agents and non-mutating tools. Native contact_supervisor/subagent_supervisor handles child decisions and plan-changing discoveries; routine completion uses normal results. External pi-intercom peer messaging is separately opt-in and may only send verified facts/dependency updates to an exact user-directed independent-session target.

Current guard boundary

GedPi's runtime guards are an accident-prevention and evidence boundary, not an OS sandbox. They currently enforce request binding and authoritative governance for known mutation-capable tools, mutating bash, and unknown extension tools; audited, shell-free inspection forms such as pwd, uname, and bounded Git status/revision/diff/log/show/current-branch commands remain available without mutating work. Chaining, redirection, substitution, helper/output flags, npm scripts, and ambiguous Bash stay governed and snapshot-observed. The runtime protects runtime-owned .ged paths through resolved symlinks, durably records pending operations, binds plans and verification to canonical SHA-256 snapshots, rejects unrelated staged paths, and records commit milestones only after HEAD advances to the exact verified index tree. Commit pairing survives restart and stable snapshots reject continuously changing repositories. Async current-checkout workers retain a durable checkout-scoped writer lease and pending mutation until their exact completion event records pre/post content. Independent Pi processes see the same lease; restart recovery only reclaims it after pi-subagents status proves the run terminal. External processes outside Pi remain outside this boundary.

Durable Memory

GedPi's memory is lazy and current-state oriented. Fresh initialization creates only .ged/VERSION, .ged/.gitignore, standards-import metadata, an ignored session pointer, and bootstrap META.json. It does not create placeholder project, planning, progress, status, handoff, or skill files.

Substantive project knowledge has one canonical destination:

• .ged/PROJECT.md — concise agent-oriented goal, users, constraints, and success criteria, created on the first real write;
• root CONTEXT.md — canonical project/domain vocabulary;
• docs/adr/*.md — sparse decisions for meaningful trade-offs;
• .ged/STANDARDS.md — explicitly approved, content-hash-bound repository instructions;
• .agents/skills/<name>/SKILL.md — explicit reusable project skills using Pi's native trusted-project discovery. Ged records provenance lazily in .ged/SKILLS-STATE.json and never deletes a skill because a task closed.

Work artifacts are proportional to mode and scoped by immutable work ID:

.ged/work/<work-id>/
├── META.json                  immutable machine identity (all mutating work)
├── DIRECT.md                  concise scope/check record (direct-change only)
├── SPEC.md                    ┐
├── TASKS.md                   ├ planned-change only
├── TESTS.md                   ┘
└── tasks/<task-id>/
    ├── BRIEF.md
    ├── HISTORY.json
    └── RECOVERY.md

Repeated task IDs such as T01 cannot collide across work items. Read-only work opens no mutating work; an optional report is created only when there is substantive report content.

.ged/runtime/<work-id>/governance.json remains the sole machine authority. STATE.md and SESSION-SUMMARY.md are optional, explicit status/handoff projections and are never parsed back into guards. Session pointers live under .ged/runtime/active-work/; legacy checkpoints and v2 memory receive byte-exact ignored backups plus idempotent migration metadata. See the artifact contract for every producer, consumer, authority level, lifecycle, and migration rule.

Development

git clone https://github.com/edgyarmati/gedpi.git
cd gedpi
npm install
npm run chat    # launch locally in dev mode

Command	Purpose
npm run chat	Launch the local gedpi executable
npm test	Run the test suite (Vitest)
npm run check	TypeScript type-check
npm run lint	Biome lint + format check
npm run verify	Full local/CI gate: type-check, lint, test, and package dry-run
npm run format	Auto-fix lint and formatting
npm install -g .	Install globally from local checkout

CI/CD

• Pull requests and pushes to main run npm run verify.
• The docs are part of the test contract.
• Pushing a gedpi-v* tag runs the release workflow, verifies the repo again, publishes to npm through GitHub Actions trusted publishing with provenance, and then creates the GitHub release.
• Trusted publishing still requires npm-side setup for this repository/workflow in the npm package settings.

Attribution

GedPi builds on the Pi ecosystem. See CREDITS.md.

License

MIT. See LICENSE.