Hacking the SBCL REPL

Note to readers: This chapter is a work in progress. Additional topics will be added in future updates.

The SBCL REPL is already a powerful environment for interactive development, but Common Lisp’s extensibility lets us reshape it into something more. In this chapter we explore how to customize the SBCL REPL by modifying the ~/.sbclrc startup file, adding shell command execution, custom reader macros, and quality-of-life improvements that blur the line between a Lisp REPL and a Unix shell. The two customizations we implement are:

• Using #! to execute shell commands.
• Adding an AI coding agent that is always available in the REPL and instantiated with #?.

To achieve seamless, shell-like command execution in the SBCL REPL without requiring s-expression wrappers, the most idiomatic and robust mechanism is Common Lisp’s reader macros.

Instead of hacking the REPL’s top-level evaluation loop directly, we modify the readtable so that the reader itself intercepts special characters. Here is how the pieces fit together:

1. Interception — By binding #! as a dispatch macro character, the Lisp reader hands control to a custom function the moment it encounters the #! sequence.
2. Consumption — The macro function consumes the rest of the input line as a raw string, completely bypassing the standard Lisp parser for that line.
3. Evaluation — The macro returns a valid Lisp form (a function call) containing the parsed string. The REPL naturally evaluates this form.
4. Process Management — Shell commands like ls or grep are passed directly to the underlying OS shell using uiop:run-program.
5. State Mutation — Process-level state changes, specifically cd, cannot be delegated to a subshell because the subshell’s environment terminates immediately. The macro must trap cd, execute it internally using uiop:chdir, and update Lisp’s *default-pathname-defaults* to keep the Lisp environment in sync with the OS-level working directory.

Why #! instead of bare !? The exclamation mark is a valid constituent character in Common Lisp symbols. Libraries like cl-json use symbols such as run! internally. A bare ! reader macro hijacks this character globally — when SBCL loads any .asd file or source file containing ! in a symbol name, the reader macro fires, consumes the rest of the line as a shell command, and leaves the reader with unbalanced parentheses. Using #! (a dispatch macro on #) avoids this entirely because # is already reserved as a dispatching macro character and never appears as part of a symbol name.

Add the following code to the end of your ~/.sbclrc file. It requires ASDF (which ships with SBCL) for access to UIOP’s process and filesystem utilities:

The run-shell-command function is the workhorse. It takes a single string argument — the raw text after the #! sequence — and dispatches it:

• Empty input — returns immediately with no values.
• cd command — handled internally. A cd executed in a subshell would change that subshell’s directory, then immediately exit — leaving the parent Lisp process unchanged. Instead, we call uiop:chdir to change the OS-level working directory and update *default-pathname-defaults* so that subsequent Lisp file operations (like (load "foo.lisp")) resolve relative to the new directory.
• Everything else — delegated to the OS shell via uiop:run-program. The :output :string and :error-output :string keyword arguments capture both stdout and stderr as strings. We then print them explicitly with princ (which omits quotation marks, unlike print or format ~S) and call force-output to flush the stream immediately.

The :ignore-error-status t argument prevents uiop:run-program from signaling a condition on non-zero exit codes — important for commands like grep that return exit code 1 when no matches are found.

The bang-reader function is installed as a dispatch reader macro for the #! character sequence. When the Lisp reader encounters #!, it calls this function with three arguments: the input stream, the dispatch character (#), and the sub-character (!). We declare both character arguments as ignored since we only need the stream.

Rather than using read-line (which would consume the newline and potentially confuse the REPL’s line tracking), the function uses peek-char in a loop to read characters one at a time until it hits a newline or end-of-file. This leaves the newline in the stream for the REPL to consume normally.

The function returns a backquoted form:

This is a valid Lisp form that the REPL’s evaluator processes normally — calling run-shell-command with the captured string as its argument.

The final line installs the dispatch macro:

After this executes (at SBCL startup, via ~/.sbclrc), any #! sequence at the REPL is intercepted before the standard Lisp reader ever sees the rest of the line. Unlike a bare ! reader macro, this approach is safe — it cannot interfere with symbol names containing exclamation marks, because # is already reserved as a non-constituent dispatching prefix.

After adding this code to ~/.sbclrc and restarting SBCL:

Notice that normal Lisp expressions still work exactly as before. The #! macro only activates when #! appears in the input. You can freely alternate between shell commands and Lisp expressions within the same REPL session.

The #! reader macro from the previous section gave us shell access from the REPL. In this section we go further by integrating an AI coding agent directly into the REPL so we can ask questions, diagnose errors, and generate code without leaving SBCL.

The cl-ai-coding-agent package (developed in the chapter “Building an AI Coding Assistant for Common Lisp”) provides a function coding-agent-query that takes a string prompt and returns the agent’s response. The agent can autonomously list directories, read files, write new files, and diagnose stacktraces, using litelm’s OpenAI-compatible tool-calling protocol. Its default model is the local ollama/qwen3.5:4b, so nothing in this section needs an API key. But calling it directly requires quoting strings:

This syntactic friction slows down the interactive workflow. We want three levels of integration:

1. An ai macro — eliminates string quoting by stringifying unevaluated symbols, so we can type natural language as Lisp forms.
2. A #? reader macro — captures an entire line as a prompt, matching the #! pattern from the shell integration.
3. Automatic error interception — an ai-diagnose-error function that turns a condition into a prompt, wired into *debugger-hook* so an unhandled error is diagnosed before the normal debugger appears.

Add the following code to your ~/.sbclrc file, after the shell integration code from the previous section. It registers the two local systems exactly as the previous chapter’s Installation section describes, then loads the agent on startup. Set *book-src* to your checkout’s src directory:

The ai macro accepts unquoted natural language tokens and concatenates them into a prompt string at macro-expansion time:

expands to:

The prompt arrives down-cased because the reader has already up-cased every symbol: the macro receives WRITE, A, QUICKSORT and FUNCTION, and ~A would print them exactly that way, so the macro applies string-downcase before handing the string to the agent.

The (values) suppresses the return value to keep the REPL output clean — we only want to see the agent’s printed response, not a redundant return string. Because the macro stringifies symbols, any valid Lisp identifier characters work: letters, digits, hyphens. However, characters that the Lisp reader treats specially — parentheses, commas, quotes, semicolons — will cause read errors. For prompts that need those characters, use coding-agent-query with an explicit string, or the #? reader macro.

The #? dispatch macro works identically to #! but routes to the AI agent instead of the shell:

Like #!, it consumes the rest of the input line as a raw string, bypassing the Lisp reader entirely. This means any characters — including parentheses, quotes, and semicolons — are treated as plain text. This makes #? ideal for pasting error messages or asking questions that contain Lisp syntax.

Stacktraces often contain double-quote characters and span multiple lines, making them awkward to paste into a Lisp string literal. The coding-agent-query-file function reads the contents of a file and sends them as the prompt:

The third integration point is the one you never type yourself. ai-diagnose-error takes any condition object, formats it into a string with ~A, and hands that string to the agent — the same route a pasted stacktrace takes, so the agent’s stacktrace instructions apply automatically.

On its own that function is no more convenient than #?, because you have to be sitting in the debugger to call it. The *debugger-hook* assignment at the end of the code block is what makes it pay off: every unhandled error is diagnosed before the normal debugger takes over, so instead of reading a backtrace you get a plain-English explanation and a suggested fix, and then the ordinary debugger appears as usual.

Two details make it safe to leave switched on. *debugger-hook* is bound to NIL while the hook runs, so if ai-diagnose-error itself signals — an API timeout, say — the failure cannot recurse into the hook. And the hook calls invoke-debugger afterwards rather than swallowing the condition, so you keep the normal debugger and its restarts; the diagnosis is an addition, not a replacement.

Because the agent is a network call, every unhandled error now costs a round trip before you see the debugger. If that becomes tiresome during a long debugging session, remove the setf and call ai-diagnose-error by hand only when you want it.

After adding the integration code to ~/.sbclrc and restarting SBCL:

Notice how all integration levels coexist. The ai macro handles simple natural-language queries, #? handles anything with special characters, #! still works for shell commands, and Standard Lisp expressions continue to work normally.

-# Part 8: macOS Specific Code Experiments

Not everything I write is portable, and this part is where the macOS-only code lives. The first chapter builds native desktop applications with Common Lisp, CFFI, Cocoa, and WebKit: real windows, HTML and CSS user interfaces, and a two-way bridge between Lisp and JavaScript. More experiments that lean on Apple’s frameworks and Apple Silicon will be added here as I write them up.