What Are the Default File Paths for Feynman Assets? A Complete Guide

Feynman stores repository-level assets in the root assets/ folder, compiles web workbench files into dist/workbench-web/assets/ served via /app-shell/assets/, and locates Claude-Science seed data in ~/.claude-science/runtime/.../seed-assets/.

Understanding the default file paths for Feynman assets is essential when configuring static file serving, customizing the workbench UI, or debugging resource loading issues in the advaitpaliwal/feynman repository. The project organizes static resources into three distinct tiers: repository-level documentation assets, compiled web workbench bundles, and runtime Claude-Science seed files.

Repository-Level Static Assets

Feynman keeps high-level documentation images and logos in the repository root under the assets/ directory. These files are not processed by the build system and are typically referenced directly in documentation.

The default paths include:

• assets/hero.png – Primary hero image used in README and documentation
• assets/hero-raw.png – Raw unprocessed version of the hero asset

These resources are accessed using simple relative paths such as ./assets/hero.png when referenced within markdown or configuration files.

Web Workbench Asset Paths

The React-based workbench interface requires compiled JavaScript, CSS, fonts, and WASM modules. After running the build command, these assets populate a specific distribution directory.

Build Output Location

Executing npm run build:workbench-web copies all required static files into:

dist/workbench-web/assets/

This directory contains the bundled application code, stylesheets, and binary assets needed to render the workbench UI.

Runtime Serving URL

At runtime, the Feynman server exposes these built assets through a dedicated URL prefix. The constant WORKBENCH_WEB_PREFIX = "/app-shell" (defined in src/workbench/static-shell.ts) determines the base path.

Access web workbench assets via:

/app-shell/assets/{filename}

For example, the main application bundle is available at /app-shell/assets/app.js.

Claude-Science Seed Assets

For Claude-Science integration, Feynman maintains a separate asset cache located outside the repository directory. The code resolves this path using the CLAUDE_SCIENCE_HOME environment variable.

The default location follows this pattern:

~/.claude-science/runtime/{timestamp}/seed-assets/

In src/workbench/claude-science.ts, the seedPath constant points to this directory, which holds pre-bundled resources required by the Claude-Science extension. Once the runtime is initialized, these assets are also served through the /app-shell/assets/ endpoint.

Asset Serving Implementation

The core logic that maps URL requests to physical file paths resides in src/workbench/static-shell.ts. The sendWorkbenchWeb function handles all requests starting with /app-shell.

When a request arrives at /app-shell/assets/..., the server:

1. Extracts the asset name from the request URL
2. Resolves it against the dist/workbench-web directory
3. Validates the path to prevent directory traversal attacks
4. Streams the file with the appropriate MIME type

The helper function webAssetContentType (lines 42–68) maps file extensions to correct Content-Type headers, ensuring browsers properly load JavaScript, CSS, fonts, images, and WebAssembly modules.

// Example: Serving an asset from the built workbench
import { sendWorkbenchWeb } from "./src/workbench/static-shell";

http.createServer((req, res) => {
  const url = new URL(req.url!, `http://${req.headers.host}`);
  // All requests under /app-shell are handled here
  if (sendWorkbenchWeb(res, {}, url, {})) return;
  // …other routing logic
});

// Example: Referencing a repository-level image in README.md
![Feynman CLI](/assets/hero.png)

// Example: Accessing a built JS bundle directly
fetch("http://localhost:3000/app-shell/assets/app.js")
  .then(r => r.text())
  .then(console.log);

Summary

• Repository assets live in the root assets/ folder (e.g., assets/hero.png) and are referenced via relative paths
• Web workbench assets compile to dist/workbench-web/assets/ and are served at the /app-shell/assets/ URL prefix
• Claude-Science seeds are stored in ~/.claude-science/runtime/.../seed-assets/ based on the CLAUDE_SCIENCE_HOME environment variable
• The sendWorkbenchWeb function in src/workbench/static-shell.ts implements the routing logic, while webAssetContentType ensures correct MIME types

Frequently Asked Questions

Where does Feynman store built web assets?

After running npm run build:workbench-web, all compiled JavaScript, CSS, and static resources are placed in dist/workbench-web/assets/. This directory serves as the physical source for files requested via the /app-shell/assets/ endpoint.

What URL prefix serves workbench static files?

The workbench serves static files under the /app-shell/assets/ prefix. This value is defined by the WORKBENCH_WEB_PREFIX constant in src/workbench/static-shell.ts. Requests targeting this path trigger the asset serving logic rather than standard page routing.

How does Feynman resolve the Claude-Science seed directory?

The system resolves the Claude-Science seed path from the CLAUDE_SCIENCE_HOME environment variable, defaulting to ~/.claude-science/runtime/{timestamp}/seed-assets/. The seedPath constant in src/workbench/claude-science.ts references this location when loading extension resources.

Can repository-level assets be served by the workbench?

Repository-level assets in the root assets/ folder are not automatically served by the workbench server. They are intended for documentation use only. To serve custom static files through the workbench, place them in the dist/workbench-web/assets/ directory after building, or extend the server logic in static-shell.ts to handle additional routes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}