Building an AI Coding Assistant for Common Lisp

Earlier chapters built the pieces this one assembles: the litelm chapter introduced the provider-neutral model client, and the previous chapter wrapped a persistent SQLite cache in a small Common Lisp API.

In this chapter we build cl-ai-coding-agent, a focused coding assistant that uses litelm. The library speaks the OpenAI-compatible tool-calling protocol shared by many providers: we declare tools in a plain Lisp list format, the model returns typed tool-call requests, and our agent loop dispatches them directly. This eliminates the fragile JSON parsing layer entirely and lets the model decide autonomously when to inspect directories, read source files, write new files, or simply answer a question.

Because litelm routes calls by a "provider/model" string, the same agent code works with OpenAI, Gemini, Fireworks AI, DeepSeek, or a local Ollama server. The default model is the local Ollama model qwen3.5:4b, so the examples in this chapter run without any API key. Later in the Hacking the SBCL REPL chapter we integrate the agent further with reader macros (#?) and automatic error interception so the agent is always one keystroke away.

The agent follows a simple multi-round loop built on litelm:completion:

1. Prompt augmentation: The user’s input is paired with a system message that describes the available tools. If the input looks like a stacktrace, additional diagnostic instructions are injected into the system message.
2. Round 1: The message list and tool declarations are sent to the model via litelm:completion. The model returns either a text response (no tools needed) or a list of tool-call requests.
3. Tool dispatch: Each tool call is executed locally. The agent can list directories, read files, and write files.
4. Round 2+: The assistant’s tool calls and the tool results are appended to the message history, and the updated history is sent back to the model. The model may request more tool calls (for example, read a file after listing a directory) or return a final text response.
5. Termination: The loop repeats for up to 10 rounds, then returns whatever text the model has produced.

Here, the OpenAI-compatible tool-calling protocol in the library litelm handles the structure, so we never parse JSON tool invocations ourselves. The model’s tool-call requests arrive as typed plists, and our tool results go back into the message history in the same Lisp format. This is both more reliable and simpler to implement.

The project has three source files plus an ASDF system definition:

Its direct dependencies are the litelm library (developed in the litelm chapter, in the sibling directory ../litelm) and UIOP (which ships with ASDF). litelm itself brings in dexador, cl-json and alexandria, so those must be reachable on the Quicklisp path.

The package exports six symbols: two query functions, an interactive REPL, a debug flag, and two configuration parameters:

The agent has three tools, each consisting of a local implementation function and a corresponding litelm tool definition.

Each tool returns a string. This is important because tool results travel back to the model as text messages, so even tool-list-directory and tool-write-file produce human-readable string output rather than structured data.

The tool-list-directory function filters out hidden files (names starting with .), Emacs backup files (ending with ~), and Emacs auto-save files (starting with #). The truename call canonicalises the directory first, and enough-namestring then strips that prefix so the output is clean relative names rather than full absolute paths. The truename is doing real work here: leave the directory as a relative pathname such as ./ and enough-namestring cannot relativise the absolute names that directory-files returns, so the model receives full paths after all. It also turns a misspelled directory into an error the model can see, rather than letting it look like an empty folder.

The tool-write-file function calls ensure-directories-exist before writing, so the model can create files in new subdirectories without a separate mkdir step.

Each tool needs a corresponding definition that tells the model the function’s name, description, and parameters. The litelm library uses a plain Lisp format: each tool is a list of (name description ((param-name param-type param-description) ...)).

There is no JSON anywhere in our code: litelm translates these Lisp lists into the wire format expected by whichever provider the model string selects. Parameters are required by default, so the model knows it must supply both path and content when calling write_file.

When the model requests a tool call, litelm returns a plist with :ID, :NAME, and :ARGUMENTS. The dispatch function routes each call to the correct local function:

The :ARGUMENTS value is a decoded alist, for example ((:path . "/tmp/test.lisp")), so the get-arg lambda uses assoc with :test #'string-equal to handle case variations. The outer handler-case catches tool errors (like missing files) and returns them as strings rather than signaling conditions that would break the agent loop. This is crucial: if a file does not exist, we want the model to see the error message and either try a different approach or explain the problem to the user.

Before constructing the system message, the agent checks whether the user’s input contains a stacktrace or error message. If it does, additional instructions are injected to guide the model toward root-cause analysis:

The patterns cover SBCL conditions (UNDEFINED-FUNCTION, TYPE-ERROR, debugger invoked), Python tracebacks (Traceback (most recent call last)), and Java or generic stack traces (Exception in thread, Stack trace:). The char-equal test makes the search case-insensitive. Every pattern is matched with search, so they are literal substrings rather than regular expressions — one written as a regex would simply never match, and would sit in the list looking useful. Detection is heuristic: it can fire on benign input containing the word Error:, but a false positive is harmless, since the extra instructions only add diagnostic guidance without changing the agent’s capabilities.

The system message establishes the agent’s persona and informs it about available tools:

Note that %system-instructions builds only the system message. The user’s input travels as a separate :user entry in the message list, which matches the chat message format that litelm expects.

The system message explicitly instructs the model to use write_file when creating files rather than just printing code. Without this instruction, models tend to respond with code blocks in their text output, which is useful for a chatbot but unhelpful when you want the agent to actually create the file on disk.

The stacktrace instructions include a restraint: “Only use file-system tools if you genuinely need to see source code context.” This prevents the model from reflexively reading every file in the project when the error message alone provides enough information for a diagnosis.

The coding-agent-query function is the primary entry point. It maintains one message list and calls litelm:completion once per round:

The key design decisions here:

• One growing message list: Each round appends an :assistant message carrying the model’s :tool-calls, followed by one :tool message per call carrying the result string and the :tool-call-id. Because litelm owns the wire translation, this same history works with every provider.
• Early return: If a round produces text with no tool calls, the agent returns immediately. Most simple questions (“What does defmethod do?”) are answered in a single round.
• Mapcar over calls: All tool calls from a single round are executed before the next completion request. Models sometimes request multiple calls in one round (for example, reading two files at once), and processing them all at once is more efficient than sequential round-trips.
• Round limit: The *max-tool-rounds* parameter (default 10) prevents runaway loops. In practice, most interactions complete in 1 to 3 rounds: list directory, read file, respond.
• Model selection: The :model keyword accepts any litelm "provider/model" string, so switching from the local default to gemini/gemini-2.5-flash or openai/gpt-4o is a one-word change.
• Verbose mode: Setting *verbose* to t prints every message list, tool call, and response. The debug output truncates tool results to 200 characters to keep the output manageable.

Stacktraces and error messages are often multi-line and contain double-quote characters, making them painful to paste into a Lisp string literal. The coding-agent-query-file function solves this by reading the prompt from a file:

The typical workflow: copy a stacktrace to the clipboard, save it to a file (pbpaste > /tmp/error.txt on macOS), and call (coding-agent-query-file "/tmp/error.txt").

For extended sessions, the agent provides its own REPL loop:

The handler-case around coding-agent-query ensures that API errors, network timeouts, and other failures produce a message rather than dropping into the SBCL debugger. This matters for a tool you use throughout the day, since you do not want to lose your REPL state because of a transient network issue.

The agent depends on the litelm library, which lives in the sibling directory ../litelm. Load both system definitions and quickload the agent:

Replace /path/to with the checkout’s src directory — src/litelm/litelm.asd and src/cl-ai-coding-agent/cl-ai-coding-agent.asd in this repository.

The default model runs locally under Ollama, so no API key is needed. Pull the model once from your terminal:

To use a hosted provider instead, pass a different :model string and set the corresponding API key environment variable (for example GEMINI_API_KEY for gemini/ models), as described in the litelm chapter.

The following session demonstrates the agent’s multi-round tool use. The user asks the agent to describe the Lisp files in a directory, and the agent lists the directory, reads each file, then summarizes them:

Behind the scenes, this query triggered three tool-use rounds:

1. Round 1: The model called list_directory with path "." and received the file listing.
2. Round 2: The model called read_file three times (once per .lisp file) to read their contents.
3. Round 3: The model produced the final text summary.

1. Native tool calling over JSON parsing: litelm implements the OpenAI-compatible tool-calling protocol shared by many providers. By declaring tools as plain Lisp lists and dispatching the model’s typed plist requests directly, we avoid the brittleness of parsing free-form JSON from model output.

2. Provider independence: Because the agent loop only calls litelm:completion, the entire library works unchanged against OpenAI, Gemini, Fireworks AI, DeepSeek, or a local Ollama server. The default ollama/qwen3.5:4b model needs no API key.

3. Returning errors as strings: Wrapping tool dispatch in handler-case and returning error messages as strings (rather than signaling conditions) keeps the agent loop running. The model can see the error and adapt, for example by trying a different file path.

4. Stacktrace-aware prompting: Detecting error patterns in the input and injecting diagnostic instructions produces better root-cause analysis. The restraint instruction (“only use tools if you genuinely need context”) prevents unnecessary file reads.

5. File-based input for awkward text: The coding-agent-query-file function sidesteps the quoting problem inherent in pasting multi-line, quote-heavy stacktraces into Lisp string literals.

6. Composition with the REPL: This library is designed to be loaded into ~/.sbclrc and used alongside normal Lisp development. The Hacking the SBCL REPL chapter shows how to integrate it with #? reader macros and automatic error interception for a seamless coding experience.

You can use this example in building your own coding environment. In the chapter Hacking the SBCL REPL we’ll see how to use this agent in an interactive SBCL REPL.

1. Add a grep_files Tool: The agent can list directories and read files, but it has no way to search for text across multiple files. Add a fourth tool grep_files that accepts a pattern string and a directory string, uses uiop:run-program to call the system grep command (e.g., grep -rnl pattern directory), and returns matching filenames and line numbers as a string. Write the corresponding litelm tool definition in %make-tool-declarations, add a dispatch clause in dispatch-tool-call, and test it by asking the agent “Find all files that reference defmethod in this directory.”

2. Extend Stacktrace Detection: The current stacktrace-p function uses simple substring matching via search. Extend it to also recognize Clojure stacktraces (patterns like clojure.lang.ExceptionInfo, at clojure.core), Rust panics (thread 'main' panicked at), and Go panics (goroutine 1 [running]). Then write a function classify-error-type that returns a keyword (:sbcl, :python, :java, :clojure, :rust, :go, or :unknown) based on which patterns match, and modify %system-instructions to inject language-specific diagnostic instructions depending on the classification.

3. Conversation Logger: The agent currently discards all intermediate tool calls and responses after the session ends. Write a logging layer that wraps coding-agent-query: before each query, open (or create) a log file agent-log.jsonl and append a JSON object for each event: the initial prompt, each tool call (name and arguments), each tool response, and the final answer. Use litelm:json-encode to serialize each entry. This provides an audit trail and lets you replay sessions later.

4. Safety Sandbox: The tool-write-file function can write to any path, including system files. Write a wrapper function sandboxed-write-file that accepts a list of allowed directory prefixes (e.g., ("/tmp/" "/home/user/projects/")) and checks that the resolved absolute path of the target file starts with one of the allowed prefixes before writing. If the path is outside the sandbox, return an error string instead of writing. Integrate this into dispatch-tool-call so that write operations are always sandboxed. Discuss why probe-file alone is insufficient for this check (hint: symlinks).

5. Batch File Reviewer: Write a function review-project that takes a directory path, uses tool-list-directory to discover all .lisp files, then calls coding-agent-query once with a prompt that includes the contents of every file (read via tool-read-file) and asks the agent to review the code for style issues, potential bugs, and missing documentation. Be mindful of context window limits: estimate the prompt size before sending (a rough heuristic is four characters per token), and if it exceeds a threshold (e.g., 100,000 estimated tokens), split the files into batches and make multiple queries.

6. Token-Aware Agent Loop: The current agent loop has a round limit (*max-tool-rounds*) but no token budget. Modify coding-agent-query to accept an optional :max-tokens keyword parameter. After each call to litelm:completion, inspect litelm:response-usage, which returns a plist (:prompt-tokens n :completion-tokens n :total-tokens n), and check the :total-tokens value against :max-tokens. If the budget is exceeded, return early with a note that the token budget ran out, or truncate the oldest tool responses from the message history and continue. This teaches you about managing context windows in multi-round LLM interactions.