The workspace

A workspace is the directory Autolith works in. It decides which project instructions Autolith reads, which project-local skills, roles, and servers may load, and where relative paths land.

Show and change it

prompt window

/cwd "/tmp/work tree"

/cwd without arguments shows the active workspace; with a path it moves new work there. Tool calls, process spawns, and workspace references follow the change.

What Autolith reads

Standing project instructions come from AGENTS.md files: the project root first, deeper files refining earlier ones. Everything under .autolith/ is opt-in, and most of it needs an explicit trust decision:

AGENTS.md: Standing project instructions, re-read on every request.
.autolith/skills/: Project Skills, loaded from the catalog when work calls for them.
.autolith/agents/: Task roles for child agents and jobs.
.autolith/mcp.sexp: MCP servers; a repository can enable these only after you trust the directory.
.autolith/init.lisp: Full-power setup Lisp, loaded only for trusted directories.

Where state lives

Autolith follows the XDG base-directory specification. Every root is created private (mode 0700), and nothing lands in the project unless a tool writes it there:

~/.config/autolith/: init.lisp, mcp.sexp, directory-scopes.sexp, management tokens.
~/.local/share/autolith/: Built Lisp images and inference objects.
~/.local/state/autolith/: Conversation leases, localgroup records, recovery state, provider credentials.
~/.cache/autolith/: Session scratchpads, converted skill caches.

Conversations are append-only readable files; /conversations lists them, and the resume picker shows their titles.

Read-only mode

Starting with --immutable withholds evaluation, mutation, persistence, checkpoint, and rollback tools. Inspection and recovery information stay available, which makes immutable mode the right choice when you want to look without letting anything change.