Introduction
docsxai walks a running web application, follows written flows, and emits
screenshot-rich user documentation. You describe a user task once as a
flow-file; the docsxai CLI replays it through
headless Chromium, captures clean screenshots, places halos and callouts from
the flow's annotations, and renders a publishable doc pack. When the UI
changes, you re-run. The docs are a build artifact: the flow is the source
and a re-run is the refresh.
The two-mode bet
Section titled “The two-mode bet”docsxai runs in two modes:
- Calibration is AI-assisted and rare. A host agent - Claude Code, Codex, anything that speaks MCP - explores the live app, picks canonical locators, and authors the flow-file. This happens once per flow, and again only when the app drifts out from under it.
- Execution is deterministic and continuous.
docsxai runreplays the flow with zero agent involvement and zero LLM calls. Same flow-file, same target state, byte-identical screenshots - enforced by a keystone test against real Chromium.
The engine never calls a model API. Per-commit LLM runs would be untenable and per-commit Playwright runs are standard CI practice, so you pay for inference once, at authoring time. Every refresh then costs about as much as a test run. Architecture covers how the pieces enforce this.
Naming
Section titled “Naming”One name everywhere:
| Name | What it names |
|---|---|
docsxai | The product, the GitHub repo kalebteccom/docsxai, this site, the CLI binary, and the bare npm meta-package (pnpm add -g docsxai@next). |
DOCSX_* | The env-var prefix; the workspace config is .docsxai.json, schema ids are docsxai/*@N. |
@docsxai/* | The npm scope: @docsxai/engine, @docsxai/viewer, @docsxai/plugin, @docsxai/backend and @docsxai/skill are published, and @docsxai/plugin-sharepoint is published too, experimental since 0.3.0-rc.3. @docsxai/mcp and the other @docsxai/plugin-* packages are repo-only for now. |
When you type a command, it is docsxai. When you install the CLI, it is the
bare docsxai package (which wraps @docsxai/engine and ships
@docsxai/viewer); when you depend on the library, it is @docsxai/engine.
All of it names the same engine.
When to use it (and when not to)
Section titled “When to use it (and when not to)”A screen recorder or a record-and-replay generator captures what you did once; the recording rots silently when the UI moves, and refreshing means re-recording by hand. docsxai is the better tool when the documentation has to stay current without a human in the loop:
- The flow-file is a reviewable text file.
- The replay is deterministic enough to gate CI on pixel-level drift
(
docsxai diff --fail-on warn). - A halted step names exactly which locator or assertion broke instead of handing you a stale video.
- The same calibration loop works from any MCP-speaking agent, so authoring is cheap too.
If all you need is a one-off capture of a UI that will never change, a recorder is less setup. If you need living docs for an app that ships weekly, write the flow once and let CI do the rest.
Where to go next
Section titled “Where to go next”- Installation - get
docsxaionto your PATH. - Quickstart - init a workspace, write a first flow, run and render it.
- The doc pack - what a run actually produces on disk.