@false00/pi-steel

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.

Resource	Link
npm	@false00/pi-steel
GitHub	github.com/false00/pi-steel
License	MIT
Changelog	CHANGELOG.md
Security policy	SECURITY.md
Compatibility notes	docs/COMPATIBILITY.md
Examples	docs/EXAMPLES.md
Troubleshooting	docs/TROUBLESHOOTING.md
Contributing guide	CONTRIBUTING.md

Why this package

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

Changes from upstream

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

Tool coverage

Area	Tool count
Navigation	4
Content extraction	4
Interaction	7
Session management	2
Total	17

Navigation

Tool	Description
steel_navigate	Open a URL with normalization and retry logic
steel_go_back	Navigate back in browser history
steel_get_url	Read the current page URL
steel_get_title	Read the current page title

Content extraction

Tool	Description
steel_scrape	Extract page content as text, markdown, or html
steel_screenshot	Capture a screenshot artifact
steel_pdf	Generate a PDF artifact
steel_extract	Extract structured data using a JSON schema

Interaction

Tool	Description
steel_click	Click an element with captcha recovery
steel_type	Type text into a field
steel_fill_form	Fill multiple fields in one call
steel_scroll	Scroll the page or a nested container
steel_find_elements	Discover likely interactive elements
steel_wait	Wait for an element state
steel_computer	Low-level computer actions via Steel's cloud endpoint

Session management

Tool	Description
steel_pin_session	Keep the browser session alive across prompts
steel_release_session	Close the browser and restore the default session mode

Install

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.

Quick start

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

1. Configure Steel

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

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

Alternatively, run:

steel login

2. Start Pi

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.

3. Ask Pi to browse

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

Fresh-install behavior

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.

Configuration

Requirements

• 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

Configuration priority

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

Environment variables

Connection

Variable	Purpose
STEEL_API_KEY	Steel API key
STEEL_BASE_URL	Steel API base URL
STEEL_BROWSER_API_URL	Browser API endpoint
STEEL_LOCAL_API_URL	Local Steel instance URL
STEEL_API_URL	Alternative API URL
STEEL_CONFIG_DIR	Custom Steel config directory

Session

Variable	Purpose
STEEL_SESSION_MODE	Lifecycle mode: agent, session, or turn
STEEL_SESSION_TIMEOUT_MS	Session timeout
STEEL_SESSION_HEADLESS	Run browser headless
STEEL_SESSION_REGION	Browser region
STEEL_SESSION_PROFILE_ID	Persistent browser profile
STEEL_SESSION_PERSIST_PROFILE	Save profile changes
STEEL_SESSION_CREDENTIALS	Session credentials
STEEL_SESSION_NAMESPACE	Session namespace

Proxy

Variable	Purpose
STEEL_USE_PROXY	Enable proxy
STEEL_PROXY_URL	Proxy URL

Captcha

Variable	Purpose
STEEL_SOLVE_CAPTCHA	Enable captcha solving
STEEL_CAPTCHA_MAX_RETRIES	Max captcha retry attempts
STEEL_CAPTCHA_WAIT_MS	Captcha solve wait time
STEEL_CAPTCHA_POLL_INTERVAL_MS	Captcha poll interval

Tools

Variable	Purpose
STEEL_TOOL_TIMEOUT_MS	Default tool timeout
STEEL_NAVIGATE_RETRY_COUNT	Navigation retry attempts

Session modes

Mode	Behavior
session (default)	Session stays alive until Pi switches or shuts down
agent	One session per Pi prompt, closed after agent_end
turn	Session closes after each Pi turn

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.

Runtime behavior

Output model

• 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

Error model

• 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

Operational docs

For setup help and examples, see:

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

Repository layout

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

Development

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

Build note

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

Publishing

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

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

Support and feedback

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

License

MIT — see LICENSE.