Your first session

When you run lime in a project, the engine assembles a system prompt from a layered set of files, opens a session, and starts streaming. This page walks through what happens, in order, the first time.

What Lime loads on launch

Project instructions. The repo’s AGENTS.md (committed) and any nearby .lime/ content provide project-wide context.
Local overrides. AGENTS.local.md (uncommitted) and .lime/settings.local.{json,toml} add machine-local context and settings.
User-level memory. ~/.lime/ contributes user-wide context that travels with you across projects.
Merged config. Five layers — Policy → User → Project → Local → CLI flags — merge into the runtime configuration. Trusted settings (permissions.defaultMode, MCP startup config) intentionally resolve from User + Local only, so a checked-in repo file can never silently lower trust on a teammate’s machine.
Provider catalog. The built-in model catalog is merged with any user models from ~/.lime/models.json. The active model is resolved from --model, then LIME_MODEL, then models.default.slug in config, then the hardcoded default gpt-5.4.
Tool registry & permission policy. Built-in tools and any plugin-provided tools are registered. The active permission mode is set from --permission-mode, then config, then the default default.
MCP servers. Configured MCP servers connect (where eager startup is enabled) and surface their tools alongside the built-ins.

You can inspect exactly what’s loaded with:

/memory      Show the resolved instruction & memory files
/config      Inspect merged config sections (env, hooks, model, plugins)
/status      Show session, model, token, workspace, and provider status

The permission flow

Every tool call is checked against the active permission policy before execution.

Mode	Behavior
`default`	Prompt for file changes and shell access.
`plan`	Read-only — file-mutating tools are blocked.
`acceptEdits`	Auto-approve workspace edits; prompt for shell access.
`bypassPermissions`	Unrestricted tool access.
`dontAsk`	Auto-approve everything without prompting.

Switch modes at launch:

lime --permission-mode plan

…or inside the REPL:

/permissions acceptEdits

When a tool needs approval, Lime renders a prompt with the tool name, its arguments, and the choices Allow once, Allow always (creates a rule), Deny, or Ask. See Permission model for the full picture.

Sessions are saved automatically

Sessions are stored as JSONL under .lime/sessions/ (project) and ~/.lime/sessions/ (global). Files rotate at 256 KB, retaining up to 3 rotated copies. Resume anytime:

lime --continue                # most recent session
lime --resume latest           # likewise
lime --resume <session-id>     # by id

A first concrete task

A safe first prompt that exercises the read-only tools:

“Find every TODO in this repo and group them by file, then summarise the most common patterns.”

A first prompt that exercises the permission flow:

“Add a doc comment to the most-touched function in src/main.rs.”

Lime will show you a diff before applying the edit; you can accept, edit the change, or deny.

Sessions — how compaction, forking, and resume work.
CLI reference — every flag and subcommand.
Permission model — modes, allow/deny/ask rules, and the trusted-settings pin.