Autolith

The Common Lisp agent that rewrites itself and rocks.

A self-modifying terminal programming agent inside a live image it can inspect, edit, break & recover, and shape to fit any use case.

nix run github:lambda-symbolics/autolith
Read the docs

Linux, macOS, FreeBSD, NetBSD, OpenBSD, and Windows. See more.

The whole agent is one Common Lisp image.

Autolith manages MCP connections, memories, tools, agendas, and language servers in one Lisp runtime. Some might say it's a monolith.

Common Lisp provides describe, conditions, restarts, CLOS protocols, and source forms at runtime. The agent uses them to inspect and change its own implementation.

File search uses the fff Rust library. Autolith can spawn and maintain persistent Lisp workers for experiments and scripts.

The Autolith rock formation
provider
clientterminal
interfacetool
registryMCP
connectionsconversation
storepersistent
memoriesworkspace
agendamutation
journalwhat happens
next

In your repository

Repository work
Read and edit files, run commands, and search your project. Connect a language server for diagnostics, renames, and code actions.
Unattended jobs
Run Autolith inside your workflows in headless mode. Supply input and output schemas and stream S-expression events while it works.

In its image

Live Lisp
A runtime it can inspect, test, and extend, with heap-isolated workers for experiments. The bedrock for trying a change before installing it in the active agent.
Oversized context
Use recursive inference to divide material too large for one model context.
Continuity
Portable conversations, memories, agendas, checkpoints. If Autolith breaks itself, it can recover via its recovery image.

The input prompt is a REPL with syntactic sugar.

The sentence "Hello Autolith! What's your favorite rock?" is read as the Lisp form (prompt :to 'autolith "Hello Autolith! What's your favorite rock?")

Prose, typed at the prompt. Autolith reads it as a call to (prompt). Talk to a specific agent using the :to parameter.

Your messages are just calls to (prompt ...)

Try the reader below to see how a message becomes a Lisp form. This is a syntax demonstration, not a running agent. In Autolith, use :to to address a child agent.

The reader

Read as a call to (prompt), addressed to the primary agent.

You don't need to know Lisp.

Plain text works, and most people never need to type a Lisp form.

If you want to learn Lisp, start at the prompt. The agent sees the form you entered, its result, and any signaled condition, so you can ask it to explain an error.

Prompts can be computed.

Text, commands, tool calls, and Lisp forms share one input prompt. A Lisp form runs in the Autolith image, and the agent sees its result. Read a prompt from disk, fill in a template, or generate it from the program you are debugging.

;; a computed prompt
(prompt (read-file "review-notes.org"))

;; a tool, called by hand
(resource.read :uri "workspace:.")

;; introspection, right there
(describe 'application)

And you can steer any child in the tree.

Autolith keeps working while its children run. Talk to one to correct it while it's doing something. Its next text reply comes back to your terminal.

(prompt :to 'test-review
        "Run the focused tests and
         report only failures.")

Update the running agent without restarting it.

Autolith replaces complete functions, methods, classes, macros, conditions, and global settings in its image at runtime. The change is instantly live.

You decide which changes to persist. Trial changes last only for the current process unless you commit them.

Figure 2. Autolith mutations.

self.redefine journals a complete definition before compiling and installing it in the image.

self.exercise runs assertions against a pending change to check its behavior.

self.diff lets Autolith review all pending changes.

self.discard restores the definitions or settings from before an unwanted trial change.

self.commit persists pending changes as a replay script in Autolith's private Git history, after checking the replay in a clean process. Your modified agent can then be rebuilt from source and that script.

After an update, overrides whose tracked source has moved on are skipped instead of silently replacing new code, and (fix-skipped-definitions) asks Autolith to rebuild them against the current source.

Figure 3. When Autolith crashes.

If Autolith breaks:

If you or Autolith somehow manage to crash the process, it will write a crash capsule, boot a separately built pristine image, and select a known-working generation from it.

Autolith restores the conversation and starts a read-only diagnosis turn to investigate the crash.

You decide whether to attempt a repair.

Note: Many Lisp errors can be handled through the debugger without ending the process. You and the model can inspect the condition and choose an available restart.

Figure 1. RLM partitioning

Work beyond the context window.

Every model has a hard limit on how much it can read at once.

For a log, codebase, or folder of documents too large to fit, Autolith can divide the material among recursive inference calls and combine their answers. The full input stays outside the main conversation.

The approach comes from Recursive Language Models, by Alex L. Zhang, Tim Kraska, and Omar Khattab. Autolith is a compromise between a traditional agent and Prime Agent (which also rocks, by the way!): a conventional agent with RLM tools it can use when needed.

It writes small programs to search and slice the material, sends selected parts to separate model conversations, and combines the answers. Those conversations can split their own work further.

Each run has limits on calls, tokens, and recursion depth. If it reaches a limit, its retained context and trace are available for follow-up work; the answer may be incomplete.

Example budget
32 calls, 400 000 tokens, depth 2
Corpus
3.1 MB, 121 src/*.lisp files
Root conversation
59.6 K tokens in, 915 out
Answer
83 condition classes across 14 subsystems, each with its file
Trace
inference:s2Wb1o2, which the agent can read like any other resource.

Example recorded sessions.

  :::.      :::        AUTOLITH v0.67.5
  ;;`;;     ;;;        ───────────────────────────────────────
 ,[[ '[[,   [[[        model         gpt-6.1-sol (effort high)
c$$$cc$$$c  $$'        workspace     /root/demo/autolith/
 888   888,o88oo,.__
 YMM   ""` """"YUMMM
Download recording
Asked
List every condition class in a 3.7 MB concatenation of 201 source files, grouped by subsystem, with the defining file. Budget of 32 calls, 400 000 tokens, depth 2. Do not read or search the file directly.
Cost
23 of 32 calls and 316.4 K tokens inside the run. The root conversation holds 18 K tokens of context; selected corpus slices enter separate inference calls.
Answer
All 98 condition classes across 19 subsystems, each with its defining file.

Attach to a session from another terminal.

Every Autolith instance has an authenticated local endpoint on loopback, keyed by the session ID. You can (detach), and Autolith will continue your work in the background.

From any other terminal on the machine

$ autolith localgroup status
$ autolith localgroup tell   SESSION "use the staging config"
$ autolith localgroup attach SESSION --read-only
$ autolith localgroup attach SESSION --take-over
$ autolith localgroup pause  SESSION
$ autolith localgroup kill   SESSION

Use these commands to inspect, steer, or attach to running sessions. An opt-in management REPL gives authenticated clients direct Lisp access to the running image. Enable it only for clients you trust.

Editors can drive the same sessions over the Agent Client Protocol: point your editor at autolith acp and it gets streamed answers, reasoning, tool activity, approvals, steering, durable follow-ups, and job control.

We considered naming it after a rock formation, but none sounded right. Old Windows NT terminology it is.

You can also move your work between machines.

$ autolith data export project.sexp --workspace ~/code/project
$ autolith data import project.sexp --workspace ~/src/project

Export writes an S-expression archive of conversations, memories, agendas, plans, papercuts, and other session assets. Import it into the target workspace to continue there.

Rebuild a self-modified agent on another supported machine from source and its private replay script; a saved core itself is platform-specific.

  • Linux x86_64
  • Linux aarch64
  • musl static
  • macOS x86_64
  • macOS arm64
  • FreeBSD
  • NetBSD
  • OpenBSD
  • Windows x86_64

Give it a mission, not just a prompt.

Long-running work gets acceptance criteria you write, verification gates the harness runs, and hard limits on turns, tokens, and wall-clock time. The model can ask to be verified. Only the evidence can say yes.

Criteria
You write the acceptance criteria. The model cannot weaken them, and a criterion without a gate needs your explicit evidence before the mission can pass.
Gates
Command, artifact, and Lisp gates run in order, each with its own timeout and attempt limit. Deterministic gates fingerprint their input files, so an unchanged pass stays proven and an unchanged failure is not run again.
Budgets
One allowance covers the primary agent, its children, compaction, and recursive inference. Every request reserves its output ceiling before it starts, so parallel children cannot overspend, and prompt-cache reads are not counted.
Reviews
Attach an independent reviewer with its own snapshot, its own allowance, and no tools. Pending findings block acceptance, and an unchanged snapshot is never reviewed twice.
Schedules
Wake a mission at a time, on an interval, or on an external event. Due work enters the ordinary command queue under the same budgets.
Durability
Gate attempts, fingerprints, evidence, and spend restore with the conversation and survive compaction, independently of anything the model summarized.

For lighter work, (goal "…") sets an objective without the ceremony. Start a mission with (mission "start …") and watch it with (mission "status").

(mission "status")

Deliver the accepted build

turns26 / 40
tokens61,200 / 100,000
wall clock41 / 60 min
  1. buildcommand
  2. testslisp, attempt 2 of 3
  3. bundleartifact sha256
  4. reviewyour evidence

spentreserved

verified

Delegate into isolated worktrees.

Children edit and test in their own Git checkouts, report back in one standard shape, and wake the primary turn when they finish. Nobody sits there polling.

Figure 4. Parallel children, deliberate integration.

Give task.run an isolation object and the child works in a detached worktree at an exact baseline. It returns an engineering artifact: a patch or commit range with the paths it touched, the checks it ran, the evidence, open issues, and integration notes.

The parent checks each artifact against the target and applies them in the order it chooses, resolving conflicts on purpose instead of by accident.

After a restart, retained work is sorted into live, completed, safe to restart, or needing a decision. Autolith asks before it repeats anything with side effects.

(tasks)
A live inventory of owned work with lineage, timing, usage, and artifacts. Read a child's transcript, send it a correction, or cancel it.
Engineering role
The bundled engineering role returns the artifact contract, and your own roles can extend it with extra required fields.
Semantic edits
lsp.semantic turns a language server's rename, code action, or file move into one retained proposal. Applying it checks every file's revision and rolls the whole set back if anything fails.
Structural rewrites
Optional ast-grep queries and rewrites, previewed first and published under the same stale-revision checks as every other edit.
Peer messages
Grant one agent a durable, one-way channel to another, even across sessions. Messages are coordination data and never carry extra authority.
Debugger
Optional Debug Adapter Protocol sessions: launch or attach, set breakpoints, step, and inspect variables, each behind exact approval.

Facts with receipts, rules that keep up.

Alongside prose memories, Autolith keeps structured facts with their sources and basis. Rules derive facts locally, contracts check tool requirements before execution, and repeated tool sequences can become procedures.

memory:facts · rule departure v1

  1. event.startreview14:30your statement
  2. event.travelreview25 minobservation
  3. event.bufferreview15 minyour statement

?leave = ?start - (?travel + ?buffer)

  1. event.departurereview13:50derived

model requests 0

recomputed locally

Figure 5. The meeting moves; the departure follows without a model request.

A fact's basis follows its source. A file Autolith read is an observation; your words are a user assertion. Derived facts inherit the basis of their premises, so an assumption cannot become an observation through reasoning. Conflicting facts are both kept and marked as disputed.

Evidence
Files, pages, tool results, missions, or your own words. Web pages expire a week after retrieval, and file evidence holds only for the exact content observed.
Rules
Dates, durations, numbers, and quantities in units. A rule the model proposes derives nothing until you admit it, and a search that runs out of budget reports unknown, never false.
Contracts
A matching contract refuses a call whose required facts do not hold and explains why. After a successful call, its declared observation mappings turn selected JSON result fields, including MCP results, into observed facts.
Plans, gates
Plan steps can name required facts and use their current values. Fact-based mission gates accept undisputed observations or your statements, not the model's predictions.
Recipes
Starter vocabularies for appointments and service dependencies define their predicates and propose their rules in one operation.
(why)
(why "c4df") shows a fact's sources, rule, and premises; (what-changed) lists what moved since you last asked, with the cause.

procedure make-sales-report

  1. Make the sales report for q2.sales.loadsales.reportnotify.send
  2. Make the sales report for q3.sales.loadsales.reportnotify.send
  3. Make the sales report for q4.sales.loadsales.reportnotify.send

@ learned procedure make-sales-report from 3 turns

Make the sales report for q5.

@ learned procedure make-sales-report fits this request

procedure.run make-sales-report {"file":"q5"}sales.loadsales.reportnotify.send

calls chosen by the model 1

learned from 3 turns

Figure 6. Three turns making the same calls become one call.

When three turns repeat a matching tool sequence, Autolith can learn a procedure without a model request. Varying values become parameters matched to the changing words in your requests. For a later matching request, the agent receives a notice to use procedure.run. Each call inside it goes through its own approval checks.

diagnosis.run remote-service

  • unavailable
  • credentials
  • stale-endpoint
  1. service.ping {"service":"billing"}service.reachable(billing, true)rules out unavailable
  2. service.config {"service":"billing"}endpoint.current(billing, false)rules out credentials

stale-endpoint. Repair: update its endpoint.

model requests between probes 0

cause found

Figure 7. Each probe rules a hypothesis out; nothing is guessed.

Before trying repairs, diagnosis.run takes up to four hypotheses and probes that distinguish them. It ranks probes by how well they separate the remaining hypotheses relative to their cost, then runs up to three without another model request. If the probes cannot settle the case, it reports it as open.

Spend tokens on the work, not the bookkeeping.

Autolith avoids polling for finished jobs and keeps bulky command output outside the model context. Fewer requests and smaller previews leave more of the token budget for the work.

Waiting on a background job
polling5 requests
Autolith1 request

Illustration: each block is a provider request carrying the conversation context. A completion notice wakes the agent without polling.

One noisy command, in context
inline (v0.50)65,536 characters
retained-log preview6,000 bytes, the rest in a shell log

Illustrative output sizes. Captured output stays in a retained log that the model can page or search without rerunning the command. Capture and retention limits apply.

Jobs wake the agent
Shell, Lisp, RLM, skill, and task work that outlives a ten-second grace period is handed off, not rerun. The finished job continues the turn with a bounded notice, and completions that land together share one turn.
Logs, not dumps
Command output is retained behind a shell-log: reference, subject to capture and retention limits. The model sees a preview of up to 6,000 bytes, weighted toward the tail, and pages or searches the retained output on demand.
Many steps, one call
lisp.eval runs a sequence of forms, and with host tools a Lisp program can call agent tools and branch on their results inside one evaluation. Executable skills turn repeated procedures into tested code.
One edit, many files
A language-server rename or code action arrives as one proposal instead of a file-by-file edit loop, and it lands atomically or not at all.
Compaction keeps the work
Unfinished tool calls, running jobs, and steering that arrives mid-summary carry across compaction. The complete history stays searchable through conversation: resources, so old details are fetched instead of carried.
Partial results are kept
Recursive inference retains its context and trace when the budget runs out. The agent can inspect completed work before deciding how to continue.
Advice only when relevant
Context rules attach guidance only for matching paths, languages, tools, or roles, as ephemeral notes that erode instead of riding along on every request.
Spend guards
Retries after streamed output and repeated tool calls have limits. Exhausted subscription quotas fail at once. Loaded tool definitions are replayed intact to preserve the cacheable prompt prefix.

Sandboxing and security.

Commands go through authorization before execution.

Process isolation and scoped filesystem access limit accidental damage. This is not a security boundary for hostile code.

Sandbox
cl-exec-sandbox provides sandboxing on Linux, macOS, and Windows.

By default, commands have no network access, read-only host access, write access to the workspace and temporary directories, and a sixty-second timeout. Repository metadata is protected from writes.

On Linux it adds process, user, IPC, UTS, and network namespaces, no_new_privs, and seccomp.
Classification
In automatic mode one RLM inference frame judges each command under a two-call, eight-thousand-token budget and answers: sandboxed, full access, or denied.
Approvals
For each command, choose approve once, run sandboxed, full access, or deny. Headless jobs deny commands that would require an interactive decision, so choose their permission policy before starting them.
Credentials
Autolith redacts known credential fields in selected output paths, including MCP and OAuth credentials. Avoid putting secrets in prompts, source, or tool output.
Bounds
Configurable limits bound retries, repeated tool calls, and inference budgets.
Revision gating
File edits require an observed revision. If the file changes after it was read, Autolith refuses the stale edit. Line hashes help check that an edit targets the intended text.
Immutable mode
--immutable disables live self-modification operations.

Use it for a worker embedded in another program, or whenever you want to keep the running implementation fixed.

What Autolith remembers

Conversations, memories, agendas, and plans serve different purposes. Replay scripts and saved images preserve changes to the agent itself.

Conversations

An append-only, portable S-expression record of messages, tool activity, and runtime events, including errors and crashes.

Memories

Notes recalled for the current workspace, plus global notes shared across workspaces.

Agenda

Long-term commitments, blockers, and decisions. Think of a small Kanban board shared across sessions.

Plan

A short-term checklist for the current task, with progress recorded as the agent works.

Git image commits

Complete replay scripts for durable definitions and settings.

Generations

We stole this from Nix. A generation pairs a saved Lisp core with the metadata needed to select and restore that version of the agent.

Worker images

AL runs programs and experiments in heap-isolated Lisp workers. Save a useful worker image and restore it for later work.

Stores are append-only or transactional. Writes to shared state are serialized across processes, so multiple AL instances can use the same workspace.

Change anything about AL from the prompt.

Configure AL through files or Lisp forms, with help from the running agent.

Skills
Use standard SKILL.md files with frontmatter, or the native SKILL.sexp format. Native skills can load modifications into the AL image, so review them before use.

Project skills take precedence over user skills with the same name. AL also finds skills in the shared ~/.agents/skills directory. Executable skills run tested Lisp workflows in a disposable worker.
MCP servers
Connect MCP servers over stdio or Streamable HTTP, with a per-server approval policy. Project-defined servers load when the project is marked trusted in directory-scopes.sexp.
Child roles
Seven predefined child roles are available: scout, designer, reviewer, librarian, task, engineering, sonic (GOTTA GO FAST). You can add your own to .autolith/agents/ and choose each role's tools, model, and reasoning effort.
Providers
Ten providers are built in, including GitHub Copilot subscriptions. You can configure additional OpenAI-compatible endpoints.
init.lisp
Load Lisp code at startup to set defaults, add commands, or modify the agent.
Request context
define-context-contributor adds temporary context to provider requests. These ephemeral notes erode as they age, without rewriting the conversation history. Context rules add guidance only when a path, language, tool, or role matches.
Commands
define-application-command defines a command as a Common Lisp function with metadata for help and completion. Test it by hand or ask AL to help debug it. Add small commands like pebbles on a beach.
Instructions
AGENTS.md supplies project instructions. AL can also create AUTOLITH.org for project-specific adaptations that other agents do not need to load.
Settings
Settings have types and documentation. (settings) opens a grouped page where you change values in place, and (setf (config :model) ...) does the same from Lisp.
Help
(help) gives a compact overview by topic, and (help "resource.edit") explains any command, operation, or tool from its live schema.

Install it.

nix run github:lambda-symbolics/autolith

The high testosterone, high estrogen way to install Autolith.

Then sign in to a provider

autolith auth anthropic autolith auth chatgpt autolith auth copilot autolith auth fireworks autolith auth gemini autolith auth grok autolith auth mistral autolith auth nous autolith auth opencode autolith auth openrouter

Once you authenticate, it's time to have fun. Run autolith to get started.

Autolith 5th grade report card

Licence
ISC
Linux
x86_64 and aarch64, glibc and static musl
macOS
x86_64 and arm64
BSD
FreeBSD, NetBSD, OpenBSD on x86_64
Windows
x86_64
Updates
(update) inside AL, autolith update from the CLI

Yes, piping a URL into a shell is evil. Read the installer first, it's not so bad.

Nix is the preferred installation method on worthy operating systems.

Friends of Lambda Symbolics

Chakany Systems builds tools for private communication and researches human behavior and health.

They frequently contribute to Autolith.

chakany.systems ↗