Text of github.github.com › gh-aw › reference › engines › pi as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Pi reference | GitHub Agentic Workflows

Skip to main content Pi reference For first-time setup, see Using Pi . Shared options are in AI engines . Providers and authentication Section titled “Providers and authentication” Model prefix Credential copilot/ or no prefix copilot-requests: write or COPILOT_GITHUB_TOKEN anthropic/ ANTHROPIC_API_KEY openai/ or codex/ CODEX_API_KEY or OPENAI_API_KEY google/ GEMINI_API_KEY The default Pi version is 1.3.0 . Copilot defaults to copilot/auto with the gateway; native execution without the gateway retains copilot/gpt-5.4 . auto delegates selection to the gateway and need not appear in its concrete-model inventory.

OpenAI/Codex routes use the Responses API, not Chat Completions. Without a model , engine.model , or engine.model-routing , Pi on GitHub Copilot inference uses model routing with goal: cost and mode: auto for its main agent. Pi has no model variables, so this default isn’t bypassed at run time; set top-level model-routing: false to opt out, or set a model. Threat detection defaults to Copilot regardless of Pi’s provider.

Supply its separate Copilot credential or configure another detection engine . Capabilities and limitations Section titled “Capabilities and limitations” Pi supports native MCP tools and resources, codemode, tool search, provider-prefixed models, and workflow-installed Pi packages. Native MCP connects only to the compiler-managed gateway; provider and GitHub credentials remain outside the sandbox. Safe-output instructions use native MCP by default.

Workflows with tools.bash: false must explicitly set tools.cli-proxy: false and use native tools. Explicit tools.cli-proxy: true selects CLI-only instructions for mounted safe-output tools, just as it does for other MCP-capable engines. GitHub gh-proxy mode changes GitHub reads only; it does not disable native safe-output tools. Codemode batches tool calls and reduces results before they enter model context. Its classifier and image-generation APIs are available when the configured provider route supports those model types.

Custom providers still need a compatible API-proxy target and credentials; enabling codemode does not grant additional credentials or network access. For Copilot models using the Responses API, gh-aw disables grammar-based custom tools ( model.compat.supportsOpenAIGrammarTools: false ) so Pi sends codemode as a JSON-schema function tool. Codemode remains enabled; the Copilot compatibility adapter does not accept its custom-tool format.

Other provider routes retain their configured compatibility settings. Option Pi behavior max-turns , max-ai-credits Enforced by the AWF inference proxy. max-tool-calls Pre-dispatch limit covering local, MCP, and nested codemode calls. max-tool-denials Stops inference after repeated policy denials. tools.bash Supports disabling bash, executable-name rules, exact multiword commands, and explicit argument wildcards ( :* or * ).

Restricted commands reject shell comments, dynamic expansions, redirections, grouping, and background execution. tools.edit: false Disables native edit and write tools. engine.bare: true Disables automatic context, skill, prompt-template, extension, and theme discovery; retains explicit workflow infrastructure extensions and workflow-declared or imported inline skills. engine.extensions Installs npm, pinned git, or local Pi packages into the managed runtime directory. engine.driver: pi_agent_core_driver.cjs Uses the full coding-agent SDK session layer, including tools, resources, compaction, and retries. engine.driver: pi_rpc_driver.cjs Runs a headless RPC subprocess through Pi’s RPC client.

In bare mode, ambient repository and user skills are not discovered. Inline skills ( ## skill: blocks) that activation extracts from the workflow, its imports, or runtime imports remain available: before Pi starts, gh-aw reads the list of skills activation extracted and passes one explicit --skill /tmp/gh-aw/pi-agent-dir/skills/<name>/SKILL.md per skill to the CLI, sub-agents, and the SDK and RPC drivers. Workflows without inline skills get no --skill arguments.

Project-local executable resources remain untrusted by default. Workflow-installed packages and activation-installed skills use the managed agent directory. Model catalog metadata preserves thinking, vision, token limits, pricing, and cache lifetimes through gateway routing. Workflow system instructions remain separate from user instructions so compaction does not summarize them away. When AWF /reflect completes model discovery and reports reasoning-effort support for the selected provider and model, Pi uses that capability information instead of model-name exceptions.

If discovery is incomplete or reflection does not report reasoning capability data, Pi retains the model catalog or engine.config.model reasoning setting. Missing effort fields alone do not disable reasoning. Custom executables without the npm SDK must supply complete model metadata ( reasoning , input , contextWindow , and maxTokens ) in engine.config.model . The integration runs Pi headlessly; terminal UI controls, interactive authentication, and /share uploads are not workflow outputs.

Native provider fixes, prompt-cache behavior, model switching, codemode worker limits, and session tool restoration come from the installed Pi release. The kimi-coding provider uses Chat Completions in v1.3.0; custom native base URLs must include /v1 . Sandboxed custom routes still require a compatible AWF endpoint. The built-in tools.playwright integration uses playwright-cli ; omit its mode field. Native tools.web-search , max-continuations , native engine.agent selection, and custom engine.harness scripts remain unsupported.

Custom drivers must implement their own policies and cannot opt into the built-in aggregate tool budgets. Pi resolves model aliases for the main model and for sub-agents with the same rules as Copilot: model: copilot/opus runs on the newest live Opus. Exact ids are checked against AWF /reflect before Pi starts, and an unlisted id fails with model_unavailable , producing the same unavailable-model failure issue as Copilot.

When AWF’s model discovery is incomplete, exact ids pass through and aliases fail with catalog_unavailable ; sub-agents no longer fall back to Pi’s built-in model list. Session artifacts Section titled “Session artifacts” The agent artifact contains native pi-streaming.jsonl evidence and the normalized agent-session.jsonl . Conclusion publishes the essential event projection in usage/aw_session.jsonl . Pi’s observed message timestamps are retained on canonical messages, reasoning and tool calls when no source-event clock is present.

Collection also recognizes clocks stored only in data.messageMetadata.timestamp in older canonical artifacts. Collection promotes only finite, in-range milliseconds or calendar-valid timezone-qualified ISO strings from archival message metadata. Invalid archival clocks are not promoted; missing clocks are not filled with collection time. Unified tool lifecycle events retain supplied messageId and model alongside toolCallId , allowing a tool call to be correlated with its originating model response.

Full native message metadata, provider envelopes and signatures remain in the archival agent evidence rather than the unified projection. Child messages remain scoped to their invocation, and child usage is not added to parent session totals. Durable runs Section titled “Durable runs” Pi chains its native coding-agent sessions across workflow runs using the same GitHub Actions artifact restoration and publication as other engines: on: workflow_dispatch engine: pi: durable: retention-days: 7 durable: {} enables the default retention of seven days. retention-days accepts an integer from 1 to 90, subject to repository and organization artifact retention policy and gh-aw’s global artifact retention overrides.

Durable storage does not use or require tools.repo-memory or tools.cache-memory . The ordinary Pi CLI, SDK ( pi_agent_c

The rest of this page is on the live site.