st4ck

Let your coding agent verify a UI once. Replay the captured test without an LLM.

st4ck is the free, open-source command-line surface for agent-driven browser recording and deterministic local replay. It gives an agent a focused browser vocabulary, captures verified actions as Markdown in your repository, and replays that trace with Playwright.

npx st4ck@latest author https://app.example.com "Sign in as alice and verify the dashboard loads"
# The agent reads .st4ck/session.md, drives st4ck browse, proves the outcome, and closes the recording.
npx st4ck@latest run ./tests/sign-in-as-alice-and-verify-the-dashboard-loads.md

No st4ck account, API key, hosted service, or LLM call is required during replay.

The recording loop

st4ck author <url> "<instruction>"
        |
        v
writes .st4ck/session.md
        |
        v
agent launches st4ck browse --record
        |
        v
observe -> one primitive -> verify -> next primitive
        |
        v
st4ck browse close
        |
        v
tests/<flow>.md
        |
        v
st4ck run tests/<flow>.md   (deterministic, no LLM)

The generated session skill teaches the public st4ck browse CLI. Agents do not need to manage the runner process, FIFOs, or raw JSON IPC. Use npx st4ck@latest browse <op> --help as the operation-level source of truth.

What ships

• Accessible locators with collision-aware interactables and locate discovery.
• Focused reads and assertions with get-text and assert-contains.
• Recording actions including navigation, click, fill, select, check-box, hover, upload, waits, scroll, and multi-session driving.
• Explicit reactive-control escalation: click, then click_native, then a pointer sequence only when required.
• Bubble-specific diagnostics and guarded composite operations.
• Deterministic Markdown replay through st4ck-runner.
• A supported installer for the free native st4ck-lite plugin in Claude Code and Codex.

The current authoring flow records one flat primitive trace. Basic reusable local components are intended to remain open source, but a stable local component registry and authoring format do not ship in this alpha. The CLI and generated skill must not invent one.

Local vs full st4ck

| Capability | Local st4ck / st4ck-lite | Full st4ck + workspace | |---|:---:|:---:| | Agent-driven browser exploration | Yes | Yes | | Local Markdown recording and deterministic replay | Yes | Yes | | Focused Browse discovery and assertions | Yes | Yes | | Basic local reusable components | Intended OSS; registry not shipped yet | Shared registry-backed reuse | | Database-backed test/component catalog | No | Yes | | MCP authoring and execution | No | Yes | | PRD/spec/dev-task/test lifecycle links | Local documents only | Workspace-backed | | Team policy, review state, and shared history | No | Yes |

The paid boundary is managed, shared lifecycle infrastructure and outcomes—not access to basic test or component authoring. See st4ck.io for the full product.

Commands

st4ck author <url> "<instruction>" [options]

Writes .st4ck/session.md with the requested behavior and current Browse procedure.

| Flag | Default | Description | |---|---|---| | --out <path.md> | tests/<slug>.md | Recording destination taught to the agent | | --name <slug> | derived from instruction | Session/test slug override |

The agent then follows the generated file: launch with --record, inspect live results, perform one verified Browse operation at a time, and finish with browse close.

st4ck browse <subcommand> [args]

Drives a persistent named browser session. Start with:

npx st4ck@latest browse --help
npx st4ck@latest browse interactables --help
npx st4ck@latest browse launch https://app.example.com -s flow --record --out tests/flow.md

Each call emits a result envelope. Read it before choosing the next operation. Prefer focused discovery and deterministic assertions over repeated page dumps or custom JavaScript.

For authorized authenticated driving, use a mode-0600 temporary Playwright storage-state file and pass only its path with --storage-state. Never put tokens, passwords, authorization headers, or credential-bearing JSON in CLI arguments; values supplied through --local-storage, --http-credentials, and inline --context-options are visible to other local processes.

st4ck run <file.md> [--headless]

Replays a recorded Markdown file through st4ck-runner and mirrors the runner's exit code.

• 0 — replay passed.
• 1 — a block failed or input was invalid.

st4ck install [--target claude|codex|all] [--update | --force] [--repo <source>]

Registers the st4ck-lite marketplace and installs st4ck-lite@st4ck-lite-marketplace through the selected host's native plugin CLI. The default remains claude, preserving the existing Claude Code behavior. Choose codex to hydrate the packaged st4ck-browse skill in Codex, or all to configure both hosts independently.

| Flag | Behavior | |---|---| | --target claude\|codex\|all | Host to configure; defaults to claude | | --update | Refresh the selected marketplace and plugin; first-installs when absent | | --force | Refresh and reinstall/re-add without intentionally deleting plugin data | | --repo <source> | Marketplace GitHub shorthand, Git/SSH URL, or local path used for registration and source-identity checks |

--update and --force are mutually exclusive. Claude Code continues to use claude plugin marketplace ... at user scope, including its existing --keep-data force flow. Codex CLI 0.139.0 or newer is required for the JSON plugin contract used here. Codex uses codex plugin marketplace ... --json and idempotently runs codex plugin add ... --json on every install so a missing cache payload is repaired even when plugin list still says installed and enabled. It validates the returned exact plugin ID and installedPath, then verifies that path contains the packaged skills/st4ck-browse/SKILL.md before retiring any standalone copy. Git marketplaces are upgraded before a missing, disabled, updated, or forced plugin is re-added. Local Codex marketplaces skip the unsupported marketplace-upgrade command and safely re-add the plugin from the registered directory. Every Codex install reasserts the requested marketplace source, so a same-name marketplace registered from another source fails instead of being trusted silently.

With --target all, both hosts are attempted even if one host CLI is missing or fails, and the command returns nonzero if either target fails. Host installs cannot be transactional, so a successful target is kept.

The installer never deletes Claude plugin data or a legacy direct checkout. If ~/.claude/plugins/st4ck-lite exists, it warns and leaves cleanup to the user after the marketplace install is verified. When CLAUDE_CONFIG_DIR is set, the warning follows that config root.

After Codex confirms the native plugin is installed and enabled, the installer can retire one known broad standalone copy that caused every st4ck-related request to invoke Browse. It moves ${CODEX_HOME:-~/.codex}/skills/st4ck-browse to ${CODEX_HOME:-~/.codex}/legacy-skills/st4ck-browse-standalone only when it is a real directory containing exactly the unchanged official SKILL.md. The move is recoverable and outside skill discovery. A symlink, modified layout/content, existing destination, or any verification error is left untouched with a warning. The shared ~/.agents/skills/st4ck-browse location is warning-only and is never moved automatically.

Do not embed a username, password, token, or query string in an HTTP(S) source URL. HTTP userinfo, query strings, credential-shaped fragments, and sources beginning with - are rejected before either host CLI is spawned. A plain Git URL #branch-or-ref remains supported: Claude receives the existing source form, while Codex receives the URL plus its documented --ref option. Use a username-only SSH URL or a Git credential helper instead.

If Codex cannot inspect, add, or verify the plugin, check codex --version, upgrade to Codex CLI 0.139.0 or newer, and rerun the install. A failed Codex mutation includes the first safe line of captured CLI diagnostics; credential-shaped values are redacted.

After a Claude install or update, run /reload-plugins inside Claude Code or start a new session. After a Codex install or update, start a fresh Codex task, then invoke $st4ck-browse explicitly when you want that workflow. The packaged skill does not implicitly activate for ordinary st4ck requests.

st4ck link <st4ck_link_...>

Connects the current local project to the exact Existing project selected in Add Project. Copy the short-lived command from the Add Project page. Run it in the existing project folder. If the selected repository is not downloaded yet, run it in the parent folder and st4ck will download it. If no repository exists yet, create an empty project folder and run it there. Compare the six-character matching code printed by the command with the browser, then approve the connection.

The command:

• when run by Codex or Claude Code, configures that active development agent; when run in a normal Terminal, configures every supported development agent installed on the computer;
• when both agents are selected from Terminal and one fails later setup, completes with the healthy agent and reports the one that was skipped; an active agent remains fail-closed;
• for Claude Code, installs, updates, and enables the full st4ck@st4ck-marketplace plugin at user scope without changing or removing st4ck-lite@st4ck-lite-marketplace;
• reuses a Git worktree only when its canonical origin matches the selected GitHub repository;
• otherwise downloads the exact selected repository into one predictable child folder, then opens its files with Git settings that prevent repository hooks and external file filters from running; it does not run package managers, builds, tests, or repository scripts;
• configures the four st4ck roles without placing the project credential in a repository, config file, URL, command argument, or terminal output; Claude Code uses st4ck-pm, st4ck-dev, st4ck-qa, and st4ck-ops, while Codex uses collision-proof st4ck-bridge-* config names;
• calls the real get_project_briefing tool and confirms the exact project before it reports success; and
• prints the exact project folder. Start a new development-agent session in that folder, or restart the current one, so the newly configured tools are loaded.

Long-lived credentials and unfinished recovery state live in a private compatibility area ($CLAUDE_CONFIG_DIR/st4ck/agent-links, or ~/.claude/st4ck/agent-links). Directories are mode 0700; credential and journal files are mode 0600. Claude Code receives only a private headersHelper path. Codex receives only a private local bridge path and one namespaced bridge name per st4ck role; the bridge selects the nearest linked project when the new session starts. Relinking removes the older collision-prone global Codex names, leaves valid project-local URL entries untouched, and verifies that Codex can load the real project configuration. A rerun with the same command repairs an interrupted setup with the same private candidate.

When Add Project has no repository yet, link truthfully configures the current directory as a project-only connection and does not create a fake repository.

File layout

your-repo/
├── .st4ck/
│   └── session.md      # generated agent procedure and requested behavior
└── tests/
    └── <slug>.md       # created by st4ck browse close

The test artifact is human-readable, diffable Markdown containing the captured primitive sequence.

Requirements

• Node.js 18 or newer.
• An agent or human that can run shell commands.
• Playwright's Chromium binary, downloaded on first use if needed.
• The native CLI for each selected st4ck install target: claude, Codex CLI 0.139.0 or newer, or both. Authoring and replay require neither.
• Codex or Claude Code, plus Git, for every st4ck link run, including a project-only connection with no repository. If Git is missing, the command explains that it was not found and asks you to install it. Claude Code must be 2.1.152 or newer when selected.

Status

0.2.0-alpha.63. Public alpha. Browser operation names and skill guidance can still evolve; query per-operation help for the installed runtime contract.

License: Apache-2.0.