Skip to content

feat: support pi-subagents-style JSON agent overrides - #171

Open
ESSO0428 wants to merge 2 commits into
tintinweb:masterfrom
ESSO0428:feat-integrate-pi-subagents-omo-style-json
Open

feat: support pi-subagents-style JSON agent overrides#171
ESSO0428 wants to merge 2 commits into
tintinweb:masterfrom
ESSO0428:feat-integrate-pi-subagents-omo-style-json

Conversation

@ESSO0428

@ESSO0428 ESSO0428 commented Jul 23, 2026

Copy link
Copy Markdown

Summary

This PR adds support for configuring existing agents and registering new agents through Pi's settings.json files using the same subagents.agentOverrides format as npm:pi-subagents.

JSON overrides make agent configuration easier to adjust temporarily on a global or per-project basis. Users can quickly switch an agent's model or thinking level according to the current task, available provider quota, or cost constraints without editing or duplicating its complete .md definition.

Fields such as model, thinking, systemPrompt, tools, and skills can be configured under:

subagents.agentOverrides.<agentName>

Local project settings can override only the fields that need to change while inheriting the remaining configuration from global settings or existing agent definitions.

When an overridden agent name does not already exist as a built-in or .md definition, it is automatically registered from the JSON configuration..


Configuration Priority

The resulting priority order is:

Priority Source Format
1 (highest) .pi/settings.jsonsubagents.agentOverrides JSON
2 ~/.pi/agent/settings.jsonsubagents.agentOverrides JSON
3 .pi/agents/*.md YAML frontmatter
4 ~/.pi/agent/agents/*.md YAML frontmatter
5 (lowest) Built-in agents such as general-purpose, Explore, and Plan Hardcoded

Local project overrides merge on top of global overrides on a per-field basis.

For example, a project configuration can replace only an agent's model and thinking values while retaining its globally configured tools and systemPrompt.


Usage

Global defaults

~/.pi/agent/settings.json

{
  "subagents": {
    "defaultModel": "opencode/deepseek-v4-flash-free",
    "agentOverrides": {
      "Explore": {
        "model": "github-copilot/gpt-5-mini",
        "thinking": "off"
      },
      "reviewer": {
        "model": "opencode/deepseek-v4-flash-free",
        "thinking": "max",
        "tools": ["read", "grep", "find", "ls", "bash"]
      }
    }
  }
}

Project-specific overrides

.pi/settings.json

Only the fields that differ from the global configuration need to be specified:

{
  "subagents": {
    "agentOverrides": {
      "reviewer": {
        "model": "openai-codex/gpt-5.4",
        "thinking": "high"
      },
      "fixer": {
        "model": "openai-codex/gpt-5.4",
        "tools": ["read", "grep", "find", "ls", "bash", "edit", "write"],
        "systemPrompt": "You are Fixer — a fast, focused implementation specialist. NO external research, NO delegation, NO planning."
      }
    }
  }
}

In this example, reviewer inherits its remaining fields from the global configuration.

The fixer agent does not need to exist as a built-in or .md definition. It is automatically registered from this JSON configuration.


Implementation

  • Adds src/nico-overrides.ts to read, merge, normalize, and apply JSON overrides
  • Exposes applyNicoOverrides() from src/agent-types.ts
  • Applies overrides after normal agent registration in reloadCustomAgents()
  • Converts compatible fields, including the skills representation, into the format expected by @tintinweb/pi-subagents
  • Leaves existing behavior unchanged when no overrides are configured

This compatibility layer reads agentOverrides from Pi's global and project settings.json files. It does not add the same option to this extension's own subagents.json configuration format.


Thanks to @nicobailon for creating the original pi-subagents configuration format that this compatibility layer builds upon.

ESSO0428 added 2 commits July 24, 2026 00:10
Read subagents.agentOverrides and subagents.defaultModel from Nico's
settings.json (~/.pi/agent/settings.json + .pi/settings.json) and
apply them as the highest-priority layer after the built-in .md chain
has resolved.

- New file: src/nico-overrides.ts — reader + applier for Nico-style overrides
- Modified: src/agent-types.ts — registerAgents() now reads and applies
  Nico overrides automatically (zero-touch for all call sites)

Priority:
  1. Local  .pi/settings.json  subagents.agentOverrides  ← highest
  2. Global ~/.pi/agent/settings.json  subagents.agentOverrides
  3. Local  .pi/agents/*.md
  4. Global ~/.pi/agent/agents/*.md
  5. Built-in DEFAULT_AGENTS

Closes #...
- applyNicoOverrides now auto-creates AgentConfig entries for override
  names that don't exist in the registry yet (no .md file needed)
- Add resolveNicoSkills() to convert Nico string[] -> tintinweb's
  true | string[] | false format
- Move override application out of registerAgents() into a separate
  exported function applyNicoOverrides(), called from reloadCustomAgents()
  in index.ts, so unit tests are not affected by real filesystem state
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant