mirage: Instructions file for Claude Code

CLAUDE.md

MIRAGE is a package that allows you to mount anything as a filesystem and make it usable by AI Agents.

Repo Layout

This monorepo hosts two sibling implementations:

• python/ — the Python package (mirage/, tests/, pyproject.toml, uv.lock).
• typescript/ — the TypeScript monorepo (packages/core, packages/browser, packages/node, etc.).
• docs/, examples/, .github/ — shared across both.

Run Python commands from python/, TypeScript commands from typescript/.

Create all Git worktrees under the repository-local .worktrees/ directory.

TypeScript packages

• typescript/packages/core contains runtime-agnostic primitives and shared logic. Code in core must work in both browser and Node.js runtimes; do not put browser-only or Node-only APIs there.
• typescript/packages/browser contains browser-only resources, commands, and workspace wiring. It depends on @struktoai/mirage-core.
• typescript/packages/node contains Node.js-only resources, commands, and workspace wiring. It depends on @struktoai/mirage-core.
• Put shared TypeScript behavior in core only when it works in both runtime packages. Put runtime-specific behavior in browser or node.

Python/TypeScript Parity

• Keep Python and TypeScript layout, architecture, and semantics mirrored as much as practical.
• When changing one implementation, check the other for the matching pattern or feature. If one side is more correct, use it to improve the weaker side instead of copying a bad design.
• For major Python or TypeScript changes, consider adding or updating integration coverage under integ/.
• The layout half of that rule is gated. scripts/check_layout_parity.py diffs the module-name sets of every mirage/<pkg>/ against its TypeScript counterpart (core/node/browser unioned onto one namespace, plus cli/server/agents by prefix), folding camelCase, hyphens and a leading underscore so a rename reads as a rename rather than a missing module; __init__.py and index.ts are skipped because only Python needs one per directory. Intentional differences live in spec/layout_exceptions.json with a reason, and a stale entry fails as loudly as a new gap. --strict (what CI runs) does not demand zero: it fails when the count moves off the committed baseline in either direction, so new drift is blocked and closing a divergence has to be locked in by lowering the number. Run it without --strict for the full advisory report; that report is how layout work gets scoped.
• mirage ships no filetype renderers, and no factory for them. Parquet, ORC, feather/arrow/ipc and hdf5/h5 rendering are gone, along with the parquet/hdf5/pdf extras, the hyparquet/apache-arrow/h5wasm dependencies, and the whole commands/builtin/filetype_factory/ package in both languages (with its filetype_read / filetypeRead op knobs). A file with an unregistered extension is read as raw bytes. The one surviving extension point is registration on a mount: a command or op carrying a filetype resolves as (name, filetype) before (name, resource) before (name,). examples/{python,typescript}/filetype/ register a .tally renderer end to end and are gated in CI against integ/truth/*/filetype.json; tests/commands/custom/test_filetype_fns.py and test_unregister_removes_all_filetypes cover the unit path.