oh-my-open-pi

Pi Coding Agent extension package for model routing, tools, background tasks, and safety hooks.

Packages

Package details

extensionskillprompt

Install oh-my-open-pi from npm and Pi will load the resources declared by the package manifest.

npm report
$ pi install npm:oh-my-open-pi
Package
oh-my-open-pi
Version
0.1.4
Published
May 7, 2026
Downloads
733/mo · 38/wk
Author
takltc
License
MIT
Types
extension, skill, prompt
Size
1.6 MB
Dependencies
2 dependencies · 5 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ],
  "skills": [
    "./skills"
  ],
  "prompts": [
    "./prompts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

oh-my-open-pi

oh-my-open-pi 是一个 Pi Coding Agent 增强包。安装后可以在 Pi 里配置模型路由、agent 默认模型、任务分类模型、备用模型、工具开关、后台任务和安全规则。

安装

pi install npm:oh-my-open-pi

安装后打开配置界面：

pi config

启用 oh-my-open-pi，然后重启 Pi，或在 Pi 里执行：

/oh-my-open-pi-reload

配置文件

全局配置：

~/.pi/agent/oh-my-open-pi.jsonc

项目配置：

.pi/oh-my-open-pi.jsonc

项目配置优先级更高，适合给单个代码仓设置专属模型、agent 和工具策略。配置文件支持 JSONC，可以写注释。

最小模型路由配置

把下面内容放进 ~/.pi/agent/oh-my-open-pi.jsonc 或项目里的 .pi/oh-my-open-pi.jsonc：

{
  "model_fallback": true,
  "default_run_agent": "sisyphus",
  "agent_switch": {
    "shortcut": "ctrl+shift+a"
  },
  "agents": {
    "sisyphus": {
      "model": "openai-codex/gpt-5.5",
      "variant": "xhigh",
      "reasoningEffort": "xhigh"
    },
    "oracle": {
      "model": "openai-codex/gpt-5.4",
      "variant": "high",
      "reasoningEffort": "high"
    }
  },
  "categories": {
    "quick": {
      "model": "openai-codex/gpt-5.3-codex-spark",
      "variant": "low",
      "reasoningEffort": "low"
    },
    "deep": {
      "model": "openai-codex/gpt-5.5",
      "variant": "xhigh",
      "reasoningEffort": "xhigh"
    }
  }
}

model 使用 provider/model 格式。provider 需要在 Pi 里可用，或在本配置文件里注册。

每个内置 agent 名称会匹配对应的 OhMyOpenCode 工作模式、系统提示词和工具策略。当前内置 profile 包括：

sisyphus, hephaestus, oracle, librarian, explore, multimodal-looker,
prometheus, metis, momus, atlas, sisyphus-junior

切换当前 agent 路由：

/oh-my-open-pi-agent oracle

默认快捷键 Ctrl+Shift+A 会按当前配置的 agents 列表循环切换 agent。需要沿用 Tab 手势时，可以把快捷键配置成 tab：

{
  "agent_switch": {
    "shortcut": "tab"
  }
}

不带参数执行会列出当前配置的 agent。切换成功后，插件会立即调用 Pi 的模型和思考等级选择 API，后续请求也会继续使用这个 agent 对应的路由；带 category 的请求继续按 categories 路由处理。

agent 启动时，插件会把对应 profile 追加进 Pi 的 system prompt。prompt 可以覆盖内置 profile，prompt_append 会追加到内置 profile 后面；两者支持普通字符串和 file:// 路径。

全量模型路由配置

下面是一份完整的 agents 和 categories 路由示例，可以按你的团队模型策略直接调整：

{
  "model_fallback": true,
  "default_run_agent": "sisyphus",
  "agents": {
    "sisyphus": {
      "model": "openai-codex/gpt-5.5",
      "variant": "xhigh",
      "reasoningEffort": "xhigh"
    },
    "hephaestus": {
      "model": "openai-codex/gpt-5.5",
      "variant": "xhigh",
      "reasoningEffort": "xhigh"
    },
    "prometheus": {
      "model": "openai-codex/gpt-5.5",
      "variant": "xhigh",
      "reasoningEffort": "xhigh"
    },
    "oracle": {
      "model": "openai-codex/gpt-5.5",
      "variant": "xhigh",
      "reasoningEffort": "xhigh"
    },
    "librarian": {
      "model": "zai/glm-5-turbo",
      "variant": "high",
      "reasoningEffort": "high"
    },
    "explore": {
      "model": "zai/glm-5-turbo",
      "variant": "high",
      "reasoningEffort": "high"
    },
    "multimodal-looker": {
      "model": "openai-codex/gpt-5.5",
      "variant": "xhigh",
      "reasoningEffort": "xhigh"
    },
    "metis": {
      "model": "openai-codex/gpt-5.5",
      "variant": "xhigh",
      "reasoningEffort": "xhigh"
    },
    "momus": {
      "model": "openai-codex/gpt-5.5",
      "variant": "xhigh",
      "reasoningEffort": "xhigh"
    },
    "atlas": {
      "model": "openai-codex/gpt-5.5",
      "variant": "xhigh",
      "reasoningEffort": "xhigh"
    },
    "sisyphus-junior": {
      "model": "deepseek/deepseek-v4-pro",
      "variant": "max",
      "reasoningEffort": "max"
    }
  },
  "categories": {
    "visual-engineering": {
      "model": "kimi-coding/kimi-for-coding",
      "variant": "high",
      "reasoningEffort": "high"
    },
    "ultrabrain": {
      "model": "openai-codex/gpt-5.5",
      "variant": "xhigh",
      "reasoningEffort": "xhigh"
    },
    "deep": {
      "model": "openai-codex/gpt-5.5",
      "variant": "xhigh",
      "reasoningEffort": "xhigh"
    },
    "artistry": {
      "model": "kimi-coding/kimi-for-coding",
      "variant": "high",
      "reasoningEffort": "high"
    },
    "quick": {
      "model": "deepseek/deepseek-v4-flash",
      "variant": "max",
      "reasoningEffort": "max"
    },
    "unspecified-low": {
      "model": "deepseek/deepseek-v4-pro",
      "variant": "max",
      "reasoningEffort": "max"
    },
    "unspecified-high": {
      "model": "openai-codex/gpt-5.5",
      "variant": "xhigh",
      "reasoningEffort": "xhigh"
    },
    "writing": {
      "model": "deepseek/deepseek-v4-pro",
      "variant": "max",
      "reasoningEffort": "max"
    },
    "visual": {
      "model": "kimi-coding/kimi-for-coding",
      "variant": "high",
      "reasoningEffort": "high"
    },
    "business-logic": {
      "model": "openai-codex/gpt-5.5",
      "variant": "xhigh",
      "reasoningEffort": "xhigh"
    },
    "data-analysis": {
      "model": "deepseek/deepseek-v4-pro",
      "variant": "max",
      "reasoningEffort": "max"
    }
  }
}

常用字段：

  • agents: 给具体 agent 指定模型。
  • categories: 给任务分类指定模型。
  • model: 主模型，格式是 provider/model，Pi 内置 Kimi Coding Provider 写作 kimi-coding/kimi-for-coding，Z.ai 写作 zai/glm-5-turbo。
  • variant: 模型档位，例如 low、high、xhigh、max。
  • reasoningEffort: 推理强度。OpenAI Codex 使用 minimal、low、medium、high、xhigh；DeepSeek 使用 high、max；Anthropic 使用 minimal、low、medium、high、xhigh，Claude Opus 4.6 可用 max。
  • model_fallback: 备用模型策略字段（兼容性保留，当前为 inert 字段）。
  • default_run_agent: 默认运行使用的 agent。
  • fallback_models: 备用模型列表字段（兼容性保留，当前为 inert 字段，不触发自动重试）。
  • tools: 控制某个 agent 或分类可用的工具。
  • prompt_append: 给某个 agent 或分类追加固定提示。
  • prompt: 覆盖某个 agent 的内置系统提示词。

使用 routing 包裹模型路由

你也可以把模型路由集中放在 routing 里：

{
  "routing": {
    "model_fallback": true,
    "default_run_agent": "sisyphus",
    "agents": {
      "sisyphus": {
        "model": "deepseek/deepseek-v4-pro",
        "variant": "max",
        "reasoningEffort": "max"
      }
    },
    "categories": {
      "deep": {
        "model": "openai-codex/gpt-5.5",
        "variant": "xhigh",
        "reasoningEffort": "xhigh"
      }
    }
  }
}

顶层写法和 routing 写法可以同时使用。项目配置会覆盖全局配置，同名 agent 或 category 会按项目配置生效。

注册 Provider

如果你要接入 OpenAI-compatible 网关，可以在 providers 里注册：

{
  "providers": {
    "my-gateway": {
      "name": "My Gateway",
      "baseUrl": "https://gateway.example.com/v1",
      "apiKey": "MY_GATEWAY_API_KEY",
      "api": "openai-responses",
      "authHeader": true,
      "models": [
        {
          "id": "gpt-5.4",
          "name": "GPT-5.4",
          "reasoning": true,
          "input": ["text", "image"],
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          },
          "contextWindow": 200000,
          "maxTokens": 16000
        }
      ]
    }
  },
  "categories": {
    "deep": {
      "model": "my-gateway/gpt-5.4",
      "variant": "high",
      "reasoningEffort": "high"
    }
  }
}

apiKey 可以写环境变量名，运行 Pi 前把对应环境变量设好。

工具和安全规则

{
  "disabled_tools": [],
  "disabled_agents": [],
  "tools": {
    "grep": true,
    "glob": true,
    "ast_grep": true,
    "session": true,
    "background": true,
    "runtime": true
  },
  "background_task": {
    "command": "pi",
    "args": ["-p"],
    "maxConcurrent": 4
  },
  "hooks": {
    "bash_deny_patterns": [
      "rm\\s+-rf\\s+/"
    ],
    "protected_paths": [
      ".env",
      ".env.local",
      ".git"
    ],
    // 以下安全选项默认关闭，按需启用
    "truncate_tool_output": {
      "enabled": false,
      "maxChars": 120000
    }
  },
  // context 将 message 注入 agent system prompt（默认关闭）
  "context": {
    "enabled": false,
    "message": "优先使用项目现有约定，修改前先读取相关文件。"
  }
}

工具开关：

  • grep: 内容搜索。
  • glob: 文件匹配。
  • ast_grep: 结构化代码搜索和替换。
  • session: 会话查看工具。
  • background: 后台任务工具。
  • runtime: 运行时状态工具：
    • reload_runtime：重新加载 Pi 扩展、技能、提示词和主题。
    • tool_profile：显示当前激活的工具名称。

禁用特定 agent：在 disabled_agents 数组中列出 agent 名称（大小写不敏感），或在 agent 路由中设 "disable": true。被禁用的 agent 不会出现在命令列表、快捷键循环、补全和路由解析中。

单数 provider 兼容：原始 OpenCode 配置文件中的 "provider": { "name": {...} } （单数）会自动合并进 providers，等同 pi.registerProvider() 行为。

常用命令

查看已安装包：

pi list

更新包：

pi update npm:oh-my-open-pi

查看当前启用的工具：

/oh-my-open-pi-status

切换当前 agent 路由：

/oh-my-open-pi-agent hephaestus

循环切换当前 agent 路由：

Ctrl+Shift+A

默认快捷键来自 agent_switch.shortcut。设置为其他 Pi 支持的按键可以改绑定，设置为 false 可以关闭快捷键注册。Pi 的 tab 默认负责输入补全，覆盖它会在 Pi 里产生快捷键冲突诊断。

重新加载扩展：

/oh-my-open-pi-reload

后台子 agent：

delegate_task(description: "review plan", prompt: "Review .sisyphus/plans/app.md", agent: "momus")

查看后台任务输出：

background_output(taskId: "task-uuid")

取消后台任务：

background_cancel(taskId: "task-uuid")

后台 agent 继承规则：

  • 后台 agent 路由必须显式指定：启动后台任务时，只有明确传入 agent 参数才会设置 OH_MY_OPEN_PI_AGENT 环境变量；父进程当前激活的 agent 路由不会被自动继承。
  • 省略、空字符串或仅含空白字符的 agent 视为未提供，不会设置 OH_MY_OPEN_PI_AGENT，子进程按默认路由启动。
  • 合法的非空白 agent 字符串会原样透传给子 Pi 进程，即便该名称不是当前已配置的 agent 名称。子进程启动后在自己的 agent 路由解析中处理（匹配到已知 route 则应用对应策略，否则安全降级）。
  • 启动后台任务不会变更或覆盖父进程的当前激活 agent 路由。后台子进程的 agent 选择和父进程的后续请求互不影响。

迁移溯源

迁移依据、Pi native contract、原始 oh-my-openagent 功能映射和验证闸门记录在 docs/migration-trace.md。

以下 OpenCode 字段可安全保留在配置中，不会报错也不会触发任何行为：disabled_skills, disabled_hooks, disabled_commands, hashline_edit, runtime_fallback, experimental, new_task_system_enabled, agent_definitions。

推荐配置方式

通用 provider、默认 agent、常用 category 放在全局配置里：

~/.pi/agent/oh-my-open-pi.jsonc

项目专属模型、受保护路径和上下文提示放在项目配置里：

.pi/oh-my-open-pi.jsonc