Skip to content

pstack: support Codex installation and native agents #734

Open

Description

@ririnto

Request

I'd like to use pstack in Codex, including poteto-mode and its agent workflows. Could you provide a supported installation guide and native agent definitions?

Related work

  • Draft PR #537 proposes Codex discovery and invocation metadata.
  • Issue #601 covers tool mappings and agent workflows.

I'd like a documented setup based on those proposals. If you prefer to track this in #601, I can add the request there.

Requested changes

  • Add a Codex marketplace entry and plugin manifest.
  • Preserve each skill's invocation policy.
  • Port the bundled agents to .codex/agents/*.toml and document their installation.
  • Map Cursor-specific tool calls to Codex, and list unsupported workflows.

Configuration examples

These examples use the repository's pstack/ directory. I checked the local 0.15.29 source but have not tested installation or workflow execution.

.agents/plugins/marketplace.json

{
  "name": "pstack",
  "interface": {
    "displayName": "pstack"
  },
  "plugins": [
    {
      "name": "pstack",
      "source": {
        "source": "local",
        "path": "./pstack"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Developer Tools"
    }
  ]
}

Resolve source.path from the repository root.

pstack/.codex-plugin/plugin.json

{
  "name": "pstack",
  "version": "0.15.29",
  "description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence.",
  "skills": "./skills/"
}

Keep the version aligned with the pstack release. Preserve manual invocation policies with the Codex metadata proposed in #537.

.codex/agents/poteto-agent.toml

This excerpt adapts pstack/agents/poteto-agent.md. Replace ... with the remaining adapted instructions before use.

name = "poteto-agent"
description = "Delegate for code-writing and helper tasks during poteto-mode."
developer_instructions = """
You are one of the parent's delegates, not the runner for poteto-mode itself.
Before doing any work, read the poteto-mode skill's SKILL.md in full,
including its inline Principles index. Use the absolute path supplied by the parent.
...
"""

Document where users install the agent files: .codex/agents/ for a project or ~/.codex/agents/ for personal use. Include the Codex equivalents of Cursor paths and tool calls.

Verification

Document one tested workflow that invokes poteto-mode and delegates work to poteto-agent. Include the installation steps, the expected result, and any limitations.

References

Activity

  1. deanrie commented on Oct 21, 2026

    @deanrie

    Hey @ririnto, thanks for writing the examples out rather than describing them. Of the four items, the marketplace entry and .codex-plugin/plugin.json are what #537 already proposes (still a draft), and the agent port plus the Cursor-to-Codex tool map is the ground #601 covers, including MaxFabian25's public adaptation with .codex/agents/*.toml files you can compare against your excerpt. What is new here is the ask for a documented, supported install path once those land, so this issue is fine standing on its own for that; no need to move it. One thing worth checking before relying on the developer_instructions approach: the parent has to pass an absolute SKILL.md path to each delegate, and in Codex the plugin install location differs from Cursor's, so the path convention should be part of the guide. The pstack owner decides whether Codex support ships as part of #537 or separately; this issue stays open as the request.

  2. ImSynem commented on Oct 21, 2026

    @ImSynem

    Adding install measurements for the supported-install-path question, since the issue notes installation wasn't tested. All runs used Codex CLI 0.163.0, the latest release, and pstack 0.15.29 at 190d287.

    As #637 notes, Codex falls back to .claude-plugin/marketplace.json, so these two commands already install pstack from harness/pstack/claude-code:

    codex plugin marketplace add cursor/plugins
    codex plugin add pstack@cursor-plugins

    The plugin lands in $CODEX_HOME/plugins/cache/cursor-plugins/pstack/0.15.29/, and Codex's skill list in the prompt names that absolute root. That bears on the path convention raised above.

    Codex's skill parser never reads disable-model-invocation. So the 55 skills that set it, poteto-mode included, all sit in Codex's automatic skill list and are open to implicit invocation.

    To measure the fix, the test copied the installed tree, added this agents/openai.yaml to each of those 55 skills, and installed the copy from a local marketplace. No SKILL.md changed.

    policy:
      allow_implicit_invocation: false

    codex debug prompt-input, run from an empty directory with a fresh CODEX_HOME, shows the change:

    Before After
    pstack skills in the automatic list 56 1
    pstack entries, o200k_base tokens 3,871 89
    Whole skills block, o200k_base tokens 4,364 573

    The one skill left is setup-pstack, which doesn't set the flag. The whole block also lists Codex's 4 built-in skills.

    Explicit use still works. In a codex exec run, $pstack:unslop loaded the full unslop SKILL.md into the turn. That model call went through a local proxy, which doesn't affect skill loading.

    This file is the sidecar that e84046f removed from the generator, along with the Codex tree, before #637 merged. Writing it into harness/pstack/claude-code would bring back that one step without the Codex tree, adapter or marketplace, and Cursor's pstack/ would stay unchanged. It would still reverse #637's choice to ship no Codex files. #537's route, sidecars committed under pstack/skills, would reach the claude-code tree too, since render() copies every file there. But Cursor installs would then carry them, and #537 predates 4 of today's 55 flagged skills. mattpocock/skills pairs the same flag and policy file in one plugin that Claude Code and Codex both install. This test didn't run Claude Code on the patched tree.

    Which route, if any, is the pstack owner's call. If the generator step is welcome back for the claude-code tree, I can open that PR. This covers install and invocation policy only. It doesn't test poteto-mode workflows, delegates given absolute SKILL.md paths, or tool mappings on Codex.

    Repro
    # Codex CLI 0.163.0. Each step uses a fresh CODEX_HOME and its own empty directory.
    count() { grep -o -- '- pstack:[a-z0-9-]*:' "$1" | sort -u | wc -l; }
    
    # Before: the existing marketplace entry
    export CODEX_HOME=$(mktemp -d)
    codex plugin marketplace add cursor/plugins --ref 190d28736eff128ec94f502a22c7fe0c4b56cd37
    codex plugin add pstack@cursor-plugins
    src=$CODEX_HOME/plugins/cache/cursor-plugins/pstack/0.15.29
    cd "$(mktemp -d)"
    codex debug prompt-input > before.json
    count before.json   # 56
    
    # After: copy the installed tree and add the sidecar to each flagged skill
    mkt=$(mktemp -d)
    mkdir -p "$mkt/.claude-plugin" && cp -R "$src" "$mkt/plugin"
    for f in "$mkt"/plugin/skills/*/SKILL.md; do
      if awk 'NR==1{next} /^---$/{exit} {print}' "$f" | grep -q '^disable-model-invocation: true'; then
        mkdir -p "$(dirname "$f")/agents"
        printf 'policy:\n  allow_implicit_invocation: false\n' > "$(dirname "$f")/agents/openai.yaml"
      fi
    done
    printf '{"name":"pstack-local","owner":{"name":"local"},"plugins":[{"name":"pstack","source":"./plugin"}]}\n' \
      > "$mkt/.claude-plugin/marketplace.json"
    export CODEX_HOME=$(mktemp -d)
    codex plugin marketplace add "$mkt"
    codex plugin add pstack@pstack-local
    cd "$(mktemp -d)"
    codex debug prompt-input > after.json
    count after.json    # 1
    
    # Explicit use. This step calls a model: run `codex login` in this CODEX_HOME first.
    codex exec --skip-git-repo-check '$pstack:unslop Rewrite this sentence plainly: "We leverage synergies to deliver value."' < /dev/null

    AI assistance: Codex ran these measurements and Claude drafted this comment.

  3. deanrie commented on Oct 22, 2026

    @deanrie

    Hey @ImSynem, that is the measurement the question needed: codex plugin add pstack@cursor-plugins already installs from the claude-code tree, Codex's parser ignores disable-model-invocation, and a per-skill agents/openai.yaml with allow_implicit_invocation: false takes the automatic skill list from 56 entries and 3,871 tokens down to 1 and 89 while explicit $pstack:unslop still loads. The open decision is exactly the one you name: bring the sidecar back as a generator step into the claude-code tree (reversing part of #637), or commit sidecars under pstack/skills as #537 does and accept them in Cursor installs. Your numbers turn that from a preference into a measurable trade, which is what the pstack owner needs to pick one. Delegate paths and tool mappings remain the #601 thread.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions