ICL is an enhanced REPL for Common Lisp. It provides a modern interactive experience with readline-style editing, persistent history, tab completion, and an extensible command system. ICL works in your terminal, in a web browser with package browsing and data visualization, or integrated with Emacs via SLY/SLIME.

Syntax highlighting, paren matching, tab completion, paredit mode, and interactive inspector

Package browser, symbol inspector, data visualization, and class hierarchy graphs

Interactive Speedscope flame graphs for performance profiling (SBCL only)

Profile any expression with ,flame and explore the results in an interactive Speedscope visualization. Switch between Time Order, Left Heavy, and Sandwich views to identify performance bottlenecks.

• Syntax highlighting - Colorized input with distinct colors for keywords, strings, comments, numbers, and symbols
• Parenthesis matching - Real-time highlighting of matching parentheses as you type
• Paredit mode - Structural editing with auto-close parens, safe deletion, and sexp navigation
• Multi-line input - Automatically detects incomplete expressions with smart indentation
• Persistent history - Command history saved across sessions
• Tab completion - Complete symbols, package-qualified names, and keywords
• Command system - Built-in commands prefixed with comma (e.g., ,help)
• Multiple Lisp support - Works with SBCL, CCL, ECL, CLISP, ABCL, Clasp, and Roswell
• Error backtraces - Automatic backtrace capture with ,bt command to view stack traces
• Thread inspection - List and inspect threads in the inferior Lisp
• Documentation lookup - Quick access to function docs and apropos search
• Interactive object inspector - TUI for exploring objects with keyboard navigation
• Tracing - Enable/disable function tracing
• Source location - Find where functions are defined
• Terminal-aware colors - Automatically detects light/dark terminal background
• AI integration - Use ,explain to get AI-powered explanations of code, errors, and results
• Browser interface - Web UI with package browser, symbol list, inspector, and xterm.js terminal
• Data visualization - Visualize hash tables, classes, sets, SVG, HTML, JSON, Vega-Lite charts, and Mermaid diagrams
• Custom visualizations - Define icl-runtime:visualize methods for your own classes
• Flame graph profiling - Interactive Speedscope visualizations for performance analysis (SBCL)
• Emacs integration - Works with SLY/SLIME for synchronized browser visualization

Download from GitHub Releases:

Roswell users can also install with ros install atgreen/icl.

git clone https://github.com/atgreen/icl.git
cd icl
ocicl install
make

Requires SBCL, ocicl, and libfixposix-devel.

Start ICL (auto-detects available Lisp):

icl

Specify a Lisp implementation:

icl --lisp ccl
icl --lisp ecl
icl --lisp roswell  # Use Roswell's managed environment

Evaluate an expression and exit:

icl -e '(+ 1 2 3)'

Load a file before starting the REPL:

icl -l init.lisp

Connect to an existing Slynk server:

icl --connect localhost:4005

Skip loading config file:

icl --no-config

Start with browser interface (opens IDE alongside terminal REPL):

icl -b

ICL ships an Emacs helper for SLY or SLIME that launches the browser REPL and syncs visualizations with evals.

Minimal setup (adjust the path for your install):

(add-to-list 'load-path "/path/to/icl")
(require 'icl)

Commands:

• M-x icl — start ICL browser connected to the current SLY/SLIME session
• M-x icl-stop — stop the ICL process
• M-x icl-restart — restart ICL

If you have both SLY and SLIME installed, ICL prefers SLY by default. You can override this:

(setq icl-backend 'slime)  ;; or 'sly or 'auto

If you install the package via RPM/DEB/Windows installer, the Emacs files are placed in a standard site-lisp directory and you can just (require 'icl).

Suggested install locations for Emacs files:

• RPM: %{_datadir}/emacs/site-lisp/icl/icl.el and icl-autoloads.el
• DEB: /usr/share/emacs/site-lisp/icl/icl.el and icl-autoloads.el
• Windows: <INSTALL>/share/emacs/site-lisp/icl/icl.el and icl-autoloads.el

For packaging, include icl-autoloads.el and add the site-lisp path to Emacs’ load-path (via site-start.d or the installer), then users can:

(require 'icl)

Commands are prefixed with a comma. Type ,help for a full list.

The interactive inspector (,i or ,inspect) provides a TUI for exploring objects:

The ,flame command (aliases: ,flamegraph, ,fg) profiles the expression and opens an interactive Speedscope flame graph in the browser. Requires browser mode (,browser or icl -b).

The ,viz command automatically detects the type and displays an appropriate visualization:

• Class names: 'standard-object → interactive class hierarchy graph with slots
• Hash-tables: *my-ht* → key-value table
• FSet collections: sets, maps, and bags with appropriate displays
• JSON strings: "{\"key\": \"value\"}" → syntax-highlighted, pretty-printed JSON
• Image byte arrays: PNG, JPEG, GIF, WebP data → displayed inline
• SVG strings: "<svg>...</svg>" → rendered SVG graphics
• HTML strings: "<!DOCTYPE html>..." → rendered in sandboxed iframe

Visualize one or more FSet sets as Venn diagrams:

,viz *fruits*                    ; Single set as circle with members
,viz *fruits* *red-things*       ; Two-set Venn diagram showing overlap
,viz *set-a* *set-b* *set-c*     ; Three-set Venn diagram

• Single set: Circle displaying members inside
• Two sets: Classic Venn diagram with left-only, intersection, and right-only regions
• Three sets: Triangle arrangement showing all 7 regions with counts

Venn diagrams automatically refresh after each REPL evaluation to reflect data changes.

The class hierarchy graph supports interactive exploration:

• Click a node to see available subclasses and add them one at a time
• Hover over a node to highlight all ancestor classes up to the root
• Drag to pan, scroll to zoom the graph

Visualize image data stored in byte arrays:

;; Load an image file into a byte vector
(defvar *img* (alexandria:read-file-into-byte-vector #P"photo.png"))
,viz *img*

Supported formats (detected by magic bytes): PNG, JPEG, GIF, WebP.

JSON strings are automatically pretty-printed with syntax highlighting:

(defvar *data* "{\"name\": \"Alice\", \"scores\": [95, 87, 92]}")
,viz *data*

All visualization panels auto-refresh after REPL evaluations.

Define methods on icl-runtime:visualize to create custom visualizations for your own classes:

;; Visualize a game board as HTML
(defmethod icl-runtime:visualize ((obj my-game-state))
  (list :html (render-board-html obj)))

;; Visualize data as SVG chart
(defmethod icl-runtime:visualize ((obj my-data-series))
  (list :svg (generate-chart-svg obj)))

;; Visualize config as JSON
(defmethod icl-runtime:visualize ((obj my-config))
  (list :json (serialize-to-json obj)))

;; Visualize metrics as Vega-Lite bar chart
(defmethod icl-runtime:visualize ((obj my-metrics))
  (list :vega-lite
        (format nil "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",
                      \"data\":{\"values\":~A},
                      \"mark\":\"bar\",
                      \"encoding\":{\"x\":{\"field\":\"name\",\"type\":\"nominal\"},
                                    \"y\":{\"field\":\"value\",\"type\":\"quantitative\"}}}"
                (metrics-to-json obj))))

Supported visualization types:

• (:html string) - Render HTML in sandboxed iframe
• (:svg string) - Render SVG graphics
• (:json string) - Syntax-highlighted JSON
• (:vega-lite spec-string) - Render Vega-Lite chart
• (:mermaid definition-string) - Render Mermaid diagram
• (:image-base64 mime-type base64-string) - Image from base64 data

Return NIL from your method to fall back to ICL's built-in type detection.

See examples/vega.lisp for Vega-Lite visualization and examples/mermaid.lisp for Mermaid diagrams.

The ,explain command uses an AI CLI (auto-detected from PATH) to provide explanations of Lisp code, errors, and results. When using Gemini or Claude CLI, ICL provides an MCP server that gives the AI read-only access to the live Lisp environment - it can query documentation, describe symbols, and search for functions, but cannot execute any code.

Requires one of: Gemini CLI, Claude CLI, or Codex CLI

ICL maintains history of recent values and inputs:

ICL loads a config file on startup (unless --no-config is specified). This file can contain any Common Lisp code.

Config file locations:

• Linux/macOS: $XDG_CONFIG_HOME/icl/config.lisp (default: ~/.config/icl/config.lisp)
• Windows: %APPDATA%\icl\config.lisp

History file locations:

• Linux/macOS: $XDG_STATE_HOME/icl/history (default: ~/.local/state/icl/history)
• Windows: %LOCALAPPDATA%\icl\history

Use ,show-config to see the actual paths on your system.

Use configure-lisp to customize how ICL invokes a Lisp implementation:

(icl:configure-lisp impl &key program args eval-arg)

• :program - Path to the executable
• :args - List of command-line arguments
• :eval-arg - The eval flag (e.g., "--eval")

;; Use CCL instead of SBCL
(setf icl:*default-lisp* :ccl)

;; Custom SBCL with more memory
(icl:configure-lisp :sbcl
  :program "/opt/sbcl/bin/sbcl"
  :args '("--dynamic-space-size" "8192"))

;; Enable paredit mode
(setf icl:*paredit-mode* t)

;; Custom prompt
(setf icl:*prompt-string* "λ ~A> ")

;; Load commonly used systems
(asdf:load-system :alexandria)

;; Define custom utilities
(defun reload ()
  (asdf:load-system :my-project :force t))

Notes:

• In paredit mode, Enter only submits when the cursor is at the end of the buffer (allowing multi-line editing of balanced forms)
• Use Alt+Enter in gnome-terminal and most other terminals. Shift+Enter only works in terminals with kitty keyboard protocol support (kitty, WezTerm, Alacritty, etc.).

ICL aims to support multiple Common Lisp implementations. SBCL is the primary development and testing platform.

ICL operates as a frontend that communicates with a backend Lisp process via the Slynk protocol (from SLY). This architecture allows ICL to work with any Common Lisp implementation, provide consistent features regardless of backend, and connect to remote Lisp processes.

┌──────────────────────────────────┐   ┌──────────────────────────────────┐
│          USER TERMINAL           │   │          WEB BROWSER             │
│                                  │   │  ┌────────────────────────────┐  │
│  $ icl                           │   │  │  Packages │ Symbols │ Insp │  │
│  COMMON-LISP-USER> _             │   │  ├───────────┴─────────┴──────┤  │
│                                  │   │  │     xterm.js Terminal      │  │
│                                  │   │  │  COMMON-LISP-USER> _       │  │
└────────────────┬─────────────────┘   └──┼────────────────────────────┴──┘
                 │                        │
                 │ stdin/stdout           │ WebSocket + HTTP
                 │                        │ (localhost:random-port)
                 ▼                        ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                                 ICL                                     │
│                       (Interactive Common Lisp)                         │
│                                                                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │  Multiline  │  │   Command   │  │     Tab     │  │   History   │     │
│  │   Editor    │  │ Dispatcher  │  │ Completion  │  │   Manager   │     │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘     │
│                                                                         │
│  ┌───────────────────────────┐  ┌────────────────┐  ┌───────────────┐   │
│  │      Slynk Client         │  │ Browser Server │  │ MCP Server    │   │
│  │  (Backend Communication)  │  │  (Hunchentoot) │  │ (AI Tools)    │   │
│  └─────────────┬─────────────┘  └────────────────┘  └───────▲───────┘   │
└────────────────┼────────────────────────────────────────────┼───────────┘
                 │                                            │
                 │ Slynk Protocol                             │ HTTP (MCP)
                 │ (localhost:random-port)                    │
                 │                                            │
                 ▼                                            │
┌────────────────────────────────┐  ┌─────────────────────────┴───────────┐
│        INFERIOR LISP           │  │          AI CLI TOOLS               │
│       (Backend Process)        │  │                                     │
│                                │  │  ┌─────────┐ ┌────────┐ ┌────────┐  │
│  ┌──────────────────────────┐  │  │  │ Claude  │ │ Gemini │ │ Codex  │  │
│  │      Slynk Server        │  │  │  │   CLI   │ │  CLI   │ │  CLI   │  │
│  │                          │  │  │  └────┬────┘ └───┬────┘ └───┬────┘  │
│  │  • Evaluation            │  │  │       └──────────┼──────────┘       │
│  │  • Completion            │  │  │                  │                  │
│  │  • Xref                  │  │  │                  ▼                  │
│  │  • Inspection            │  │  │  ┌───────────────────────────────┐  │
│  │  • Macroexpansion        │  │  │  │    MCP Protocol Client        │  │
│  └──────────────────────────┘  │  │  │                               │  │
│                                │  │  │  Read-only tools:             │  │
│  ┌──────────────────────────┐  │  │  │  • get_documentation          │  │
│  │   User's Lisp Image      │  │  │  │  • describe_symbol            │  │
│  │                          │  │  │  │  • apropos_search             │  │
│  │  • Loaded libraries      │  │  │  │  • get_function_arglist       │  │
│  │  • User definitions      │  │  │  │  • get_repl_history           │  │
│  │  • REPL state            │  │  │  │  • list/read_project_files    │  │
│  └──────────────────────────┘  │  │  └───────────────────────────────┘  │
│                                │  │                                     │
│  SBCL │ CCL │ ECL │ ABCL │ ... │  │  AI cannot execute code             │
└────────────────────────────────┘  └─────────────────────────────────────┘

All connections use randomly-assigned ports on localhost. When ICL starts an inferior Lisp, it finds an available port and configures Slynk to listen there. The browser interface (started with ,browser or icl -b) serves a Dockview-based IDE with package browser, symbol list, inspector panels, and class hierarchy visualization. The browser automatically closes when ICL terminates. The MCP server (started on-demand by ,explain) provides read-only AI tool integration.

MIT License. See LICENSE file for details.

Anthony Green [email protected]