Talk to Autolith

Prose, Lisp, and commands

Ordinary text is a prompt to the primary agent. It is equivalent to:

(prompt :to 'autolith "Review this change")

autolith is reserved, case-insensitively, for the primary agent.

As a shortcut, if you want to submit something to the main agent, you don't need to include the :to parameter:

(prompt "Shut yourself down homie")

prompt can also compute text or attach local images:

(prompt (read-file "request.org"))
(prompt :images "/tmp/diagram.png" "Review this diagram")
(prompt :to 'test-review "Run focused tests and report failures.")

If you message a sub-agent, it can respond to you in the main conversation thread if it wants to.

Start a message with ( to evaluate it as Common Lisp in the active image:

(help)
(resource.read :uri "workspace:.")
(eval-now (setf *print-pretty* nil))

Use (help) for a short overview. Choose a topic or look up one command:

(help :conversations)
(help :workspace)
(help 'resume)
(help "lisp.eval")

Keyword topics open sections. Quoted symbols and strings open command or tool help, including usage and parameter descriptions. Browse tools by namespace with (help :lisp), list all commands with (help :commands), or request the full reference with (help :all). Help uses the terminal Markdown renderer and Lisp syntax highlighting.

Press Tab after =(help = to browse topics and registered operations. Command options also appear after a command name and a space, for example =(ste =.

Type @ in prose or inside a Lisp string to fuzzy-search workspace files through fff. Accepting a match inserts the path and drops the @. Directories keep a trailing slash so you can keep completing. A completed file stays in the draft.

The clanker sees both your source input and its evaluated result apart from any other effects it may have.

Start input with ? followed by whitespace to evaluate one form asynchronously in the active image. Use this for a blocking operation or a bare variable:

? *package*
? (progn (sleep 10) (values :finished 42))

The editor displays ? in place of the normal prompt. Submit with Enter, then continue using the session while the form runs. ?? and ?text are chat; spaces, tabs, and line breaks after ? select asynchronous Lisp. Continue an incomplete form on another line as with ordinary Lisp input.

Inspect or cancel the returned exec:N job with job.get, job.wait, or job.cancel. Standard output, error output, and Lisp diagnostic streams are captured with bounded retention and rate-limited, sanitized terminal display. On completion, receive all returned values or the error, together with captured output. Asynchronous evaluation uses noninteractive error handling and EOF input rather than a restart picker.

The submitted form and its eventual result are retained in the originating session, including across a session switch. The model receives these messages at a safe request boundary; submitting a form does not start a model turn.

When local Lisp or an interactive command signals a serious condition, the restart debugger keeps the signaling stack and its live restarts available. Use Ask Autolith why this failed to run an independent diagnosis while the failed operation remains suspended. Diagnosis can offer up to three explicitly selected recoveries that invoke a live restart, run repair source first, retry the whole operation, return replacement values when supported, or abort the operation. Retry does not roll back effects completed before the failure.

The debugger shows the condition type and report, followed by available details such as the offending value, expected type, operation, filename, and reader location. These fields come from the condition itself and are also included in model diagnosis.

Escape during diagnosis cancels only the diagnosis and returns to the live restarts. Escape at the ordinary restart picker aborts the failed operation. During an active provider turn, Escape cancels the turn and continues queued steering in submission order, oldest first. Ctrl-C cancels and pauses queued work until you submit input; a second interrupt within the force-exit window exits the application.

Parking and editing queued input

Run (vault-store) to move queued work and unconsumed steering into the recovery input vault immediately, including during an active turn. Active work continues. Use (vault-contents) to read the parked entries in restoration order and setf to replace the whole list or one zero-based entry:

(vault-store)
(vault-contents)
(setf (vault-contents 0) '(:message "Revised task"))
(setf (vault-contents) '((:message "First task") (:lisp "(+ 1 2)")))
(vault-restore)

Entries are (:message INPUT), (:command TEXT), or (:lisp SOURCE). Direct vault reads and top-level setf forms containing only vault-contents places execute during an active turn. Returned lists are detached snapshots; publish edits with setf. Use (setf (vault-contents) nil) to clear parked input. Run (vault) for a summary or (vault-restore) to prepend parked work to the live queue.

Managed resources

resource.read observes durable state and returns an opaque revision. resource.edit applies a resource-specific operation only against that exact observation.

For multi-file semantic changes, Autolith prepares a cl-resources change set against retained file revisions and validates every member before publication. Each file is published atomically. On a later failure, Autolith restores earlier members; conflicting external updates require explicit recovery rather than replacement. File moves preserve source permissions captured during staging.

Papercuts use current-workspace resource URIs:

• papercut:current lists active reports and accepts papercut-report.
• papercut:id/<percent-encoded-stable-id> reads one active report and accepts papercut-close with a complete resolution.

The existing papercut.report tool and (papercuts), (papercut "ID"), and (papercut-close "ID") commands remain convenient direct interfaces.

Conversation history uses read-only resource URIs:

• conversation:current is the current conversation's complete durable history, including the records compaction removed from the model context. A plain read returns the newest records; start-sequence and record-count (default 20, maximum 200) page by durable record sequence. A window holds at most 7,000 characters and shortens long records, so read a record alone to see all of it.
• With query, the read lists the newest records containing every whitespace-separated term, each with its sequence and an excerpt. ASCII letters match in either case and other characters match exactly. max-results defaults to 20 and is capped at 50. Messages, assistant replies, reasoning summaries, tool call arguments and outputs, web searches, and compaction summaries are searched.
• conversation:id/<id> reads or searches another conversation by its identifier. Searches never span several conversations.

Each model report is acknowledged durably in the conversation, and a report that repeats an active papercut of the workspace is not recorded again: a title matching word for word, or a title and body whose words largely overlap a report from the last day, answers with that existing report instead. A conversation re-filing within an hour of its own report is matched more loosely, since rewritten repeats share fewer words.

Exporting and importing data

Use the same portable archive from the command line or an active session:

autolith data export all.sexp --all
autolith data export project.sexp --workspace /home/al/code/project
autolith data import project.sexp --workspace /home/al/src/project

(data.export "all.sexp" :all)
(data.export "project.sexp" :workspace "/home/al/code/project")
(data.import "project.sexp" :workspace "/home/al/src/project")

Export defaults to all workspaces and global data. A workspace export contains its conversations, memories, agendas, plans, papercuts, and associated session assets. The archive contains Autolith data rather than the repository files; clone or copy the repository separately. Credentials, configuration, executable image state, and caches are excluded.

Import preserves stable identifiers and merges into local data. Identical data is skipped; a conflicting identity aborts the import before publication. For a single-workspace archive, --workspace DIRECTORY or :workspace "DIRECTORY" sets its new home directory. Without that option, workspace locations are preserved. Relative paths are resolved against the current working directory.

Export creates a new private archive and refuses to overwrite an existing file. The CLI exits without starting a session: success is 0, invalid arguments are 64, and transfer failures are 1. Both command groups provide --help.

Session titles and resume

A session gets an immediate local title from its first prompt or image. After the third actual user turn, Autolith may ask the active model for one concise replacement and persist it with the conversation. The local title does not depend on provider generation.

Provider-generated refreshes are enabled by default. Use (titles), (titles "on") or (titles "off") to inspect or change the durable global preference.

(resume) displays titles in its picker while an explicit (resume "ID") continues to address the stable conversation identifier. The terminal status bar and local session status display the title when one is available and otherwise show the conversation ID.

A resumed conversation runs in a fresh process, so background jobs, asynchronous shell runs, and Lisp worker state from before the restart no longer exist. The first user turn after a resume carries a request-local notice telling the model so, which keeps it from polling or waiting on dead jobs. Only durable child task results stay readable through job.get.

Inspect a saved conversation without resuming or locking it with:

autolith replay ID
autolith replay ID turn 12
autolith replay ID date 2026-08-28
autolith replay ID time 2026-08-28T10:30:00
autolith replay ID sequence 1200

On an interactive terminal, replay behaves like a small debugger over durable conversation events. next and previous step records; turn, date, time, and sequence jump to a location; raw shows the selected replay form; and quit exits. Replay reads complete persisted forms without acquiring the conversation lease or repairing, appending, or resuming the conversation.

Local sessions

Every running Autolith session publishes a private authenticated local endpoint. Its session ID is the active conversation ID, shared with resume and stable across detach, restart and checkpoint quiescence. Selecting another conversation with new, resume or fork moves the endpoint to that conversation ID while attached terminals continue using the same connection. Inspect endpoints with:

autolith localgroup status
autolith localgroup status --sexp

idle means that the process is at input with no active work of any kind.

Control a sessions with the following commands:

autolith localgroup tell   SESSION-ID "message"
autolith localgroup pause  SESSION-ID
autolith localgroup attach SESSION-ID
autolith localgroup attach SESSION-ID --read-only
autolith localgroup attach SESSION-ID --take-over
autolith localgroup detach SESSION-ID
autolith localgroup kill   SESSION-ID

Use a full SESSION-ID or a prefix that matches one session. Prefixes accept IDs with or without the display hyphen, for example b, b-6, or b6 for b-6uouHJ. Full IDs take priority over prefix matches. If a prefix matches more than one session, the error lists the matching IDs; use a longer prefix. Current IDs are case-sensitive. Legacy hexadecimal IDs accept either case.

tell uses input to tell something to a session and resumes a paused session. pause cancels active work and holds queued primary work. kill requests graceful shutdown.

Detaching hands a session to a supervised process group that outlives the terminal. Windows has no process groups or detached sessions, so sessions there always run directly in the terminal that started them: (detach) and client-first starts report that the handoff is withheld, while the loopback endpoint and the localgroup commands work as elsewhere.

Autolith stores configuration, durable data, process state, and replaceable caches below ${XDG_CONFIG_HOME:-~/.config}/autolith/, ${XDG_DATA_HOME:-~/.local/share}/autolith/, ${XDG_STATE_HOME:-~/.local/state}/autolith/, and ${XDG_CACHE_HOME:-~/.cache}/autolith/. XDG base-directory values must be nonempty absolute paths; invalid values use these defaults. Newly created Autolith roots have mode 0700.

On Windows the same four roots are, unless an absolute XDG variable overrides one, %APPDATA%\autolith\, %LOCALAPPDATA%\autolith\data\, %LOCALAPPDATA%\autolith\state\, and %LOCALAPPDATA%\autolith\cache\. Private files and directories carry an access control list granting only the owner and SYSTEM, which is what mode 0600 and 0700 mean there; a file Autolith publishes read-only withholds write access through that list and keeps the read-only attribute clear, so it can still be replaced and deleted.

Conversation leases, Localgroup endpoint records, and recovery state live under ${XDG_STATE_HOME:-~/.local/state}/autolith/ rather than XDG_RUNTIME_DIR. They must survive logout so detached sessions, handoffs, and crash recovery can continue across login sessions. Autolith uses authenticated loopback TCP rather than filesystem sockets for its inference and Localgroup protocols, and cleans stale Localgroup records itself.