create-healix

Scaffold a Healix test-automation project in one command — a ready-to-run WebdriverIO setup wired for AI-assisted authoring and self-healing, standalone test suites.

npx create-healix my-app
cd my-app

What you get

• WebdriverIO + Healix service preconfigured (wdio.web.conf.ts).
• .mcp.json registering the healix-mcp server, so an AI agent (Claude Code, Cursor, Windsurf, …) can drive the live browser, observe the real DOM, and author specs/page objects for you.
• Two-file page-object model + an example spec/POM to copy.
• Allure reporting and a reports/screenshots/ directory wired out of the box.
• CLAUDE.md + a SessionStart hook so the agent always loads the framework guide.

Options

| Flag | Effect | |------|--------| | --yes, -y | Accept all defaults | | --platforms=web,android,ios | Target platforms (default web) | | --app-url=<url> | Default app URL for the example spec | | --mcp=cursor\|claude\|windsurf | Which MCP client to configure | | --skip-install | Don't run npm install |

Run it

npm run session:web   # opens a live browser + the Healix API for the agent to drive
npm test              # runs the suite standalone — no AI, no MCP

The deliverable is a normal WDIO suite: it runs in CI with npx wdio run and no AI in the loop.

See wdio-healix-service (the framework) and healix-mcp (the agent server).

Codex host

--host codex scaffolds .codex/config.toml, .codex/hooks.json, AGENTS.md, .agents/skills/ and .codex/agents/test-builder.toml. Each behaviour below was checked against a real Codex CLI (0.155.0); npm test repeats the checks (the ones that need the CLI run only when codex is installed). It is not a guarantee across every Codex version.

One-time steps in Codex (the scaffold prints them):

1. Trust the project. An untrusted project skips the whole .codex/ layer — config, MCP, hooks.
2. Review and trust the hooks (/hooks). Codex trusts each hook by the hash of its exact definition and skips new or changed hooks until reviewed — so re-review after any re-scaffold or upgrade that changes hooks.json.

What the scaffold does about Codex's behaviour

• AGENTS.md size. Codex loads at most project_doc_max_bytes (default 32 KiB) and silently drops the tail. The Healix guide alone is ~31 KiB, so .codex/config.toml sets project_doc_max_bytes = 65536 (honoured for a trusted project) and the knowledge-file instructions are placed near the top of the file. The scaffold warns if the generated file ever exceeds the cap; npm test fails.
• Hook paths. Hook commands run in the session cwd, and a relative node .codex/x.mjs silently does not run when Codex is started below the project root. When the project is its own git root (a new scaffold runs git init for you if it is not inside a repository), commands are written node "$(git rev-parse --show-toplevel)/.codex/x.mjs". Inside a larger repository, or without git, they stay relative and the scaffold tells you to start Codex from the project root.
• MCP launch. A stdio MCP server starts in the session cwd, and healix-mcp treats its cwd as the project root. The [mcp_servers.healix] table therefore uses a tiny launcher that finds the nearest node_modules/healix-mcp above the cwd, chdirs there and imports it in-process — no absolute path is committed, and it works from any subdirectory.
• MCP environment. Codex does not give MCP servers your environment — only a small default set plus env_vars. healix-mcp spawns WDIO with its own environment, so the table lists env_vars for the app selector (appEnvVar from healix.agent.json, e.g. APP_URL/APP_ID), proxy and CA settings (HTTPS_PROXY, NODE_EXTRA_CA_CERTS, …), JAVA_HOME/ANDROID_HOME, BrowserStack credentials and the Healix switches. Only variables that are set are forwarded. Add your own names to env_vars.
• Hook matchers. Codex matches a matcher against the whole tool name, and MCP tools arrive namespaced as mcp__healix__healix_*. A bare Spryv-style scaffold_page never fires (verified live), so the scaffold writes the full names (mcp__healix__healix_scaffold_page, …) and apply_patch|Edit|Write|MultiEdit for file edits; npm test checks every matcher against the real tool names.
• Knowledge gate. A scaffold/locator/spec write is denied once per session with the required knowledge file injected inline, then the retry proceeds. This does not depend on Codex's transcript_path (which Codex documents as an unstable interface): the delivery is recorded per session id under the OS temp dir. The gate resolves the doc from the project root, so it works from a subdirectory too.

Limits

• Hooks are guardrails, not a security boundary (Codex says the same): shell edits can bypass them. Acceptance is a fresh standalone WDIO run, not just a green interactive session.
• Codex asks for approval on MCP tool calls unless you set default_tools_approval_mode (per server or tool).
• --add-host codex merges into an existing config.toml: it adds only what is missing and never rewrites your own keys or an existing [mcp_servers.healix] table, even with --force. A table written by an older scaffold has no env_vars (the scaffold warns) — delete it and re-run to regenerate.
• Custom-agent frontmatter with no supported Codex translation is omitted; see the generated TOML comments.

Official references: hooks, MCP, skills, custom agents.