pi-consult

A Pi extension for user-initiated, configurable multi-stage consultations with one or more models.

Like this extension? See my other Pi extensions.

Requirements

• Pi 0.84.1 or later
• Node.js 22.19.0 or later for package development
• Authenticated model providers configured through Pi

Installation

Install from npm:

pi install npm:@arcanemachine/pi-consult

Or install directly from GitHub:

pi install git:github.com/arcanemachine/pi-consult

For local development:

pi -e ./src/index.ts

Quick start

Add a pi-consult namespace to global ~/.pi/agent/settings.json or trusted project <project>/.pi/settings.json:

{
  "pi-consult": {
    "models": {
      "smart": { "model": "provider/model-id" },
      "lateral": { "model": "another-provider/another-model" }
    },
    "workflows": {
      "review": {
        "description": "Get two independent reviews",
        "context": true,
        "stages": [
          {
            "prompt": "Review the request independently and identify risks.",
            "consultants": ["smart", "lateral"]
          },
          {
            "prompt": "Synthesize the preceding reviews into one recommendation.",
            "consultants": ["smart"]
          }
        ]
      }
    }
  }
}

Consultations are explicitly user-driven. Run the command:

/consult review --context What should I reconsider?

A successful consultation displays its result and then resumes the active Pi turn with that result in context. Failed consultations display an error without resuming the turn. The prompt is optional; a workflow can run with no ad hoc prompt when its configured instructions and optional context provide enough subject matter.

A lateral-thinking workflow can deliberately separate familiar assumptions from unconventional alternatives before a consultant synthesizes the result:

{
  "workflows": {
    "lateral-thinking": {
      "stages": [
        {
          "prompt": "Defamiliarize the request. Separate hard constraints from assumptions and restate the problem without assuming the current approach is correct.",
          "consultants": ["smart"]
        },
        {
          "prompt": "Think laterally. Use inversion, analogy, constraint removal, changes of scale, and surprising reframings. For every alternative, state which assumption it breaks and which hard constraints it preserves.",
          "consultants": [
            "smart",
            {
              "alias": "lateral",
              "prompt": "Prefer surprising but practical alternatives that could break a habitual cycle of thought."
            }
          ]
        },
        {
          "prompt": "Compare the alternatives against the hard constraints. Preserve the strongest non-obvious idea rather than averaging everything into the familiar approach. Recommend one direction and a quick way to falsify it.",
          "consultants": ["smart"]
        }
      ]
    }
  }
}

Configuration

The external configuration has exactly two keys: models and workflows.

The extension applies conservative bounds: configuration files and settings fragments are limited to 512 KB, with at most 100 model aliases, 100 workflows, 20 stages per workflow, and 20 consultants per stage. Ad hoc prompts are limited to 8,000 characters; serialized conversation context and stage handoffs to 24,000 characters each; each consultant response to 12,000 characters; and the final displayed result to 48,000 characters. Validation diagnostics are capped at 100 entries and 20,000 characters. Bounds are reported in structured details when they affect a consultation.

• A model alias maps to a provider/model-id selection. Pi resolves the model and its authentication; credentials do not belong in this configuration.
• A workflow contains sequential stages.
• Consultants in one stage run concurrently.
• A consultant is an alias string or { "alias": "...", "prompt": "..." }.
• Every successful stage's labeled outputs are passed to every consultant in the next stage.
• A stage failure stops downstream stages. There are no automatic retries or hidden distillation calls.
• Configure a final one-consultant stage when you want one explicit synthesis response. A multi-consultant final stage returns every response.

Configuration sources

The package-owned file ~/.pi/agent/pi-consult.json, when present, is authoritative and contains the models and workflows object directly (without a pi-consult wrapper). It is not merged with settings.json.

If that file exists while a pi-consult namespace is also present in global settings or trusted project settings, the configuration is rejected as ambiguous. A malformed standalone file is an error and never silently falls back to settings.

Without the standalone file, Pi settings are merged in the normal order: global settings first, then trusted project settings. Untrusted project settings are ignored.

Conversation context

Set context: true on a workflow or use the --context command flag to include the active compaction-aware conversation. The extension serializes that conversation as reference material. It does not copy Pi's system prompt, tool definitions, loaded skills, or AGENTS files into consultant requests.

Consultants are permanently text-only. They cannot call tools, spawn child agents, inspect files, or modify the parent session.

Command

/consult <workflow> [--context] [prompt]

The command is the sole consultation entry point; models cannot invoke it as a tool. It displays a visible versioned consultation result and resumes the active parent turn only after a successful consultation. Configuration and operational failures are displayed and notified without triggering another turn. Workflow names and --context have autocomplete support.

The command returns labeled final outputs, bounded diagnostics, and aggregated nested model usage in its visible result.

Development

npm run format:check
npm run typecheck
npm run test
npm run build
npm pack --dry-run

Verify user-facing behavior against a running isolated Pi session before release.

License

MIT