If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/chaosprint/glicol shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 6 active contributors
• Distributed ownership (top contributor 48% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live chaosprint/glicol repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/chaosprint/glicol.

What it runs against: a local clone of chaosprint/glicol — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in chaosprint/glicol | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 427 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of chaosprint/glicol. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/chaosprint/glicol.git
#   cd glicol
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of chaosprint/glicol and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "chaosprint/glicol(\\.git)?\\b" \\
  && ok "origin remote is chaosprint/glicol" \\
  || miss "origin remote is not chaosprint/glicol (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "rs/main/src/lib.rs" \\
  && ok "rs/main/src/lib.rs" \\
  || miss "missing critical file: rs/main/src/lib.rs"
test -f "js/src/glicol-engine.js" \\
  && ok "js/src/glicol-engine.js" \\
  || miss "missing critical file: js/src/glicol-engine.js"
test -f "rs/Cargo.toml" \\
  && ok "rs/Cargo.toml" \\
  || miss "missing critical file: rs/Cargo.toml"
test -f "js/package.json" \\
  && ok "js/package.json" \\
  || miss "missing critical file: js/package.json"
test -f "js/src/glicol-mode.js" \\
  && ok "js/src/glicol-mode.js" \\
  || miss "missing critical file: js/src/glicol-mode.js"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 427 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~397d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/chaosprint/glicol"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Glicol is a graph-oriented live coding language with a real-time audio engine written entirely in Rust, enabling garbage-collection-free, memory-safe music synthesis and DSP that runs identically in web browsers, VST plugins, and on embedded boards like Bela. It combines declarative synth-like syntax for live performance with sample-accurate audio synthesis, letting musicians write high-level control code and low-level DSP in a single language. Monorepo structure with /js containing the JavaScript/web bindings and assets (50+ drum sample .wav files in js/assets/), and /rs (inferred from description) containing the Rust audio engine and platform-specific targets (VST, Bela). The npm package glicol wraps the WASM-compiled Rust core for browser use, with the web app at glicol.org serving as the primary reference implementation and playground.

Electronic musicians and live coders who perform in browsers or DAWs, audio app developers building browser-based music tools, DSP engineers who want memory-safe real-time audio without GC pauses, and educators teaching computer music and signal processing. Contributors are typically Rust developers familiar with audio DSP or web audio APIs.

Actively developed but still pre-1.0 (currently v0.4.0). The project has a CI/CD pipeline (.github/workflows/ci.yml), organized monorepo structure, a live web app at glicol.org with production features (sample drag-drop, collaborative yjs support), and an active Discord community. However, the absence of a test script in package.json and pre-release version number indicate it's not yet considered stable for all use cases.

Single maintainer (chaosprint/Qichao Lan) is visible in package.json authorship, which is a medium bus-factor risk. The npm package depends on a Rust-compiled WASM module (implied by 'garbage-collection-free' claim) whose build process isn't detailed in the visible JavaScript package.json—build failures could be opaque. The declarative LCS-based update algorithm is a non-trivial system that could have edge cases in live coding scenarios.

The project is actively maintained with version 0.4.0 published to npm. Recent work likely includes stability improvements (based on pre-1.0 status), sample library expansion (60+ drum assets in js/assets/), and collaborative features (yjs integration for decentralized real-time collaboration mentioned in README). The presence of a GitHub Actions CI workflow suggests active testing and deployment.

Clone the repo and install npm dependencies (the /js directory is the web package):

git clone https://github.com/chaosprint/glicol.git
cd glicol/js
npm install

For Rust development, you'll need rustup and wasm-pack to rebuild the WASM bindings (not detailed in visible config, but required for 'Rust written in' language).

Daily commands: For the web app locally (requires Rust toolchain and wasm-pack to build WASM bindings):

cd js
npm install
npm run build  # (inferred; build script not shown in package.json, may require wasm-pack build)

The live app runs at https://glicol.org; clone + local build requires WASM compilation setup not detailed in visible config.

• rs/main/src/lib.rs — Core Rust library entry point that exports the audio DSP engine and graph compilation logic; all audio processing flows through here.
• js/src/glicol-engine.js — JavaScript/WebAssembly bridge that initializes the Rust engine and handles audio node graph execution in the browser.
• rs/Cargo.toml — Workspace manifest defining all Rust crate dependencies and build configuration; required to understand the entire build system.
• js/package.json — JavaScript project manifest with build scripts and WebAssembly bindings; orchestrates npm package publication for browser distribution.
• js/src/glicol-mode.js — Live coding editor syntax definition; implements the graph-oriented language parsing and highlighting.
• rs/main/examples/hello.rs — Demonstrates the canonical usage pattern of Glicol's API; shows how to construct and execute audio graphs.

Add a new audio DSP node (e.g., new oscillator, filter, or effect)

1. Define the node struct and implement its processing logic in rs/main/src/lib.rs, typically as a module that accepts audio inputs and parameters. (rs/main/src/lib.rs)
2. Register the node in the parser's grammar and syntax rules so it can be recognized in Glicol code. (rs/main/src/lib.rs)
3. Add a reference example in the examples directory (e.g., rs/main/examples/newnode.rs) showing how to use it. (rs/main/examples/hello.rs)
4. Update the API documentation by adding the node's signature to js/src/glicol-api.json so the web IDE provides autocomplete. (js/src/glicol-api.json)

Add a new built-in audio sample for the sample library

1. Place the .wav file in the js/assets/ directory with a descriptive name (e.g., js/assets/newsample.wav). (js/assets)
2. Run the asset conversion utility (js/assets/2json.js) to embed the sample in the engine binary or sample index. (js/assets/2json.js)
3. Update js/src/sample-list.json to register the new sample so it appears in the UI and is accessible via the samples node. (js/src/sample-list.json)

Extend the live coding syntax with new language constructs

1. Add grammar rules and parsing logic in rs/main/src/lib.rs to recognize the new syntax pattern. (rs/main/src/lib.rs)
2. Update the syntax mode in js/src/glicol-mode.js to highlight and tokenize the new syntax in the editor. (js/src/glicol-mode.js)
3. Create an example in rs/main/examples/ demonstrating the new feature (e.g., rs/main/examples/newfeature.rs). (rs/main/examples/hello.rs)
4. Update js/src/glicol-api.json with autocomplete and documentation for the new construct. (js/src/glicol-api.json)

• Rust — Enables memory-safe, zero-copy audio processing with no runtime garbage collection; essential for real-time audio synthesis with predictable latency.
• WebAssembly (WASM) — Compiles Rust to near-native performance in the browser; allows the same DSP engine to run on multiple platforms (web, VST, native) with minimal porting.
• Web Audio API — Provides access to the browser's audio subsystem and hardware; integrates Glicol synthesis with the host audio context.
• Vite — Fast, modern JavaScript bundler with HMR support; enables rapid iteration of the live coding IDE.
• CodeMirror-style syntax mode (glicol-mode.js) — Provides real-time syntax highlighting and parsing feedback for the graph-oriented DSL without heavy dependencies.

• Graph-oriented (node-based) language instead of a traditional text DSL

  • Why: Explicitly models audio signal flow as a directed acyclic graph; makes dependency and data flow transparent.
  • Consequence: Slightly steeper learning curve for users familiar with imperative languages, but enables powerful live-patching and visual representations.

• GC-free Rust implementation in audio thread

  • Why: Prevents garbage collection pauses that would cause audio clicks, pops, and glitches during synthesis.
  • Consequence: Requires explicit memory management patterns and careful API design; not beginner-friendly but guarantees audio quality.

• Single-threaded WASM audio engine (no background workers for DSP)

  • Why: Simplifies state management and avoids synchronization overhead; Web Audio already handles threading internally.
  • Consequence: Audio workload must fit in callback latency (~10–20ms); very heavy graphs may cause buffer underruns, but typical music graphs are well-suited.

• Hot-reload without stopping audio playback

  • Why: Enables live coding experience where code changes take effect in real time.
  • Consequence: Requires atomic graph swaps and careful handling of node state transitions; increases engine complexity but is core to the UX.

• Does not provide a visual node editor UI (focused on text-based live coding).
• Does not handle disk I/O or sample file loading from the filesystem (relies on pre-bundled assets or streaming from URLs).
• Does not support plugin architecture or user-defined Rust node extensions (sealed API surface).
• Not a DAW; lacks timeline, arrangement, MIDI sequencing, or project save/load (purpose-built for real-time performance).
• Does not guarantee sub-millisecond latency; trades some latency for safety and simplicity.

The WASM build process is not visible in the JavaScript package.json—Rust → WASM compilation likely happens in CI or a missing build script, and local development may fail silently if wasm-pack is not installed. The 'LCS algorithm' for declarative updates (mentioned in README) is a custom system that differs from React reconciliation; understand it before modifying live update logic. Samples in js/assets/ are preloaded; adding new ones requires both file addition and possible browser caching considerations. No test script in package.json; testing strategy is unclear—check CI or Rust cargo test setup.

• WebAssembly (WASM) Memory Model — Glicol's entire real-time audio engine is compiled to WASM; understanding linear memory, module instantiation, and WASM GC implications is critical for debugging audio glitches or performance bottlenecks
• Graph-oriented DSP (Directed Acyclic Graphs in Audio) — Glicol's core abstraction is a DAG of audio nodes; understanding node topology, feedback prevention, and topological sorting is essential for language feature design
• Longest Common Subsequence (LCS) Algorithm — Glicol uses LCS for declarative live updates (no explicit select/update, just edit and it reconciles); this diff algorithm determines what audio nodes are added/removed/modified
• Conflict-free Replicated Data Type (CRDT) — Glicol's yjs-based collaboration uses CRDTs to merge concurrent edits without a central server; understanding eventual consistency is key to the 'be-ready' mechanism
• Real-time Audio Thread Safety (Rust async/Send + Sync) — Glicol achieves garbage-collection-free real-time audio by careful use of Rust's type system; understanding mutex-free data structures and lock-free algorithms prevents audio dropouts
• Sample-accurate Audio Synthesis — Glicol allows both high-level synth control and low-level sample-by-sample DSP; understanding audio buffer sizes, control-rate vs. audio-rate, and scheduling is essential
• VST Plugin Architecture — Glicol can target VST plugins; understanding the plugin lifecycle, parameter automation, and DAW communication is needed for VST-specific features

• rust-lang/rust — Glicol is built on Rust and leverages its memory safety guarantees for real-time audio; understanding Rust stability and async patterns is essential
• rustwasm/wasm-pack — Required toolchain to compile the Glicol Rust engine to WebAssembly; the entire browser distribution depends on this
• yjs/yjs — Glicol's decentralized collaboration feature uses yjs CRDTs; understanding conflict-free replication is key to the 'be-ready' mechanism
• ojack/hydra — Integrated visual synthesis framework mentioned in README; Glicol users can mix Hydra code for visuals alongside audio code
• supercollider/supercollider — Spiritual predecessor and competing live coding language; understanding SuperCollider's graph model and performance characteristics provides context for Glicol's design choices

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add npm package.json test script and Jest/Vitest configuration for js/npm module

The root package.json has a placeholder test script ('Error: no test specified'). The js/npm folder contains critical files like glicol-engine.js, nodechain.js, and nosab.js with no apparent test coverage. Adding a proper test suite would catch regressions in the WASM bindings and JavaScript wrapper logic that users depend on.

• [ ] Set up Jest or Vitest in js/npm with config file (jest.config.js or vitest.config.ts)
• [ ] Create test files for js/npm/index.js, js/npm/glicol-engine.js, and js/npm/detect.js covering initialization and basic API calls
• [ ] Update root package.json test script to run the npm module tests
• [ ] Add test step to .github/workflows/ci.yml to run tests on PR/push

Add webpack/build configuration and documentation for js/assets bundling

The js/assets folder contains 40+ WAV files (drums, synths, samples) but there's no visible build process documented. A production setup should bundle these assets efficiently with the WASM module. Adding a build configuration would help contributors and users understand asset loading and reduce bundle size.

• [ ] Create js/webpack.config.js (or js/vite.config.js) with asset loader configuration for WAV files
• [ ] Add asset versioning/hashing to prevent cache issues
• [ ] Document asset loading in js/README.md with examples of how users should reference samples
• [ ] Update js/npm/glicol-engine.js if needed to reference bundled asset paths correctly

Create comprehensive GitHub Actions workflow for multi-platform Rust/WASM build and NPM publish

The .github/workflows/ci.yml exists but is not shown in detail. Given that glicol compiles Rust to WebAssembly for the npm package (js/npm/glicol_wasm.js and .wasm files), the CI should explicitly test WASM compilation on Linux/macOS and publish to npm on tagged releases. This prevents broken releases and ensures platform compatibility.

• [ ] Extend .github/workflows/ci.yml to include wasm-pack build steps for Rust → WASM compilation
• [ ] Add separate jobs for testing on Linux and macOS (Rust toolchain differences)
• [ ] Create .github/workflows/publish.yml triggered on version tags to publish js/npm to NPM registry
• [ ] Document the build process in js/README.md and root README.md (how to build locally, how releases work)

• Add a test script to package.json and implement basic npm test coverage for the JavaScript bindings (currently missing entirely, blocked by understanding where Rust tests live and how they integrate with JS)
• Document the WASM build process and add a BUILD.md guide in /js explaining how to compile Rust → WASM locally, including wasm-pack version requirements (completely absent, but critical for contributors wanting to modify the audio engine)
• Expand js/README.md with concrete code examples for the NPM package (e.g., instantiation, sample loading, graph construction) beyond the current minimal README, mirroring the language documentation at glicol.org

The Glicol codebase shows reasonable security baseline but has several areas for improvement. Primary concerns include lack of test coverage, WebAssembly integrity verification, and missing security headers. The Rust backend (rs/) was not fully analyzed due to limited visibility. No hardcoded secrets or obvious injection vulnerabilities were detected in the visible JavaScript code. Recommended immediate actions: (1) Implement SRI for WASM files, (2) Add security headers and CSP, (3) Set up automated testing and security scanning, (4) Create security policy documentation.

• Medium · Missing test coverage and no test execution — js/package.json - test script. The package.json test script is a placeholder that exits with error code 1. This indicates no automated security or functional tests are being executed in the CI/CD pipeline, which could allow vulnerabilities to slip through. Fix: Implement comprehensive test suite including security tests, run tests in CI/CD pipeline (.github/workflows/ci.yml), and ensure tests pass before deployment.
• Medium · WebAssembly binary files without integrity verification — js/npm/glicol_wasm_bg.wasm, js/src/glicol_wasm_bg.wasm. The codebase includes compiled WebAssembly binaries (glicol_wasm_bg.wasm) that are loaded and executed in the browser. Without subresource integrity (SRI) or hash verification, there's a risk of tampering during distribution or man-in-the-middle attacks. Fix: Implement Subresource Integrity (SRI) hashes for WASM files in HTML/JavaScript loaders, verify WASM signatures during build process, and ensure secure distribution over HTTPS.
• Medium · No security headers or CSP configuration visible — js/index.html, js/vite.config.js. The HTML entry point (js/index.html) and main application lack visible security headers (CSP, X-Frame-Options, etc.) which could expose the application to XSS and clickjacking attacks. Fix: Configure Content Security Policy (CSP) headers, add security headers (X-Frame-Options, X-Content-Type-Options, etc.) in Vite configuration or server setup, implement proper CSP for inline scripts.
• Low · Incomplete dependency information — js/package.json, js/package-lock.json, js/pnpm-lock.yaml. While the provided package.json shows no direct dependencies listed (only devDependencies would be expected in js/package.json and js/npm/package.json), the actual dependency tree is not fully visible for analysis. Fix: Run 'npm audit' or 'pnpm audit' regularly to identify vulnerable transitive dependencies, maintain lock files in version control, and update dependencies promptly.
• Low · No CHANGELOG or security policy visible — Repository root. The repository lacks a visible SECURITY.md or security policy file for reporting vulnerabilities responsibly, and no CHANGELOG for tracking security fixes across versions. Fix: Create SECURITY.md with responsible disclosure guidelines, maintain CHANGELOG.md documenting security patches, and set up security advisories on GitHub.
• Low · Vite configuration not fully auditable — js/vite.config.js. The build configuration file (js/vite.config.js) content is not provided, making it difficult to assess build security, source maps handling, and production optimization settings. Fix: Review and harden Vite configuration: disable source maps in production, enable minification, use secure server settings, implement build-time CSP hash generation.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.