PiMarg

Version 1.0.7 · MIT licensed · Pi Agent + Oh My Pi · by Sangyaa

PiMarg turns an ordinary prompt into a governed development path. It identifies the work boundary, selects one engineering method, discovers the models and tools the active runtime really provides, separates thinking from execution, records evidence, and stops before protected actions.

                           shared workflow core
                    intent · models · approvals · evidence
                                      │
                         ┌────────────┴────────────┐
                         ▼                         ▼
                     Pi adapter                OMP adapter
                  TypeBox · Pi events       Zod · OMP events
                         │                         │
                         └────────────┬────────────┘
                                      ▼
                  A discover → C plan review → plan gate
                                      │
                                      ▼
                       B build → verify → D review
                                      │
                                      ▼
                      security when needed → lessons

The same model-selection and approval logic lives in core/. Runtime-specific code is limited to adapters/pi/ and adapters/omp/.

Why PiMarg

• Confirms job/client versus personal work; job/client mode suppresses Sangyaa branding by default.
• Routes seven work types: idea, new feature, improvement, proactive bug fix, security, repository analysis, and business/sales analysis.
• Uses one primary Compound Engineering, Superpowers, GSD Core, or automatically selected workflow spine.
• Shows every current authenticated and enabled model, ranking the best fit for each stage first instead of pinning dated model names.
• Enforces that A and C use different underlying models, and B and D use different underlying models.
• Uses CodeGraph for repository architecture and impact when available, with LSP/AST or repository-native tools for exact code questions.
• Adds conditional testing, debugger, browser/desktop, security, Advisor, task, and memory routes only when detected.
• Tracks the plan, decisions, evidence, and one lesson under .agent-work/sessions/.
• Requires a one-use approval before delete/remove, push, merge, web publication, session sharing, or external-agent creation.

Compatibility

Capability	Pi Agent	Oh My Pi
Ordinary prompts enter the workflow	Pi bootstrap hook	OMP global rule
Shared skills and decision flow	Yes	Yes
Dynamic A/B/C/D model routing + high/low failover	Pi model registry	OMP model registry
Approval guard	Pi event adapter	OMP event adapter
Slash workflow entry points	Pi prompt templates	OMP commands
CodeGraph	CLI/integration when detected	MCP integration when configured
Advisor, checkpoint, security scan, Hindsight	Extension/fallback when detected	Native capability when enabled
Parallel agents	Only when a compatible task extension exists	Native task/workflow routes when available

Tested locally against Pi Agent 0.85.1 and OMP 18.2.1. Optional features are always capability-detected, so their absence produces a recorded fallback rather than a false success claim.

Try the demo

Open demo/pi-marg-v1.0.html in a modern browser. It is self-contained and offline. Use Play Flow for a walkthrough or Presenter Mode to hide the configuration panel.

Install

Review extensions before installation: both Pi and OMP packages execute with your local user permissions.

Preview the local installation commands:

./scripts/install.sh --runtime pi
./scripts/install.sh --runtime omp

Apply one runtime:

./scripts/install.sh --runtime pi --apply
./scripts/install.sh --runtime omp --apply

Install both only when you use both CLIs:

./scripts/install.sh --runtime both --apply

Install PiMarg from the Pi package catalog/npm:

pi install npm:@sangyaahub/pi-marg

Install the global OMP launcher:

npm install --global @sangyaahub/pi-marg

Or install Pi and OMP directly from this GitHub repository:

pi install https://github.com/sangyaahub/pi-marg
omp plugin marketplace add sangyaahub/pi-marg
omp plugin install --scope user pi-marg@pi-marg-marketplace

The npm command launches OMP; the OMP plugin installation supplies PiMarg's extensions, skills, commands, and rules. Install both when you want to start the complete workflow with pi-marg from any repository.

Configure models

Authenticate providers using the active runtime's normal login flow, then run:

/auto-models choose

The router shows every model in the live authenticated and enabled registry. Stage-appropriate choices appear first and all other enabled choices remain selectable. Reopening /pi-marg highlights the saved selector; Enter keeps it and activates the first required stage model. It does not promise that a subscription route is free or unlimited. See MODEL-SETUP.md.

Custom OpenAI-compatible provider

When OMP has no models yet, /pi-marg can register a custom provider without leaving the intake. It asks for a provider id, display name, base URL, env var name, and model ids. models.yml stores apiKey: YOUR_ENV_VAR. The secret goes only in ~/.omp/agent/.env. After the runtime reloads, every model from that provider is offered at A, B, C, and D. A and C must still be different models, and B and D must still be different models. With only one model, PiMarg says so before stage A and lets you add another model or stop before the paired stage.

CheaperInference below is one worked example of that same shape, not the only custom provider PiMarg accepts.

CheaperInference (Kimi and GLM)

Oh My Pi does not ship CheaperInference. Register it once, then /auto-models choose and /pi-marg offer its models at every stage. A and C must be different models. B and D must be different models.

1. Create a dashboard key. Current keys begin with ci_live_.
2. Store it in ~/.omp/agent/.env, which Oh My Pi loads on startup:

CHEAPER_INFERENCE_API_KEY=ci_live_your_key

3. Add the provider to ~/.omp/agent/models.yml. apiKey is the environment-variable name, not the secret. Confirm the live ids before relying on this list:

curl https://api.cheaperinference.com/v1/models \
  -H "Authorization: Bearer $CHEAPER_INFERENCE_API_KEY"

providers:
  cheaperinference:
    baseUrl: https://api.cheaperinference.com/v1
    api: openai-completions
    apiKey: CHEAPER_INFERENCE_API_KEY
    authHeader: true
    compat:
      supportsStore: false
      supportsDeveloperRole: false
      supportsReasoningEffort: true
      supportsStrictMode: false
      toolStrictMode: none
      thinkingFormat: openai
      reasoningContentField: reasoning_content
      requiresReasoningContentForToolCalls: true
      maxTokensField: max_tokens
      reasoningEffortMap:
        xhigh: max
        max: max
    models:
      - id: kimi-k3
        name: Kimi K3
        reasoning: true
        input: [text, image]
        contextWindow: 1000000
        maxTokens: 131072
        tokenizer: kimi-k2
      - id: glm-5.3
        name: GLM 5.3
        reasoning: true
        input: [text]
        contextWindow: 1000000
        maxTokens: 131072
        tokenizer: glm5
      - id: glm-5.3-flash
        name: GLM 5.3 Flash
        reasoning: true
        input: [text, image]
        contextWindow: 1048576
        maxTokens: 131072
        tokenizer: glm5
      - id: glm-5.2
        name: GLM 5.2
        reasoning: true
        input: [text]
        contextWindow: 1048576
        maxTokens: 131072
        tokenizer: glm5

4. Check that Oh My Pi can see them, then pick any of them at each stage:

omp models find cheaperinference

Stage	One valid pick
A discover	cheaperinference/kimi-k3
C plan review	cheaperinference/glm-5.3
B build	cheaperinference/glm-5.3
D code review	cheaperinference/kimi-k3
high backup	cheaperinference/kimi-k3
low backup	cheaperinference/glm-5.3-flash

Swap any row. The picker rejects the run only when A equals C, or B equals D. Recovery stays off until both backups are saved. This route bills a wallet on each call. The same steps are in MODEL-SETUP.md.

Start a workflow

From a terminal in the repository you want to work on, run either:

pi-marg start
pi-marg "add CSV export to this repository"

pi-marg start opens OMP and asks for the work prompt. Supplying a prompt starts the same guided flow immediately. Inside an existing OMP session, invoke:

/pi-marg
/pi-marg add CSV export to this repository
/auto add CSV export to this repository

The native picker asks for work boundary, work type, workflow skill, every model required by that work type, then two distinct runtime backups: high first and low second. Automatic recovery stays disabled until both are saved. It shows only models reported as authenticated and enabled by OMP, with recommended fits first.

stage model hits quota
          │
          ▼
   OMP/Pi native retry
          │ still failed
          ▼
   high backup ──fails──► low backup
          │                    │
          └──── notify + resume┘

PiMarg switches only after a positively identified terminal usage-limit/quota failure (or a settled model-execution tool failure such as external Devin or a subagent); a temporary 429/rate-limit response does not consume a backup. It records and deduplicates each failure, advances from high to low only when the active high model itself fails, notifies the user, and resumes with an instruction to inspect current state before repeating any side effect. If both backups are exhausted, it stops with an actionable request to run the model chooser again.

Useful entry points:

• /auto-models choose — refresh A/B/C/D choices and the high/low recovery pair.
• /auto-runtime status — show detected capabilities and fallbacks.
• /auto-review plan|code — run the independent review contract.
• /auto-status — show the current ledger and evidence.
• /auto-close — verify completion and write the session lesson once.

On Pi these are prompt templates. On OMP they are command files. Ordinary new substantive prompts also enter the workflow automatically: Pi uses a lightweight bootstrap hook, while OMP loads the packaged global rule. The workflow instructions and state contract are shared.

Protected actions

The default policy is ask. A protected action remains blocked until the complete next user message is exactly one of:

APPROVE ACTION: delete-remove
APPROVE ACTION: push-main
APPROVE ACTION: merge-pr
APPROVE ACTION: post-web

Each phrase permits one matching call and is then consumed. Set PIMARG_APPROVAL_POLICY=allow before starting the runtime only when intentionally enabling automated protected actions. UNIVERSAL_AUTO_MODE_APPROVAL_POLICY and OMP_AUTO_MODE_APPROVAL_POLICY remain recognized for migration.

CodeGraph policy

For an existing repository, preview setup first:

./scripts/setup-codegraph.sh /absolute/path/to/repository

Apply after reviewing the preview:

./scripts/setup-codegraph.sh --apply /absolute/path/to/repository

OMP can expose CodeGraph through .mcp.json. Pi uses a detected CodeGraph CLI or another installed integration. When CodeGraph is missing, the workflow may use precise repository-native tools, but it must not claim a repository-wide architecture or impact scan occurred.

Project structure

core/                    shared policy and routing logic
adapters/pi/             Pi extensions and prompt templates
adapters/omp/            OMP extensions
skills/                  shared workflow skills
commands/ agents/ rules/ OMP-native resources
demo/                    offline interactive presentation
tests/                   shared core and adapter contract tests

Validate

./scripts/validate.sh
bun test tests

License

PiMarg is an open-source project by Sangyaa. Product branding uses Sangyaa's official mark and palette; see BRAND.md for permitted use.

Copyright © 2026 Sangyaa and PiMarg contributors. Released under the MIT License. Everyone may use, copy, modify, merge, publish, distribute, sublicense, or sell copies subject to the license notice and warranty disclaimer.

Contributions are welcome; see CONTRIBUTING.md. Report vulnerabilities using SECURITY.md.