pi-codex-tools

pi-codex-tools turns Codex CLI into bounded Pi tools for agentic engineering: deterministic web evidence first, optional Codex summarization second, and structured JSON results that another agent can inspect.

It is designed for practical AI tooling work where a coding agent needs current public evidence, a safe page fetch, patch validation, or a contained Codex subtask without turning model output into the source of truth.

The core idea is simple: search and fetch with deterministic code, pass only that evidence to Codex when a summary is useful, and keep coding delegation scoped with timeouts, sandboxes, and debug logs.

Why this matters

AI-assisted development is most useful when the agent workflow is inspectable. This package gives Pi sessions four explicit tools that separate evidence collection from model interpretation:

• deterministic search/fetch results are returned before any summary;
• Codex summaries are convenience output derived from returned evidence, not hidden sources;
• coding tasks are delegated through bounded subprocess calls with structured results;
• failures include enough debug information to inspect what happened.

That makes pi-codex-tools a small but concrete example of applied AI engineering: LLMs are used as tools inside an auditable workflow rather than as unbounded automation.

Architecture overview

Pi session
  -> pi-codex-tools extension
      -> deterministic web search/fetch helpers
      -> optional Codex CLI summarization over returned evidence
      -> bounded Codex CLI coding subprocesses
      -> structured JSON tool responses + temp debug logs

The extension is registered from extensions/codex-tools.ts. Package metadata in package.json exposes it to Pi through:

{
  "pi": {
    "extensions": ["./extensions/codex-tools.ts"],
    "skills": ["./skills"]
  }
}

Tools

Tool	Purpose	Evidence / output model	Default timeout
web_search_codex	Search the public web through Brave Search API when BRAVE_SEARCH_API_KEY is set, otherwise DuckDuckGo HTML search.	Returns provider results first; optional Codex summary is constrained to those titles, URLs, snippets, dates, and sources.	120 seconds
web_fetch_codex	Fetch an HTTP/HTTPS URL and extract text, markdown, and raw text.	Returns fetched response metadata and extracted content; optional Codex summary is constrained to the fetched evidence.	120 seconds
apply_patch_codex	Ask Codex to validate or apply an explicit patch in a repository.	Returns structured patch status, changed files, summary, diff/error details, and debug log path. Dry run uses a read-only sandbox.	180 seconds
codex_task	Delegate a bounded coding, debugging, review, migration, or test-fixing task to Codex.	Returns Codex's structured result with summary, files changed, tests run, diff/error details, and notes.	900 seconds

Safety and observability

• Evidence first: web tools collect deterministic search/fetch output before optional Codex summarization.
• Derived summaries: prompts instruct Codex to summarize only the provided evidence and to say when facts are missing.
• Structured JSON: tool responses are JSON-oriented so a parent agent can inspect ok, status, files changed, tests run, summaries, errors, and notes.
• Timeouts: each tool accepts timeout_seconds; values are clamped and fall back to safe defaults.
• Safe URL checks: web_fetch_codex accepts only http and https, blocks localhost/loopback/link-local metadata hosts, and rejects likely internal suffixes such as .local, .internal, and .localhost.
• Subprocess boundaries: Codex coding tools run through codex exec --json; codex_task defaults to workspace-write with approval policy never, while apply_patch_codex dry runs use read-only.
• Debug logs: Codex subprocess calls write JSON debug logs under the operating system temp directory in pi-codex-tools/, including prompt, CLI args, stdout, stderr, exit code, and timestamps.

Requirements

• Pi CLI/runtime with package extension support.
• Codex CLI available on PATH.
• Node.js and npm.
• Codex CLI already authenticated for the current user.
• Optional: BRAVE_SEARCH_API_KEY for Brave Search API results. Without it, web_search_codex falls back to DuckDuckGo HTML search.

Check local prerequisites:

which codex
codex --help
node --version
npm --version

Quickstart / install

From the package directory:

npm install

Enable globally for all Pi sessions:

pi install .

Enable only for the current project/repository:

pi install -l .

Confirm Pi can see the installed package:

pi list

If Pi is already running, reload extensions/resources with:

/reload

Or restart Pi.

For a one-off local test from this repository, run Pi with the extension file explicitly:

pi -e ./extensions/codex-tools.ts

Example prompts

Search with deterministic results and optional summary:

Use web_search_codex to search for "OpenAI Codex CLI app-server" and show the top 3 URLs.

Fetch a specific public page:

Use web_fetch_codex to fetch https://example.com and summarize it.

Validate or apply an explicit patch:

Use apply_patch_codex to dry-run this patch and report changed files and errors.

Delegate a bounded coding task:

Use codex_task to inspect this repository and tell me what package manager it uses. Do not modify files.

Verification commands

This package currently does not define npm scripts in package.json, so there is no documented npm test command to run. For safe local verification of the package metadata and README surface, use:

node -e "JSON.parse(require('fs').readFileSync('package.json','utf8')); JSON.parse(require('fs').readFileSync('package-lock.json','utf8')); console.log('package metadata JSON OK')"
npm run
git diff --check
git status --short --branch

Manual Pi smoke checks after installing:

pi -e ./extensions/codex-tools.ts

Then ask Pi to call each tool with a small, bounded prompt such as the examples above.

Expected result shapes

web_search_codex

{
  "ok": true,
  "provider": "brave or duckduckgo-html",
  "results": [
    {
      "title": "...",
      "url": "...",
      "snippet": "...",
      "source": "...",
      "date": "..."
    }
  ],
  "summary": "... or null"
}

web_fetch_codex

{
  "ok": true,
  "url": "https://example.com",
  "final_url": "https://example.com/",
  "status": 200,
  "content_type": "text/html",
  "title": "Example Domain",
  "text": "...",
  "markdown": "...",
  "raw_text": "...",
  "summary": "... or null",
  "error": null
}

apply_patch_codex

{
  "applied": true,
  "dry_run": false,
  "files_changed": ["hello.txt"],
  "summary": "...",
  "diff": "...",
  "error": null
}

codex_task

{
  "success": true,
  "summary": "...",
  "files_changed": [],
  "tests_run": [],
  "diff": null,
  "error": null,
  "notes": []
}

Notes and limitations

• web_search_codex uses Brave Search API when BRAVE_SEARCH_API_KEY is set; otherwise it falls back to DuckDuckGo HTML search.
• web_fetch_codex performs a plain HTTP fetch and uses Readability/Turndown extraction. If a site blocks HTTP clients, requires login, needs JavaScript rendering, or redirects indefinitely, the tool should report failure instead of inventing content.
• Codex summaries are derived output. For web tools, use returned raw results, text, markdown, and metadata as source evidence.
• apply_patch_codex is agentic patch application. For tiny deterministic edits, a native editor or patch tool is usually simpler.
• The current coding-agent backend starts short-lived codex exec --json subprocesses. A future version could replace this with a persistent Codex app-server client while keeping the same Pi-facing tool names.