jon.recoil.org / js_top_worker
this repo has no description
fork atom
js_top_worker / CLAUDE.md
at main 2.3 kB view raw view code

CLAUDE.md#

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview#

This is an OCaml toplevel (REPL) designed to run in a web worker. The project consists of multiple OPAM packages that work together to provide an OCaml interactive environment in the browser.

Build Commands#

# Build the entire project
dune build

# Run tests
dune runtest

# Build and watch for changes
dune build --watch

# Run a specific test
dune test test/cram

Running the Example#

The worker needs to be served by an HTTP server rather than loaded from the filesystem:

dune build
cd _build/default/example
python3 -m http.server 8000
# Then open http://localhost:8000/

Architecture#

The codebase is organized into several interconnected packages:

  • js_top_worker: Core library implementing the OCaml toplevel functionality
  • js_top_worker-web: Web-specific worker implementation with browser integration
  • js_top_worker-rpc.message: Message protocol definitions for worker communication
  • js_top_worker-client.msg: Client library for communicating with the worker (Lwt-based, message protocol)
  • js_top_worker-unix: Unix implementation for testing outside the browser
  • js_top_worker-bin: Command-line tools including jtw for package management

Key directories:

  • lib/: Core toplevel implementation with OCaml compiler integration
  • idl/: Message protocol definitions and client library
  • example/: Example applications demonstrating worker usage
  • bin/: Command-line tools, notably jtw for OPAM package handling

The system uses a simple JSON message protocol for communication between the client and worker, with support for both browser WebWorkers and Node.js for testing.

Technical Q&A Log#

When the user asks technical questions about the codebase, tools, or dependencies (especially js_of_ocaml, dune, findlib, etc.), Claude should:

  1. Answer the question with technical accuracy
  2. Record the Q&A in docs/technical-qa.md with:
    • The question asked
    • The answer provided
    • Verification steps taken (code inspection, testing, documentation lookup)
    • Date of the entry

This creates institutional knowledge that persists across sessions.