pi-gpt

A native Pi extension that drives a ChatGPT / Codex account as Pi tools. Inspect the account, list models, start or continue chats (normal, agent, deep research, deep-research heavy), pick an intelligence level, and read back conversation history — all scoped to the current project. No API key needed: it reuses codex login (~/.codex/auth.json).

Native Pi package — no separate process, no MCP stdio. Loaded directly into Pi as a TypeScript extension. Talk to chatgpt.com with plain fetch (no TLS impersonation, no native deps).

Install

pi install /path/to/pi-gpt      # local
# or, once published:
pi install npm:pi-gpt

Then in Pi, the tools gpt_account_status, gpt_list_models, gpt_chat, gpt_list_chats, gpt_get_conversation, gpt_get_message are available, plus the /skill:chatgpt skill.

Requires a ChatGPT login:

codex login   # writes ~/.codex/auth.json, shared with pi-gpt

Multiple accounts

Codex stores credentials and state under CODEX_HOME. Give each login its own directory, then launch Pi with the account you want:

CODEX_HOME="$HOME/.codex-pro" codex login
CODEX_HOME="$HOME/.codex-work" codex login

CODEX_HOME="$HOME/.codex-pro" pi
# Exit Pi before switching:
CODEX_HOME="$HOME/.codex-work" pi

For two workspaces under one ChatGPT login, optionally pin each login in that home's config.toml:

forced_chatgpt_workspace_id = "<workspace-uuid>"

codex --profile changes configuration but does not isolate authentication. pi-gpt never switches accounts automatically; call gpt_account_status to see the auth-selected account and available workspaces.

Tools

Tool	Purpose
gpt_account_status	Auth profile, selected account, available workspaces, plan, expiry, features, and raw Deep Research quota.
gpt_list_models	Available models with slug + thinking-effort options.
gpt_chat	Start/continue a chat: normal | agent | deep_research | deep_research_heavy. Accepts prompt_file and files for local context.
gpt_list_chats	Chats started from the current project path.
gpt_get_conversation	Message history of a conversation.
gpt_get_message	A single message by id.

Intelligence levels (gpt_chat)

instant → medium → high → extra_high → pro. Each maps to a model and a thinking effort; pro uses gpt-5-5-pro. For normal chats, pass an explicit model slug plus thinking_effort (min | standard | extended | max) to pin both values; use an effort listed by gpt_list_models for that model. Deep-research chat types use their own models and ignore these settings. high/extra_high (extended/max thinking) are returned asynchronously — the tool auto-polls the conversation so you still get the answer.

File inputs (gpt_chat)

• prompt_file — one UTF-8 text file containing a prepared prompt packet. Its contents are appended to prompt; either prompt or prompt_file is required.
• files — local files to provide as context. UTF-8 text, source, and Markdown are embedded verbatim with path-labeled boundaries for every chat type. PNG, JPEG, GIF, BMP, WebP, and PDF use native uploads for normal/agent. Both Deep Research modes reject images/PDFs before starting; unsupported or unrecognized formats fail explicitly and are never silently skipped.

All files are read and validated before any upload or ChatGPT request. Results report prompt-file bytes plus inlined/uploaded file counts so missing context is visible. Native uploads use a 3-step Azure-blob flow (POST /files → PUT blob → confirm), with no native dependencies.

Long-running research

deep_research_heavy defaults to a two-hour wait (max_wait_minutes: 120). Increase max_wait_minutes when the research scope warrants more time; there is no configured maximum. A heartbeat keeps the run visibly alive, Esc aborts, and on timeout it returns the partial result plus the conversation_id so you can retrieve the completed report later via gpt_get_conversation. ChatGPT App v2 plan preparation is treated as progress; terminal statuses such as rate_limited are returned immediately instead of waiting for the wall-clock deadline. details.deep_research_rate_limit provides reset_after, retry_after_seconds, and the backend's raw_remaining; agents should not retry before the reported reset.

Project-scoped chats

Every chat gpt_chat creates is indexed by the working directory it ran in. gpt_list_chats returns only the chats for the current project, so you can keep per-repo threads separate. The index lives at ~/.pi-gpt/registry.json.

Observer — struggle detection (experimental, off by default)

A silent supervisor that reads the agent's visible messages with a model, detects sustained struggle, and nudges it to ask for help — ask you, consult gpt_chat, or run Deep Research. Think of it as pushing an introvert model to socialize. It is not a keyword matcher: a model judges each turn, and healthy exploration / confident bug diagnoses never count as struggle (validated: 0 false positives on real session messages).

• Off by default. Enable with /gpt-observer. A status-bar line shows 👁 observer: off / on · <mode> · <model> (set on session start, refreshed from the menu).
• Passive first: the default delivery mode is notify (surfaces to you); flip to steer to push the agent, or nextTurn to queue a nudge.
• The detector picks who to ask (user / gpt_chat / Deep Research) from the kind of struggle; the delivery mode picks how.
• Smart, not a counter: acts only on sustained struggle (minStreak, default
  2. with a cooldown (default 6 turns), skips turns where the agent already sought help, and never crashes the agent (fail-silent).
• State/config at ~/.pi-gpt/observer/ (config.json, state.json, log.jsonl).

/gpt-observer            # interactive menu: enable, delivery mode, detector
                         # model, sensitivity, streak, window, cooldown, status

How it works

• Auth: reads the access token from ~/.codex/auth.json (honors CODEX_HOME for multi-account) and re-reads it on mtime change so codex's background refresh can't 401 mid-request.
• Sentinel gate: solves the chatgpt.com proof-of-work (SHA3-512) and turnstile challenge, ported to node:crypto.
• Streaming: SSE parsed over fetch web streams for chat, agent, and both deep-research paths (including the delta-patch v1 encoding and widget-state report recovery for heavy DR).
• File upload: 3-step Azure-blob upload with a no-dep image-dimension reader (PNG/JPEG/GIF/BMP/WebP) for image attachments.
• Redaction: tool output masks emails, phone numbers, and secrets (JWT, bearer tokens, API keys, GitHub tokens).

Status & limits

Native port of the conversation engine, proven live: account, models, normal / thinking chat (incl. extended & max), multi-turn + cross-type continuation (including normal follow-ups and sequential Heavy Research turns in one thread), light & heavy deep research (heavy completed in ~11 min end-to-end), file inputs, and the project-scoped registry. Deep Research usage varies by account; ChatGPT is the source of truth for enforcement, while gpt_account_status reports the raw quota/reset values it exposes. Tool output is PII-redacted.

License

MIT.