Production-focused Steel browser automation for the Pi coding agent.

Fork of @steel-experiments/pi-steel. Original credit belongs to nibzard and the Steel Experiments team.

@false00/pi-steel exposes 17 Pi tools for browser navigation, screenshots, scraping, structured extraction, form interaction, low-level computer actions, and browser-session lifecycle control.

This fork is aimed at people who want Pi browsing to feel stable, readable, and operationally friendly instead of feeling like a thin demo wrapper.

What it emphasizes:

• Pi-friendly output — screenshot, scrape, PDF, and computer tools return artifact paths in plain tool output so agents can actually read them
• Safer fresh installs — missing Steel credentials no longer break extension loading; the package creates a template ~/.config/steel/.env and tells the user what to update
• Cleaner local state — artifacts live under ~/.cache/.steel-browser/ instead of cluttering project directories
• Session lifecycle control — session-persistent browsing by default plus explicit pin/release tools and opt-in stricter cleanup modes
• Publishable package hygiene — CI, dependency review, vulnerability scanning, changelog, security policy, contributing guide, docs, and package tests

This fork currently adds or changes the following behavior:

• .env file support — ~/.config/steel/.env is read as the highest-priority config source for api_key and base_url
• Fresh-install template creation — if the file is missing, pi-steel creates a template and tells the user to update it
• Lazy Steel initialization — the extension loads even when credentials are missing; the failure is deferred until the first Steel tool call
• Clearer error guidance — configuration failures tell the user to update ~/.config/steel/.env or run steel login
• Session persistence by default — when STEEL_SESSION_MODE is unset, Pi keeps the same Steel browser alive for the active Pi session
• Fail-fast blank-page interaction errors — selector-based tools report session continuity problems immediately instead of spending a full selector timeout on about:blank
• Read-tool-friendly artifact paths — screenshot, scrape, PDF, and computer outputs include explicit file paths in visible tool output
• Full scrape persistence — steel_scrape writes the complete content to disk before truncating inline output
• Artifact directory relocation — screenshots, scrapes, and PDFs are stored under ~/.cache/.steel-browser/
• /clear_webcache command — deletes cached Steel artifacts from the local cache directory
• Security workflows — GitHub Actions now run production dependency audit, dependency review on pull requests, and CodeQL analysis

Install into Pi as a package:

pi install npm:@false00/pi-steel

Use it for a single run:

pi -e npm:@false00/pi-steel

For local development from this repository:

pi --no-extensions -e .

If you already have @false00/pi-steel installed in Pi, --no-extensions prevents tool-name conflicts between the installed package and the repo-local copy.

After installing, configure Steel once and then ask Pi to browse in plain English.

Create or update ~/.config/steel/.env:

api_key=your-steel-api-key
# base_url=https://your-selfhosted-steel-instance.example

Alternatively, run:

steel login

pi -e npm:@false00/pi-steel

By default, pi-steel keeps the same Steel browser session alive for the active Pi session, so cross-prompt browsing behaves more like a normal web browser.

Go to hacker news and tell me the top story
Open the docs page and scrape it as markdown
Take a screenshot of the pricing page
Find the login button on the current page

If you use pi.dev with a global AGENTS.md or similar user-level instructions, add a short browser-automation section there. This does not install the extension by itself; users still need pi install npm:@false00/pi-steel or pi -e npm:@false00/pi-steel.

Suggested AGENTS.md snippet:

## Browser automation with @false00/pi-steel

When browser automation is needed, prefer the `steel_*` tools from `@false00/pi-steel`.

- Use `steel_*` tools before Playwright, Puppeteer, Selenium, or ad-hoc browser setup.
- If the `steel_*` tools are unavailable in the current Pi session, say so plainly and ask to restart Pi with `pi -e npm:@false00/pi-steel` or install the package with `pi install npm:@false00/pi-steel`. Do not spend turns building a fallback browser stack unless explicitly asked.
- Keep the same Steel browser session across prompts when tasks span multiple prompts.
- If a selector-based tool fails because the current page is `about:blank`, do not retry the selector blindly. Navigate again in the same prompt or run `steel_pin_session`.
- Always set an explicit `steel_scrape` format: `text` for concise answers, `markdown` when headings, links, or lists matter, `html` only for raw DOM debugging.
- If `steel_scrape` output is truncated, read the saved artifact path instead of re-running the scrape.
- Treat `steel_find_elements` results as candidate selectors, not guaranteed unique selectors. Prefer stable selectors like `#id`, `[name]`, `[aria-label]`, `[data-testid]`, or specific `href` values.
- Prefer DOM-level tools such as `steel_click`, `steel_type`, `steel_fill_form`, `steel_wait`, `steel_scroll`, `steel_scrape`, and `steel_screenshot` before using `steel_computer`.
- Do not assume `steel_computer` works on self-hosted Steel. Fall back to DOM-level tools when computer actions are unavailable.
- When screenshot, scrape, PDF, or computer tools return an artifact path, read that artifact instead of repeating the same tool call.
- If a Steel tool reports missing configuration, stop retrying and tell the user to update `~/.config/steel/.env` or run `steel login`.
- Use `steel_release_session` only when the browsing task is complete.

If Steel is not configured yet:

• the extension should still load
• ~/.config/steel/.env is created automatically when missing
• the first Steel tool call returns an actionable configuration error instead of breaking the entire extension load

That means users should no longer hit this old startup failure mode on fresh installs:

Failed to load extension ... STEEL_API_KEY is required ...

Instead, they should be told to update ~/.config/steel/.env or run steel login.

• Node.js 20+
• A Pi runtime with extension support
• Steel authentication via one of:
  • ~/.config/steel/.env
  • STEEL_API_KEY
  • steel login config in ~/.config/steel/config.json
  • a self-hosted Steel base_url

1. ~/.config/steel/.env
2. Constructor options when embedding the client directly
3. Environment variables
4. Steel CLI config

Connection

Session

Proxy

Captcha

Tools

Selector-based interaction tools operate on the current browser page only. With the default session mode, Pi should usually keep the same browser alive across prompts. If you explicitly switch to agent or turn and the current URL becomes about:blank, tools such as steel_click should tell you to navigate first or re-enable persistence.

Set the mode with an environment variable only when you want stricter cleanup semantics than the default:

STEEL_SESSION_MODE=agent pi -e npm:@false00/pi-steel

You can also switch persistence at runtime with steel_pin_session and steel_release_session. steel_pin_session is mainly useful when you started Pi in agent or turn mode and want to promote the active browser to session persistence without restarting.

• steel_scrape defaults to text
• ask for markdown when headings, lists, or links matter
• ask for html only when raw DOM markup is actually needed
• full scrape output is always written to disk before inline truncation
• screenshot, scrape, PDF, and computer outputs include artifact paths in visible tool output

• tool failures are thrown back to Pi as real tool errors
• configuration errors are classified separately and include .env / steel login guidance
• already-classified errors are preserved instead of being wrapped repeatedly

For setup help and examples, see:

• docs/COMPATIBILITY.md
• docs/EXAMPLES.md
• docs/TROUBLESHOOTING.md

dist/                     Runtime extension code committed directly to the repo
  index.js                Pi extension entrypoint
  steel-client.js         Steel client and session lifecycle logic
  tools/                  Individual tool definitions

docs/                     Compatibility notes, examples, troubleshooting
.github/                  GitHub workflow directory
.github/workflows/        CI, dependency review, and CodeQL security workflows

tests/                    Smoke, runtime, and package-structure tests

README.md                 User-facing package documentation
AGENTS.md                 Maintainer and agent instructions
CONTRIBUTING.md           Contributor workflow
SECURITY.md               Security and disclosure policy
CHANGELOG.md              Release history

npm install
npm test
npm run test:smoke
npm run test:runtime
npm run test:package
npm pack --dry-run

This fork treats dist/ as the source of truth. There is no separate TypeScript build step required for normal development or publishing.

npm test
npm pack --dry-run
npm publish --ignore-scripts

Versioning and release-discipline notes live in AGENTS.md.

When reporting problems, include:

• package version
• Pi version
• Node.js version
• tool name
• whether you are using Steel cloud or a self-hosted base URL
• the relevant error message

MIT — see LICENSE.