Ellama ¶

2.1 Core Chat and Agent Setup ¶

• ellama: This is the entry point for Ellama. It displays the main transient menu, allowing you to access all other Ellama commands from here.
• ellama-chat: Ask Ellama about something by entering a prompt in an interactive buffer and continue conversation. If called with universal argument (C-u) will start new session with llm model interactive selection.
• ellama-chat-send-last-message: Send last user message extracted from current ellama chat buffer.
• ellama-plan-and-act: Start an agent loop that first creates a checklist plan and then acts on it with automatic continuations. It reuses the current chat session when possible and can be launched from the main transient menu with A in the Problem solving section.
• ellama-setup-agentic-coding: Apply coding-agent defaults for long sessions: enable all tools, enforce DLP, block irreversible actions, and use longer agent loops. Pass an srt settings file to enable lower-prompt tool use inside that sandbox.

2.2 Ask and Media Input ¶

• ellama-ask-about: Ask Ellama about a selected region or the current buffer. Automatically adds selected region or current buffer to ephemeral context for one request.
• ellama-ask-selection: Send selected region or current buffer to ellama chat.
• ellama-ask-line: Send current line to ellama chat.
• ellama-ask-image: Ask Ellama about one image file by adding it as ephemeral context for the request. If called with universal argument (C-u) will start new session with llm model interactive selection.
• ellama-chat-with-image: Ask Ellama about one image file. If called with universal argument (C-u) will start new session with llm model interactive selection.
• ellama-chat-with-images: Ask Ellama about multiple image files. If called with universal argument (C-u) will start new session with llm model interactive selection.
• ellama-ask-audio: Ask Ellama about one audio file by adding it as ephemeral context for the request. If called with universal argument (C-u) will start new session with llm model interactive selection.
• ellama-chat-with-audio: Ask Ellama about one audio file. If called with universal argument (C-u) will start new session with llm model interactive selection.
• ellama-chat-with-audios: Ask Ellama about multiple audio files. If called with universal argument (C-u) will start new session with llm model interactive selection.
• ellama-ask-audio-recording: Record a short audio message from the microphone and ask Ellama about it.
• ellama-chat-with-audio-recording: Record a short audio message from the microphone and send it to chat.
• ellama-record-audio: Record a short audio message from the microphone and return the recorded file.
• ellama-start-audio-recording: Start microphone recording without a fixed duration.
• ellama-stop-audio-recording: Stop microphone recording and return the recorded file.

2.3 Text Writing and Transformation ¶

• ellama-write: This command allows you to generate text using an LLM. When called interactively, it prompts for an instruction that is then used to generate text based on the context. If a region is active, the selected text is added to ephemeral context before generating the response.
• ellama-complete: Complete text in current buffer with ellama.
• ellama-translate: Ask Ellama to translate a selected region or word at the point.
• ellama-translate-buffer: Translate current buffer.
• ellama-define-word: Find the definition of the current word using Ellama.
• ellama-summarize: Summarize a selected region or the current buffer using Ellama.
• ellama-summarize-killring: Summarize text from the kill ring.
• ellama-code-review: Review code in a selected region or the current buffer using Ellama. Automatically adds selected region or current buffer to ephemeral context for one request.
• ellama-change: Change text in a selected region or the current buffer according to a provided change.
• ellama-make-list: Create a markdown list from the active region or the current buffer using Ellama.
• ellama-make-table: Create a markdown table from the active region or the current buffer using Ellama.
• ellama-summarize-webpage: Summarize a webpage fetched from a URL using Ellama.
• ellama-proofread: Proofread selected text.
• ellama-improve-wording: Enhance the wording in the currently selected region or buffer using Ellama.
• ellama-improve-grammar: Enhance the grammar and spelling in the currently selected region or buffer using Ellama.
• ellama-improve-conciseness: Make the text of the currently selected region or buffer concise and simple using Ellama.
• ellama-make-format: Render the currently selected text or the text in the current buffer as a specified format using Ellama.

2.4 Code ¶

• ellama-code-review: Review code in a selected region or the current buffer using Ellama. Automatically adds selected region or current buffer to ephemeral context for one request.
• ellama-code-complete: Complete selected code or code in the current buffer according to a provided change using Ellama.
• ellama-code-add: Generate and insert new code based on description. This function prompts the user to describe the code they want to generate. If a region is active, it includes the selected text in ephemeral context for code generation.
• ellama-code-edit: Change selected code or code in the current buffer according to a provided change using Ellama.
• ellama-code-improve: Change selected code or code in the current buffer according to a provided change using Ellama.
• ellama-generate-commit-message: Generate commit message based on diff.

2.5 Providers and Models ¶

• ellama-provider-select: Select ellama provider.
• ellama-select-model: Change the current provider model interactively. The model transient can switch the provider type as well as the model. Built-in choices include Ollama, OpenAI-compatible, OpenAI, Claude, Gemini, DeepSeek, OpenRouter, Azure OpenAI, GitHub Models, Vertex AI, GPT4All, and Llama.cpp. It also supports providers with a chat-model slot. URL editing is available when the provider has a url slot. It can also set the maximum number of output tokens. Use "Reset model fields" to clear model, temperature, context-length, and max-token overrides and let the provider use its defaults; reset values are shown as default in the transient.

2.6 Sessions ¶

• ellama-load-session: Load ellama session from file.
• ellama-session-delete: Delete ellama session.
• ellama-session-switch: Change current active session.
• ellama-session-kill: Select and kill one of active sessions.
• ellama-session-rename: Rename current ellama session.
• ellama-session-compact-current: Compact current Ellama session context.
• ellama-session-compact: Select and compact an active Ellama session context.

2.7 Context ¶

• ellama-context-add-file: Add file to context.
• ellama-context-add-image: Add image file to context.
• ellama-context-add-audio: Add audio file to context.
• ellama-context-add-audio-recording: Record a short audio message and add it to context.
• ellama-context-start-audio-recording: Start microphone recording without a fixed duration.
• ellama-context-stop-audio-recording: Stop microphone recording and add the recorded file to context.
• ellama-context-add-directory: Add all files in directory to the context.
• ellama-context-add-buffer: Add buffer to context.
• ellama-context-add-selection: Add selected region to context.
• ellama-context-add-info-node: Add info node to context.
• ellama-context-reset: Clear global context.
• ellama-context-manage: Manage the global context. Inside context management buffer you can see ellama context elements. Available actions with key bindings:
  • n: Move to the next line.
  • p: Move to the previous line.
  • q: Quit the window.
  • g: Update context management buffer.
  • a: Open the transient context menu for adding new elements.
  • d: Remove the context element at the current point.
  • RET: Preview the context element at the current point.
• ellama-context-preview-element-at-point: Preview ellama context element at point. Works inside ellama context management buffer.
• ellama-context-remove-element-at-point: Remove ellama context element at point from global context. Works inside ellama context management buffer.

2.8 Chat Translation ¶

• ellama-chat-translation-enable: Enable chat translation.
• ellama-chat-translation-disable: Disable chat translation.

2.9 Blueprints and Community Prompts ¶

• ellama-community-prompts-select-blueprint: Select a prompt from the community prompt collection. The user is prompted to choose a role, and then a corresponding prompt is inserted into a blueprint buffer.
• ellama-blueprint-fill-variables: Prompt user for values of variables found in current blueprint buffer and update them.

2.10 Tools and DLP ¶

• ellama-tools-enable-by-name: Enable a specific tool by its name. Use this command to activate individual tools. Requires the tool name as input.
• ellama-tools-enable-all: Enable all available tools at once. Use this command to activate every tool in the system for comprehensive functionality without manual selection.
• ellama-tools-disable-by-name: Disable a specific tool by its name. Use this command to deactivate individual tools when their functionality is no longer needed.
• ellama-tools-disable-all: Disable all enabled tools simultaneously. Use this command to reset the system to a minimal state, ensuring no tools are active.
• ellama-tools-dlp-show-incident-stats: Show a summary buffer with recent DLP incident statistics.
• ellama-tools-dlp-clear-session-bypasses: Clear session-scoped DLP bypasses.
• ellama-tools-dlp-reset-runtime-state: Reset in-memory DLP runtime state, including incident logs and detector caches.

4.1 Option Reference ¶

• Core Behavior and Providers
• Sessions and Naming
• Task Providers and Media
• Display Context and Reasoning
• Blueprints Prompts and Conversion
• Tool Prompts and Edit Behavior
• DLP and Irreversible Actions
• Transient Menus Community Prompts and Diagnostics
• Tool Access and Sandboxing
• Task Templates Blueprints and Skills
• Agent and Subagent Loops

4.2 Session Provider Keys ¶

Ellama does not persist provider keys as plaintext in session files. Saved sessions keep provider settings such as model and URL, but provider key slots are removed before writing the session file. When a session is loaded, Ellama restores missing keys from the configured provider when possible.

If a saved provider key cannot be restored, the session still loads. Requests using that provider can fail later with the provider’s normal authentication error until the provider is configured again.

The upstream llm provider-key redaction change is merged, but released versions such as llm 0.30.3 may not include it yet. Until a released llm version containing that change is installed, provider keys can still appear in debugger output produced by llm itself. Ellama avoids adding new plaintext keys to saved session files, but it cannot redact every llm backtrace from older released llm versions.

Set ellama-session-persist-provider-keys to auth-source to save an auth-source lookup reference in the session file. The secret itself stays in auth-source and is resolved when the session is loaded. Ellama uses the provider URL host when available, otherwise the provider symbol or provider type, together with ellama-session-provider-key-auth-source-user and ellama-session-provider-key-auth-source-port.

Example auth-source entry:

machine api.example.com login ellama port api-key password example-secret

Example configuration:

(setopt ellama-session-persist-provider-keys 'auth-source)
(setopt ellama-session-provider-key-auth-source-user "ellama")
(setopt ellama-session-provider-key-auth-source-port "api-key")

4.3 Session Compaction ¶

Ellama can compact long chat sessions to keep them within the provider context window. Compaction summarizes older conversation turns into one synthetic assistant message and keeps the most recent user turns verbatim. New messages continue from the compacted prompt, so the session can keep running without resending the full history.

Automatic compaction is enabled by default with ellama-session-auto-compact-enabled. It runs after a response when Ellama can determine or estimate token usage and the session crosses the configured threshold. Use ellama-session-auto-compact-token-threshold for an absolute token threshold, or leave it unset to use ellama-session-auto-compact-threshold-percent of the provider context limit. While a session request or compaction is still running, Ellama rejects another request for the same session. This prevents accidental duplicate sends, for example by pressing C-c C-c twice in a chat buffer.

You can compact sessions manually:

• M-x ellama-session-compact-current compacts the current session.
• M-x ellama-session-compact prompts for an active session and compacts it.

Ellama keeps ellama-session-auto-compact-keep-last-turns recent user turns by default. When ellama-session-auto-compact-allow-fewer-kept-turns is non-nil, short oversized sessions may keep fewer recent turns so there is still older history to summarize. Disable this option when compaction should fail instead of reducing the kept-turn count.

The system message is not summarized by the compaction LLM. Ellama restores the original system message in the compacted session prompt context, including when an LLM provider moved the system message into a system interaction before the request.

Example configuration:

(setopt ellama-session-auto-compact-enabled t)
(setopt ellama-session-auto-compact-threshold-percent 75)
(setopt ellama-session-auto-compact-keep-last-turns 4)
(setopt ellama-session-auto-compact-allow-fewer-kept-turns t)
(setopt ellama-session-auto-compact-provider ellama-summarization-provider)

4.4 Image Input ¶

Ellama can send image files to providers that advertise the image-input capability through the llm library. Image data is sent as multipart media and is supported for PNG, JPEG, WebP and GIF files by default.

Use M-x ellama-ask-image to ask about one image. This command follows the same context-based workflow as ellama-ask-about: it adds the image as ephemeral context, sends the request with ellama-chat, and shows the image link in the chat buffer. M-x ellama-chat-with-image and M-x ellama-chat-with-images use the same context workflow for compatibility. The main transient menu also includes "Chat with image".

Programmatic calls can also pass image files directly:

(ellama-chat "Describe this screenshot." nil
             :images '("/path/to/screenshot.png"))

(ellama-stream "Extract visible text."
               :images '("/path/to/image.png"))

The singular :image argument is also accepted as a convenience alias.

Use M-x ellama-context-add-image to add an image to context. Image context is ephemeral by default, so it is attached to the next request and then removed. Set ellama-image-context-default-scope to persistent to keep image context until it is removed or the context is reset. The context transient menu also provides "Add Image"; combine it with --ephemeral to force one-request image context.

The built-in read_file tool supports image and audio files through a configurable read mode:

• auto: read text files as text and queue supported media files for model input
• text: force text reading, even for files with image-like extensions
• image: force image handling and return a clear text error for unsupported image types, missing sessions, or providers without image-input
• audio: force audio handling and return a clear text error for unsupported audio types, missing sessions, or providers without audio-input

Tool calls can request image handling explicitly:

{
  "file_name": "/path/to/image.png",
  "mode": "image"
}

4.5 Audio Input ¶

Ellama can also send audio files to providers with the audio-input capability. The default supported extensions are WAV, MP3, M4A, AAC, FLAC, OGG, Opus and WebM. Audio is sent as multipart media, the same transport used for image input. Set ellama-audio-file-extensions if your provider accepts another format.

Audio transport depends on the installed llm package. Ellama requires llm 0.31.1 or newer, which includes audio serialization for OpenAI-compatible and Ollama providers. Gemini and Vertex use their native inline media format.

Use M-x ellama-ask-audio for one audio file, or M-x ellama-chat-with-audio inside a chat workflow. For several files, use M-x ellama-chat-with-audios. These commands add audio as ephemeral context for the next request, so the file is not kept around unless you add it as persistent context yourself.

The read_file tool also accepts audio. In auto mode it recognizes supported audio extensions; use audio to request audio handling explicitly:

{
  "file_name": "/path/to/recording.wav",
  "mode": "audio"
}

The tool queues the recording as media for the next model turn. It does not return binary audio as text.

Programmatic calls can pass audio directly:

(ellama-chat "Transcribe this note." nil
             :audios '("/path/to/note.wav"))

(ellama-stream "Summarize the meeting."
               :audio "/path/to/meeting.mp3")

Use :media when a request mixes images and audio:

(ellama-chat "Compare the screenshot with the spoken notes." nil
             :media '("/path/to/screenshot.png"
                      "/path/to/notes.wav"))

Ellama selects an installed microphone recorder automatically. On macOS it tries FFmpeg and then SoX. On GNU/Linux it tries arecord, FFmpeg, and then SoX. Set ellama-audio-recording-command if you need another program, input device, or extra arguments. On macOS, allow microphone access for Emacs in System Settings under Privacy & Security > Microphone. If Emacs runs in a terminal, allow access for that terminal instead.

FFmpeg recordings use dynamic speech normalization by default. This helps when the microphone input is quiet and reduces the chance that an audio model will invent speech from a weak signal. Set ellama-audio-recording-ffmpeg-filter to nil to keep the original input level, or replace it with another FFmpeg audio filter.

• macOS microphone permission

APP=/Applications/Emacs.app
plutil -extract NSMicrophoneUsageDescription raw \
  "$APP/Contents/Info.plist"

/usr/libexec/PlistBuddy \
  -c 'Add :NSMicrophoneUsageDescription string Ellama records audio from the microphone.' \
  "$APP/Contents/Info.plist"

codesign --force --deep --sign - "$APP"

BUNDLE_ID=$(plutil -extract CFBundleIdentifier raw \
  "$APP/Contents/Info.plist")
tccutil reset Microphone "$BUNDLE_ID"
open "$APP"

M-x ellama-context-start-audio-recording
...speak for as long as needed...
M-x ellama-context-stop-audio-recording

4.6 Task Tool Subagents ¶

The task tool delegates work to an asynchronous sub-agent. The parent model gets control back immediately, and the sub-agent reports the final result by calling the injected report_result tool. If the sub-agent finishes a turn without reporting a result, Ellama sends ellama-tools-subagent-continue-prompt until the task is complete or ellama-tools-subagent-default-max-steps is reached.

Each sub-agent runs in its own Ellama session. When ellama-display-session-buffer-on-generation is non-nil, Ellama displays both the main session and sub-agent session buffers as generation starts. Sub-agent buffers include the delegated prompt under the Main agent: label, followed by the sub-agent response.

Sub-agents also keep session-local tool loop state. When ellama-tools-subagent-loop-detection-enabled is non-nil, the second consecutive identical tool call returns a recovery message instead of the normal tool result. The message includes the repeated tool name, exact arguments, the latest tool result and a next action. If the same consecutive call chain continues beyond ellama-tools-subagent-loop-detection-repeated-threshold, Ellama finishes the subtask with a loop-detected result. A later repeated call after a different tool call is treated as a new recovery opportunity, not as an immediate hard loop.

If a sub-agent LLM request fails before producing a tool result, Ellama keeps the sub-agent loop alive. The first consecutive request error records the failure and immediately continues the sub-agent. The second consecutive request error resets the counter, compacts the sub-agent session automatically, and continues the loop after compaction finishes or is skipped. Any successful sub-agent response resets the consecutive error counter.

The tool accepts either a free-form description or a prompt template:

{
  "template": "templates/researcher.md",
  "template_base": "/path/to/skill",
  "arguments": {
    "main_topic": "Example topic",
    "subtopic_name": "Example subtopic"
  },
  "role": "explorer"
}

Prompt templates are plain text files with placeholders like {main_topic}. The arguments object must provide values whose keys match the placeholder names. If validation fails, the tool returns an error with hints listing missing and unused keys and an example object to retry.

Template resolution is intentionally scoped:

• relative template paths are resolved under template_base when supplied
• otherwise relative paths are searched under ellama-tools-task-template-dirs
• path traversal outside the selected base directory is rejected
• absolute template paths are rejected unless ellama-tools-task-template-allow-absolute-paths is non-nil

This keeps large prompts out of the main agent context while still letting skills bundle reusable task prompts next to their SKILL.md files.

4.7 Plan-and-Act Agent Loop ¶

ellama-plan-and-act runs a local agent in the current Ellama chat session. It starts with a planning turn, asks the model to submit a checklist, and then continues automatically through the checklist until the agent reports a result, marks the plan complete, becomes blocked, or reaches ellama-tools-agent-default-max-steps.

If the LLM request fails before the loop receives a usable response, Ellama continues the same agent loop instead of stopping it. The first consecutive request error is recorded and the loop continues. The second consecutive request error triggers automatic session compaction, resets the error counter, and then continues the loop. A successful response resets the consecutive error counter.

The loop adds temporary controller tools to the session:

• agent_submit_plan records the initial checklist before acting starts
• agent_update_plan records progress as checklist items move between states
• agent_report_result finishes the loop and restores the original tool set

Models or providers that cannot call tools can still participate by emitting the fallback BEGIN_ELLAMA_AGENT_STATE block described in the controller prompt. Ellama parses that block, updates the stored state, and prints visible plan or status snapshots into the chat buffer.

Start the loop with M-x ellama-plan-and-act, or open the main transient with M-x ellama and press A in the Problem solving section. The transient entry respects the regular session options: use -n before A to create a new session, and use -e when ephemeral sessions are enabled.

Without a new-session request, the command reuses the current chat buffer and session. If that session already has an active plan-and-act loop, a new user message resumes the same loop instead of replacing the plan. This makes it possible to interrupt a running request with C-g, add corrective instructions under the next User: prompt, and continue the existing loop with C-c C-c or another ellama-plan-and-act call.

Plan-and-act state is stored in the session extra data, so the loop survives session compaction and regular session persistence. The visible plan/status notes in the chat buffer are for transparency; the canonical state is the session state used by the continuation handler.

4.8 Edit Tool Shell Hooks ¶

Projects can define shell commands that run around mutating edit tools: write_file, append_file, prepend_file and edit_file. Hooks are read from the target file buffer, so project-local values from .dir-locals.el apply to the file being edited.

Each hook entry is a plist with a required :command string. A non-zero exit status is always returned to the agent. Successful hook output is returned only when that hook has :show-output t and produced non-empty output.

Before hooks run after access checks and syntax validation, but before the file is written. A failing before hook blocks the edit. After hooks run after a successful write; failure is reported to the agent and does not roll back the edit.

Hook processes are started asynchronously, so long-running hooks do not block the Emacs UI. They are still blocking from the agent’s point of view: the edit tool callback runs only after all relevant before/after hooks finish, and the agent receives the final hook status together with the edit result.

Example project-local configuration:

((nil . ((ellama-tools-edit-before-shell-commands
          . ((:command "git diff --quiet")))
         (ellama-tools-edit-after-shell-commands
          . ((:command "make format-elisp" :show-output t)
             (:command "make test"))))))

Hook commands run from the target file’s project root, or from the file directory when no project is found. The command environment includes:

• ELLAMA_HOOK_PHASE: before or after
• ELLAMA_EDIT_OPERATION: write, append, prepend or edit
• ELLAMA_TOOL_NAME: tool name such as write_file
• ELLAMA_FILE_NAME: absolute target file name
• ELLAMA_PROJECT_ROOT: directory used as hook working directory
• ELLAMA_HOOK_NAME: optional :name value

Hook diagnostics use their own output line budget instead of sharing one limit with the main tool result. Hook output is operational feedback and is not scanned by tool output DLP.

4.9 DLP for Tool Input/Output ¶

Ellama includes an optional DLP (Data Loss Prevention) layer for tool calls. It can scan:

• tool input (arguments sent from the model to tools)
• tool output (strings returned from tools back to the model)

The DLP layer supports regex-based rules and exact secret detection derived from environment variables (including common encoded variants such as base64/base64url and hex). It also includes an optional LLM-based semantic check as a block-only backstop for payloads that look unsafe but do not match a deterministic rule.

Recommended initial rollout:

• enable DLP
• keep mode in monitor
• review incidents before switching selected paths to enforce
• if enabling the LLM detector, start with a small tool allowlist

Example minimal setup:

(setopt ellama-tools-dlp-enabled t)
(setopt ellama-tools-dlp-mode 'monitor)
(setopt ellama-tools-dlp-log-targets '(memory))

Key settings:

• ellama-tools-dlp-enabled: Enable DLP scanning for tool input/output.
• ellama-tools-dlp-mode: Rollout mode. Use monitor for detect+log only, or enforce to apply actions.
• ellama-tools-dlp-regex-rules: Regex detector rules (IDs, patterns, direction/tool/arg scoping, enable/disable, case folding).
• ellama-tools-dlp-scan-env-exact-secrets: Enable exact-secret detection from environment variables (enabled by default).
• ellama-tools-dlp-llm-check-enabled: Enable the optional isolated LLM safety classifier (disabled by default).
• ellama-tools-dlp-llm-provider: Provider used for the isolated LLM safety check. When nil, it falls back to the extraction provider, then the default provider.
• ellama-tools-dlp-llm-directions: Directions where the LLM detector may run (input, output, or both).
• ellama-tools-dlp-llm-max-scan-size: Maximum bytes eligible for the LLM detector. Payloads above this limit are skipped for the LLM pass.
• ellama-tools-dlp-llm-tool-allowlist: Optional list of tool names allowed to use the LLM detector. Nil means all tools are eligible.
• ellama-tools-dlp-llm-run-policy: Run the LLM detector only when deterministic findings are empty (clean-only) or on every non-blocked scan (always-unless-blocked).
• ellama-tools-dlp-max-scan-size: Maximum bytes scanned per input/output payload (default 5 MB; larger payloads are truncated for scanning).
• ellama-tools-dlp-input-default-action: Default action for input findings in enforce mode (allow, warn, block).
• ellama-tools-dlp-output-default-action: Default action for output findings in enforce mode (allow, warn, block, redact).
• ellama-tools-dlp-output-warn-behavior: Handling for output warn verdicts (allow, confirm, or block).
• ellama-tools-dlp-safe-read-file-regexps: Canonical file-name regexps whose file-reading outputs skip output DLP scans. This is for trusted source files that should not prompt on every agent read. It does not bypass input DLP, non-read tool output DLP, irreversible checks, srt checks, or line-budget truncation.
• ellama-tools-dlp-policy-overrides: Per-tool/per-arg overrides and exceptions. For structured input args, nested string values are scanned with path-like arg names (for example payload.items[0].token). Override :arg matches exact names and nested path prefixes (for example "payload" matches payload.items[0].token).
• ellama-tools-dlp-log-targets: Incident log targets (memory, message, file).
• ellama-tools-dlp-audit-log-file: JSONL path used when file sink is enabled.
• ellama-tools-dlp-incident-log-max: Maximum in-memory incidents retained.
• ellama-tools-dlp-input-fail-open / ellama-tools-dlp-output-fail-open: Behavior when DLP itself errors internally.
• ellama-tools-irreversible-enabled: Enable irreversible-action handling.
• ellama-tools-irreversible-default-action: Default irreversible action (warn or block, with monitor downgrade to warn-strong).
• ellama-tools-irreversible-unknown-tool-action: Default action for unknown MCP tools (warn or allow).
• ellama-tools-irreversible-require-typed-confirm: Require typed phrase for irreversible warnings.
• ellama-tools-irreversible-project-overrides-enabled: Enable project-local irreversible override policy.
• ellama-tools-irreversible-project-overrides-file: Project policy file name.
• ellama-tools-irreversible-project-trust-store-file: User trust store for repository approval records (repo root + remote + policy hash).
• ellama-tools-irreversible-scoped-bypass-default-ttl: Default TTL (seconds) for session bypass entries.
• ellama-tools-output-line-budget-enabled: Enable per-tool output line-budget truncation before returning text to the model (enabled by default).
• ellama-tools-output-line-budget-max-lines: Max lines per tool output (default 200).
• ellama-tools-output-line-budget-max-line-length: Max characters per line before a single line is truncated (default 4000).
• ellama-tools-output-line-budget-save-overflow-file: Save full overflowing output to a temp file when the output source file is unknown (default t).

Trusted read-file outputs:

ellama-tools-dlp-safe-read-file-regexps lets users mark known source files as safe for output DLP. By default, Ellama marks its own loaded ellama*.el source files safe, so autonomous agents can inspect Ellama internals without repeated DLP approval prompts. The match is performed against the canonical file name. Only output scans for file-reading tools are skipped; DLP still scans tool inputs and outputs from other tools.

Example:

(setopt ellama-tools-dlp-safe-read-file-regexps
        (list (concat "\\`"
                      (regexp-quote
                       (file-truename "/path/to/ellama/"))
                      "ellama\\(?:-[[:alnum:]-]+\\)?\\.el\\'")))

Enforcement behavior (v1):

• input block prevents tool execution
• input warn asks for explicit confirmation before execution
• output block returns a safe denial string
• output redact replaces detected fragments with placeholders
• output warn follows ellama-tools-dlp-output-warn-behavior (confirm by default)

LLM safety check behavior (v1):

• the LLM detector runs only when ellama-tools-dlp-llm-check-enabled is non-nil
• the checker uses an isolated structured-output request with no tools
• in monitor, unsafe LLM verdicts are logged but do not change the result
• in enforce, an unsafe LLM verdict may force block
• LLM findings never trigger warn or redact and do not affect redaction

Irreversible action safety (v1):

• irreversible warnings use warn-strong with typed confirmation phrase I UNDERSTAND THIS CANNOT BE UNDONE
• in enforce, high-confidence irreversible findings hard block
• in monitor, high-confidence irreversible findings still require typed confirmation and do not hard block
• unknown MCP tool identities default to warn (configurable via ellama-tools-irreversible-unknown-tool-action)
• policy precedence for irreversible decisions: high-confidence enforce block > session bypass > project override > global irreversible default
• project overrides are ignored until the repository policy is explicitly trusted; trust is bound to repo root, remote URL, and policy hash
• audit sink write failure for irreversible decisions is fail-closed; in interactive sessions a separate explicit confirmation can override once

Session bypass helper:

;; Allow irreversible actions for one tool identity in this session.
(ellama-tools-dlp-add-session-bypass "mcp-db/query" 3600 "migration window")

Autonomous agent configuration:

Autonomous agents need fewer routine prompts, not fewer checks. If every file read or harmless edit asks for approval, users learn to approve by reflex. Keep the prompts for cases that actually need a decision:

• clean read/write operations inside the approved workspace run automatically
• secret leaks and prompt-injection-like output are redacted or blocked
• ambiguous dangerous actions require typed user confirmation or fail closed
• high-confidence destructive actions are blocked, not prompted
• unknown MCP tools warn until they are classified

ellama-tools-allow-all bypasses only the normal confirmation wrapper. DLP, irreversible-action checks, output scanning, and srt filesystem checks still run because DLP wraps the confirmation layer. Use allow-all only with DLP in enforce mode and a constrained filesystem policy.

Recommended baseline for autonomous coding:

;; General agent defaults.  This does not configure a provider or model.
(ellama-setup-agentic-coding)

;; Low-friction autonomous mode with filesystem sandboxing.
(ellama-setup-agentic-coding
 "~/.config/ellama/srt-autonomous.json")

The first form enables DLP enforcement, blocks irreversible actions, and tunes the agent loop, but keeps global tool auto-approval off. Ordinary DLP input/output findings still ask before continuing.

The second form enables srt and turns on ellama-tools-allow-all. In that mode, ordinary DLP input findings are allowed and ordinary output findings are redacted, so the agent can keep working. Irreversible findings still block, and built-in shell secret checks still block because SRT cannot tell whether a command leaks a token to an allowed destination.

Use an srt policy that allows writes only inside the current project and a scratch area. Add explicit read/write denials for secrets, credentials, audit logs, and system paths. See the project sandbox example in the SRT Filesystem Policy for Tools section.

There are two reasonable policies for dangerous cases. User-handled dangerous cases ask only for DLP warnings and irreversible actions:

(setopt ellama-tools-dlp-input-default-action 'warn)
(setopt ellama-tools-dlp-output-warn-behavior 'confirm)
(setopt ellama-tools-irreversible-default-action 'warn)
(setopt ellama-tools-irreversible-require-typed-confirm t)

Medium-risk irreversible actions require the typed confirmation phrase I UNDERSTAND THIS CANNOT BE UNDONE. High-confidence destructive actions are still blocked in enforce mode before session or project overrides apply.

Secure fallback is better for unattended agents:

(setopt ellama-tools-dlp-input-default-action 'block)
(setopt ellama-tools-dlp-output-warn-behavior 'block)
(setopt ellama-tools-irreversible-default-action 'block)
(setopt ellama-tools-irreversible-require-typed-confirm t)

With secure fallback, the agent receives a denial string and must find a safer path. This avoids turning user confirmation into a routine approval habit.

Reduce prompt fatigue by tightening tool roles instead of weakening safety. Avoid :tools :all for autonomous subagents. Prefer separate roles such as:

• read-only explorer without shell_command
• coder with file tools and sandboxed shell_command
• bash role only when a task explicitly needs shell access
• no ask_user tool unless user interruption is intentional

For MCP tools, keep ellama-tools-irreversible-unknown-tool-action as warn initially. After observing common safe tools, classify trusted tool identities with ellama-tools-irreversible-tool-risk-overrides or trusted project overrides. Use ellama-tools-dlp-add-session-bypass only for narrow tool identities and short TTLs; do not disable DLP globally to reduce prompts.

If srt is not available, do not use global ellama-tools-allow-all for autonomous coding. Use a small ellama-tools-allowed list of safe read-only tools instead, and keep mutating tools behind confirmation or DLP fallback.

Tool output truncation behavior:

• line budget is applied per tool output payload
• if a payload exceeds the line budget, the model receives a truncation notice plus the truncated snippet
• if lines exceed ellama-tools-output-line-budget-max-line-length, those lines are shortened and marked with ...[line truncated]
• when source is known (for example read_file, lines_range, grep_in_file), the notice includes source path and suggests using lines_range and grep_in_file~/~grep
• when source is unknown (for example generic tool output), full output is saved to a temp file (if enabled) and the filename is included in the notice

Example regex rules:

(setopt ellama-tools-dlp-regex-rules
        '((:id "openai-key"
           :pattern "sk-[[:alnum:]-]+"
          :directions (input output))
          (:id "pem-header"
           :pattern "-----BEGIN [A-Z ]+-----"
           :directions (output)
           :enabled t)))

Example scoped override (ignore noisy shell command input):

(setopt ellama-tools-dlp-policy-overrides
        '((:tool "shell_command"
           :direction input
           :arg "cmd"
           :except t)))

Example override for structured input payloads (top-level arg prefix match):

(setopt ellama-tools-dlp-policy-overrides
        '((:tool "write_file"
           :direction input
           :arg "content"
           :action warn)))

Tuning helpers:

• M-x ellama-tools-dlp-reset-runtime-state
• M-x ellama-tools-dlp-show-incident-stats
• (ellama-tools-dlp-recent-incidents)
• (ellama-tools-dlp-incident-stats)
• (ellama-tools-dlp-incident-stats-report)

Incident stats include rollups by risk class, rule ID, tool identity, and decision type (including bypass).

For a longer rollout/tuning walkthrough and more override examples, see docs/dlp_rollout_guide.md.

Troubleshooting:

• repeated irreversible warnings: classify trusted MCP tools with ellama-tools-irreversible-tool-risk-overrides or use a short-lived session bypass for one tool identity
• bypass expiry: session bypasses expire by TTL and are removed automatically; re-add with ellama-tools-dlp-add-session-bypass when needed
• false positives: inspect incidents via ellama-tools-dlp-recent-incidents and tune regex rules / overrides before moving more paths to enforce

4.10 SRT Filesystem Policy for Tools ¶

When ellama-tools-use-srt is non-nil, the srt settings file is the source of truth for tool filesystem policy:

• shell-based tools (shell_command, grep, grep_in_file) are enforced by the external srt runtime
• non-shell file tools (read_file, write_file, append_file, prepend_file, edit_file, directory_tree, move_file, count_lines, lines_range) apply local checks derived from the same srt settings file

Supported local filesystem subset (current):

• filesystem.denyRead
• filesystem.allowWrite
• filesystem.denyWrite (takes precedence over allowWrite)

For irreversible audit hardening, keep ellama-tools-dlp-audit-log-file outside allowWrite and add explicit denyRead~/~denyWrite entries for the audit directory.

Local checks intentionally ignore unrelated srt keys (for example network.*). If the filesystem section is missing, local checks use the same defaults as srt for filesystem access: reads are allowed by default and writes are denied unless allowed by allowWrite.

Path matching notes for local checks:

• relative paths in srt rules are resolved against Emacs default-directory
• ~~ expands to the current user home directory
• literal paths, directory-prefix rules, and glob patterns are supported
• malformed/unsupported patterns signal a user-error (fail closed)

The local checks fail closed when ellama-tools-use-srt is enabled and:

• srt is not installed
• the resolved settings file is missing
• the settings file is malformed JSON
• relevant filesystem keys have an invalid shape

Example srt config for a project sandbox:

{
  "network": {
    "allowedDomains": [
      "github.com",
      "*.github.com",
      "api.github.com",
      "*.npmjs.org"
    ],
    "deniedDomains": [],
    "allowUnixSockets": [],
    "allowLocalBinding": false
  },
  "filesystem": {
    "denyRead": [
      "~/.srt-settings.json",
      "~/.ssh",
      "~/.aws",
      "~/.gnupg/",
      "~/.config/gcloud/",
      "~/.azure/",
      "~/.kube/",
      "~/.docker/",
      "~/.netrc",
      "~/.npmrc",
      "~/.pypirc",
      "~/.git-credentials",
      "~/.emacs.d/ellama-dlp-audit.jsonl",
      ".env",
      ".env.*",
      ".env*.local",
      "*.env",
      "*-credentials.json",
      "*serviceAccount*.json",
      "*service-account*.json",
      "kubeconfig",
      "*-secret.yaml",
      "secrets.yaml",
      "*.pem",
      "*.key",
      "*.p12",
      "*.pfx",
      "*.tfstate",
      "*.tfstate.backup",
      ".terraform/",
      ".vercel/",
      ".netlify/",
      ".supabase/",
      "dump.sql",
      "backup.sql",
      "*.dump"
    ],
    "allowWrite": [
      ".",
      "src/",
      "test/",
      "docs/",
      "/tmp/ellama-agent"
    ],
    "denyWrite": [
      "~/.srt-settings.json",
      "~/.ssh",
      "~/.aws",
      "~/.gnupg/",
      "~/.config/gcloud/",
      "~/.azure/",
      "~/.kube/",
      "~/.docker/",
      "~/.netrc",
      "~/.npmrc",
      "~/.pypirc",
      "~/.git-credentials",
      "~/.emacs.d/ellama-dlp-audit.jsonl",
      ".env",
      ".env.*",
      ".env*.local",
      "*.env",
      "*-credentials.json",
      "*serviceAccount*.json",
      "*service-account*.json",
      "kubeconfig",
      "*-secret.yaml",
      "secrets.yaml",
      "*.pem",
      "*.key",
      "*.p12",
      "*.pfx",
      "*.tfstate",
      "*.tfstate.backup",
      ".terraform/",
      ".vercel/",
      ".netlify/",
      ".supabase/",
      "dump.sql",
      "backup.sql",
      "*.dump",
      "/etc/",
      "/usr/",
      "/bin/",
      "/sbin/",
      "/boot/",
      "/root/",
      "~/.bash_history",
      "~/.zsh_history",
      "~/.node_repl_history",
      "~/.bashrc",
      "~/.zshrc",
      "~/.profile",
      "~/.bash_profile"
    ]
  },
  "ignoreViolations": {
    "npm": [
      "/private/tmp"
    ]
  },
  "enableWeakerNestedSandbox": false,
  "enableWeakerNetworkIsolation": false
}

Keep allowUnixSockets empty unless the agent explicitly needs a local socket. For example, adding /var/run/docker.sock gives the sandbox broad Docker control and should be treated as a privileged capability.

Example Emacs configuration:

(setopt ellama-tools-use-srt t)
(setopt ellama-tools-srt-args
        '("--settings" "/path/to/.srt-settings.json"))

Parity tests (real srt runtime vs local ellama checks):

• make test-srt-integration: Run host parity tests (requires srt installed)
• make test-srt-integration-linux: Run parity tests in Docker on Linux semantics. Requires Docker and runs a privileged container (--privileged).

5.1 Transient Menus for Context Management ¶

Ellama provides a transient menu accessible through the main menu, offering a streamlined way to manage context elements. This menu is accessed via the “System” branch of the main transient menu, and then selecting "Context Commands."

The Context Commands transient menu is structured as follows:

Context Commands:

• Options: Provides options for managing ephemeral context.
  • “-e” "Use Ephemeral Context" --ephemeral
• Add: Provides options for adding content to the global or ephemeral context.
  • “b” "Add Buffer" ellama-transient-add-buffer
  • “d” "Add Directory" ellama-transient-add-directory
  • “f” "Add File" ellama-transient-add-file
  • “I” "Add Image" ellama-transient-add-image
  • “A” "Add Audio" ellama-transient-add-audio
  • “R” "Record Audio" ellama-transient-add-audio-recording
  • “s” "Add Selection" ellama-transient-add-selection
  • “i” "Add Info Node" ellama-transient-add-info-node
• Manage: Provides options for managing the global context.
  • “m” "Manage context" ellama-context-manage - Opens the context management buffer.
  • “D” "Delete element" ellama-context-element-remove-by-name - Deletes an element by name.
  • “r” "Context reset" ellama-context-reset - Clears the entire global context.
• Recording: Provides start and stop commands for long microphone recordings.
  • “S” "Start Recording" ellama-transient-start-audio-recording
  • “E” "Stop Recording" ellama-transient-stop-audio-recording
• Quit: (“q” "Quit" transient-quit-one) - Closes the context commands transient menu.

5.2 Managing the Context ¶

ellama-context-manage opens a dedicated buffer, the context management buffer, where you can view, modify, and organize the global context. Within this buffer:

• n: Move to the next context element.
• p: Move to the previous context element.
• q: Quit the context management buffer.
• g: Refresh the contents of the context management buffer.
• a: Add a new context element (similar to ellama-context-add-selection).
• RET: Preview the content of the context element at the current point.

5.3 Considerations ¶

Keep context size in check. LLMs have finite context windows, and irrelevant information wastes tokens and can distract the model. Remove or refresh stale context before switching tasks.

6.1 ellama-context-header-line-mode ¶

Shows the Ellama context in the header line. By default, the line appears only when the global or ephemeral context is not empty. Set ellama-context-line-always-visible to keep it visible.

M-x ellama-context-header-line-mode toggles this mode.

The mode updates the display on window-state-change-hook. When disabled, it removes (:eval (ellama-context-line)) from header-line-format.

6.2 ellama-context-header-line-global-mode ¶

Enables ellama-context-header-line-mode in all buffers automatically.

M-x ellama-context-header-line-global-mode toggles this global mode.

6.3 ellama-context-mode-line-mode ¶

Shows the Ellama context in the mode line. It follows the same visibility rules as ellama-context-header-line-mode.

M-x ellama-context-mode-line-mode toggles this mode.

The mode updates the display on window-state-change-hook. When disabled, it removes (:eval (ellama-context-line)) from mode-line-format.

6.4 ellama-context-mode-line-global-mode ¶

Enables ellama-context-mode-line-mode in all buffers automatically.

M-x ellama-context-mode-line-global-mode toggles this global mode.

6.5 ellama-session-header-line-mode ¶

Displays the current Ellama session ID in the header line.

M-x ellama-session-header-line-mode toggles it in the current buffer; M-x ellama-session-header-line-global-mode toggles it globally.

The session ID uses the customizable ellama-face face.

6.6 ellama-session-mode-line-mode ¶

Displays the current Ellama session ID in the mode line.

M-x ellama-session-mode-line-mode toggles it in the current buffer; M-x ellama-session-mode-line-global-mode toggles it globally. This mode also uses ellama-face.

7.1 Key Components ¶

1. Act: The blueprint’s primary identifier (its name).
2. Prompt: Text that initializes the chat session, including instructions and context.
3. For Developers: A flag marking the blueprint as developer-facing.

7.2 Creating and Managing ¶

• ellama-blueprint-create: Create a blueprint from the current buffer. Prompts for a name and developer flag, then saves the buffer content as the prompt.
• ellama-blueprint-new: Create a new buffer for a blueprint, optionally inserting the current region if active.
• ellama-blueprint-select: Select a prompt and optionally filter by developer status or source (user, community, files, or all sources).

7.3 Blueprint Files ¶

Store blueprints as plain text files. Place them in:

• Global: ellama-blueprint-global-dir
• Project-local: ellama-blueprint-local-dir, relative to the project root

Files use extensions from ellama-blueprint-file-extensions.

7.4 Variables ¶

Blueprints can include variables that must be filled before the session runs.

• ellama-blueprint-fill-variables: Prompts for values for all variables found in the current buffer.

7.5 Keymap and Mode ¶

ellama-blueprint-mode is a text-mode derivative that highlights variables in curly braces and sets up local keybindings:

• C-c C-c: Open ellama-transient-blueprint-mode-menu. From there you can send the buffer to a chat, set it as the system message, create a blueprint, or fill variables.
• C-c C-k: Kill the current buffer.

7.6 Transient Menus ¶

• ellama-transient-blueprint-menu: Chat with a selected blueprint, create a new blueprint, or manage saved blueprints.
• ellama-transient-blueprint-mode-menu: Act on the blueprint in the current buffer.
• ellama-transient-main-menu: Integrates the blueprint menu into the main interface.

7.7 Running Blueprints Programmatically ¶

ellama-blueprint-run starts a chat session with a blueprint, pre-filling variables from the provided arguments.

(defun my-chat-with-morpheus ()
  "Start chat with Morpheus."
  (interactive)
  (ellama-blueprint-run "Character" '(:character "Morpheus" :series "Matrix")))

(global-set-key (kbd "C-c e M") #'my-chat-with-morpheus)

9.1 Directory Structure ¶

Ellama searches for skills in two locations:

1. Global: ‘~/.emacs.d/ellama/skills/’ by default, customizable via ellama-skills-global-path.
2. Project-local: skills/ inside the project root, customizable via ellama-skills-local-path.

A skill is a directory containing a SKILL.md file with metadata (name, description) and instructions for the agent. Skills can also include scripts, templates, and reference materials.

my-project/
└──skills/
   └── pdf-processing/
       ├── SKILL.md          # Required: instructions + metadata
       ├── scripts/          # Optional: executable code
       ├── references/       # Optional: documentation
       └── assets/           # Optional: templates, resources

9.2 Creating a Skill ¶

The SKILL.md file must include YAML frontmatter:

---
name: pdf-processing
description: Extract text from PDFs and summarize them.
---

# PDF Processing Instructions
To extract text from a PDF...

9.3 How It Works ¶

• Auto-Discovery: Ellama scans skill directories when each chat starts.
• Context: Skill metadata (name, description, location) is injected into the system prompt.
• Activation: The LLM loads SKILL.md content via read_file when needed.