agentleFS
JuliaPlutoJuliaPluto/Pluto.jl/.claude/CLAUDE.md

Pluto.jl

CLAUDE.md5.4k starsChanged 12 months agoMITView on GitHub

Pluto.jl is a reactive Julia notebook: a Julia web server that executes notebook code in isolated worker processes and pushes state diffs to a browser frontend (pure ES modules, no build step in dev). There are three cooperating layers, plus a bundler that packages the frontend for release. The server serves frontend/ directly — edits to JS/CSS need only a browser reload. With frontend-dist/ present (e.g. after a bundler run), the server serves that instead; delete or rename it to…

  • Deletes or force-pushes
  • Installs packages

1 other project uses a version of this.

Trending

Less talk lately.about the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 1 mentionJun 2026: 20 mentionsJul 2026: 14 mentionsAug 2026: 3 mentionsSep 2026: 2 mentionsOct 2026: 6 mentionsNov 2026: 4 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the JuliaPluto/Pluto.jl repository that our weekly crawl found. There is no adoption data for this file yet.

Most recently taken up by

Who's talking about JuliaPluto/Pluto.jl

The biggest 5 of 50 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 50

Talked about on GitHub (50 times).

On GitHub · 50

45 more on GitHub
  • Other versions1 project uses a version of this.

    Word for word · 1

    1. fonsp/Pluto.jl★ 5.4k100% same

    Edited · 0

    None found.

    Wrote their own version · 0

    None found.

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository3 other files it gives its agents.

The file

We split this CLAUDE.md into the rules it gives an agent

7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Put new styles in the existing CSS files (usually frontend/editor.css) — not inline in JS.

    line 79
  2. Very specific:

    Prefer custom element names (<pluto-pkg-terminal>) as CSS selectors over generic classes.

    line 82
  3. Distinctive:

    Avoid inline styles except for small values that genuinely change at runtime.

    line 83
  4. Very specific:

    Use Ionicons pinned to 5.5.1: https://cdn.jsdelivr.net/gh/ionic-team/ionicons@5.5.1/src/svg/<name>.svg.

    line 87
  5. Distinctive:

    All user-facing strings must be localized.

    line 91
  6. Very specific:

    Add every new key to frontend/lang/english.json (the fallback).

    line 99
  7. Very specific:

    Important: use gh run view --log, not gh run download.

    line 119

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md

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

Pluto.jl is a reactive Julia notebook: a Julia web server that executes notebook code in isolated worker processes and pushes state diffs to a browser frontend (pure ES modules, no build step in dev). There are three cooperating layers, plus a bundler that packages the frontend for release.

Repository layout (big picture)

  • src/ — the Julia server. src/Pluto.jl is the entry point and orders the includes; read it to understand module dependencies.
    • src/notebook/ — the notebook file format (Cell, Notebook, saving/loading the .jl format that sample/ demonstrates).
    • src/analysis/ — static code analysis (Parse.jl, DependencyCache.jl, MoreAnalysis.jl). Uses ExpressionExplorer + PlutoDependencyExplorer to build the reactive dependency graph without executing code.
    • src/evaluation/ — runs cells in the correct topological order. WorkspaceManager.jl manages worker processes (via Malt); Run.jl / RunBonds.jl drive reactive re-execution; MacroAnalysis.jl handles the round-trip needed to expand macros in the worker before analyzing them.
    • src/runner/PlutoRunner/ — code that runs inside the worker process. It is a separate sub-package loaded into each worker; it formats outputs, captures logs, evaluates cells, and communicates via MsgPack. Keep its dependencies minimal — anything it imports pollutes the user's notebook namespace.
    • src/packages/ — per-notebook package environments (Pluto's built-in Pkg manager). PkgCompat.jl wraps Pkg internals; Packages.jl is the reactive integration.
    • src/webserver/ — HTTP + WebSocket server. Dynamic.jl is the main RPC surface (the "update" protocol the frontend talks to); Firebasey.jl / FirebaseyUtils.jl implement JSON-patch-like diffing used to sync notebook state; SessionActions.jl is the high-level API (open, shutdown, move); Static.jl serves the frontend files.
  • frontend/ — plain ES modules, run directly in the browser during development (no bundler needed). Preact + HTM (frontend/imports/Preact.js) for UI, CodeMirror 6 in components/CellInput/. editor.js is the notebook UI entry; index.js is the welcome/launcher. common/PlutoConnection.js is the WebSocket client that talks to src/webserver/Dynamic.jl.
  • frontend-bundler/ — Parcel-based bundler with a custom parcel-resolver-like-a-browser resolver that is intentionally restrictive: it only resolves imports the same way a browser would, so nothing can accidentally work in the bundle that wouldn't work in dev. Output goes to frontend-dist/ (loaded instead of frontend/ when present; see FRONTEND_DIST_DIR in src/Pluto.jl).
  • test/ — Julia backend tests plus a separate Node/Jest+Puppeteer E2E suite in test/frontend/.
  • sample/ — example notebooks that double as test fixtures (they are real Pluto notebook files).

Commands

Running Pluto locally (dev)

julia --project=. -e 'import Pkg; Pkg.instantiate()'
julia --project=. -e 'import Pluto; Pluto.run()'

The server serves frontend/ directly — edits to JS/CSS need only a browser reload. With frontend-dist/ present (e.g. after a bundler run), the server serves that instead; delete or rename it to go back to dev mode.

Backend tests (Julia)

julia --project=. -e 'import Pkg; Pkg.test()'

To run a single file, edit test/runtests.jl (the file has a comment at the top explaining this) and comment out every @timeit_include line except helpers.jl and the one you want. The in-file Revise snippet near the top is the fast iteration path.

  • Env var PLUTO_TEST_ONLY_COMPILETIMES=true runs only compiletimes.jl and exits.
  • Many tests spawn worker processes; verify_no_running_processes() is called between test files — don't reorder without understanding this.

Frontend E2E tests (test/frontend/, run from that directory)

npm install
# in another terminal, start Pluto on a known port:
PLUTO_PORT=2345 julia --project=/path/to/Pluto -e \
  'import Pluto; Pluto.run(port=2345, require_secret_for_access=false, launch_browser=false)'
# then:
PLUTO_PORT=2345 npm run test                                    # headless
HEADLESS=false PLUTO_PORT=2345 npm run test                     # watch the browser
HEADLESS=false PLUTO_PORT=2345 npm run test -- -t="suite name"  # one suite

To fail a test on a handled-but-bad situation, log with console.error("PlutoError ...") — the runner treats any PlutoError string in console output as a failure.

TypeScript check (matches CI TypeScriptCheck.yml)

cd frontend && npm install
tsc --noEmit --strictNullChecks false   # from repo root

tsconfig.json has allowJs + checkJs — the frontend is plain JS with JSDoc type annotations, checked as TS.

Bundler

cd frontend-bundler
npm install
rm -rf ../frontend/.parcel-cache ../frontend-dist ../frontend-dist-offline
npm run build          # online bundle → frontend-dist/
npm run build-offline  # offline bundle → frontend-dist-offline/

Requires Node 22.

Formatting

Prettier config at the repo root: 160-col, 4-space, no semicolons, double quotes, ES5 trailing commas.

Frontend conventions (from .cursor/rules/)

Styling

  • Put new styles in the existing CSS files (usually frontend/editor.css) — not inline in JS.
  • New colors go as CSS variables in both frontend/themes/light.css and frontend/themes/dark.css. Don't reuse an existing variable with the wrong semantics.
  • The same frontend serves the IDE and Print mode (PDF/HTML export). If a UI element should not appear in Print, add a rule to frontend/hide-ui.css.
  • Prefer custom element names (<pluto-pkg-terminal>) as CSS selectors over generic classes.
  • Avoid inline styles except for small values that genuinely change at runtime.

Icons

  • Icons are empty <span>s styled in CSS (background-image or ::before), never imported from a JS icon library and never PNG/JPG.
  • Use Ionicons pinned to 5.5.1: https://cdn.jsdelivr.net/gh/ionic-team/ionicons@5.5.1/src/svg/<name>.svg.
  • Size in em, use background-size: contain, theme via filter: var(--image-filters) (or filter: invert(1) for light-on-dark).

Localization (i18next)

All user-facing strings must be localized. Always localize complete sentences, not fragments.

import { t, th } from "../../lang/lang.js"
t("t_remove_from_recent_notebooks")              // plain text (titles, aria-labels)
th("t_newnotebook")                               // content with HTML/Preact
th("t_welcome_to_pluto", { pluto: html`<img/>`})  // with interpolation
  • Keys always start with t_.
  • Add every new key to frontend/lang/english.json (the fallback); other locales in the same folder.
  • Pluralization: t_foo + t_foo_one.

Downloading CI failure logs

Grab logs from the N most recent failed runs of a workflow (e.g. FrontendTest.yml) for local analysis:

# 1. List the failed runs as JSON (pick N with --limit)
gh run list --repo JuliaPluto/Pluto.jl --workflow FrontendTest.yml \
    --status failure --limit 20 \
    --json databaseId,displayTitle,createdAt,conclusion

# 2. For each databaseId, save the expanded job log
mkdir -p ci_logs_failed
for id in <id1> <id2> ...; do
    gh run view --repo JuliaPluto/Pluto.jl "$id" --log > "ci_logs_failed/${id}.log"
done

Important: use gh run view --log, not gh run download. gh run download fetches workflow artifacts (for FrontendTest.yml those are screenshot bundles), not the stdout/stderr of the jobs.

Each log is ~80–150 KB; 20 runs fit in ~2 MB. Search them with Grep for patterns like FAIL __tests__, TimeoutError, AssertionError, ProtocolError, or Tests:.*failed.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.