Ellama ¶

4.1 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.

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.

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-provider ellama-summarization-provider)

4.2 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 files through a configurable read mode:

• auto: read text files as text and queue supported image files as image 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

Tool calls can request image handling explicitly:

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

4.3 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.

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.4 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-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).

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 a low-friction policy. Prompting on every ordinary tool call trains users to approve blindly, which is worse than a smaller set of high-signal prompts. The recommended shape is:

• 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 only bypasses the normal confirmation wrapper. It does not bypass DLP, irreversible-action checks, output scanning, or srt filesystem checks because DLP wraps the confirmation layer. This makes allow-all suitable only when DLP enforcement is enabled and tool filesystem access is constrained.

Recommended baseline for autonomous coding:

(with-eval-after-load 'ellama-tools
  ;; Let clean calls run without repetitive prompts.
  (setopt ellama-tools-allow-all t)

  ;; Required safety layer.
  (setopt ellama-tools-dlp-enabled t)
  (setopt ellama-tools-dlp-mode 'enforce)

  ;; Prefer fail-closed behavior for autonomous operation.
  (setopt ellama-tools-dlp-input-fail-open nil)
  (setopt ellama-tools-dlp-output-fail-open nil)

  ;; Keep secret and output protections active.
  (setopt ellama-tools-dlp-scan-env-exact-secrets t)
  (setopt ellama-tools-dlp-input-default-action 'warn)
  (setopt ellama-tools-dlp-output-default-action 'redact)

  ;; Irreversible actions require stronger intent.
  (setopt ellama-tools-irreversible-enabled t)
  (setopt ellama-tools-irreversible-default-action 'warn)
  (setopt ellama-tools-irreversible-require-typed-confirm t)

  ;; Keep telemetry durable enough to tune.
  (setopt ellama-tools-dlp-log-targets '(memory file))

  ;; Strongly recommended when `ellama-tools-allow-all' is enabled.
  (setopt ellama-tools-use-srt t)
  (setopt ellama-tools-srt-args
          '("--settings" "~/.config/ellama/srt-autonomous.json")))

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.5 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
  • “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.
• 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 ¶

Large Language Models possess limited context window sizes, restricting the total amount of text they can process. Be mindful of the size of your context to avoid truncation or performance degradation. Irrelevant context can dilute the information and hinder the LLM’s focus. Ensure context remains up-to-date for accurate information. Experimentation with different approaches to context management can optimize performance for specific use cases.

6.1 ellama-context-header-line-mode ¶

Description: Toggle the Ellama Context header line mode. This minor mode updates the header line to display context-specific information.

Usage: To enable or disable ellama-context-header-line-mode, use the command:

M-x ellama-context-header-line-mode

When enabled, this mode adds a hook to window-state-change-hook to update the header line whenever the window state changes. It also calls ellama-context-update-header-line to initialize the header line with context-specific information.

When disabled, it removes the evaluation of (:eval (ellama-context-line)) from header-line-format.

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

Description: Globalized version of ellama-context-header-line-mode. This mode ensures that ellama-context-header-line-mode is enabled in all buffers.

Usage: To enable or disable ellama-context-header-line-global-mode, use the command:

M-x ellama-context-header-line-global-mode

This globalized minor mode provides a convenient way to ensure that context-specific header line information is always available, regardless of the buffer being edited.

6.3 ellama-context-mode-line-mode ¶

Description: Toggle the Ellama Context mode line mode. This minor mode updates the mode line to display context-specific information.

Usage: To enable or disable ellama-context-mode-line-mode, use the command:

M-x ellama-context-mode-line-mode

When enabled, this mode adds a hook to window-state-change-hook to update the mode line whenever the window state changes. It also calls ellama-context-update-mode-line to initialize the mode line with context-specific information.

When disabled, it removes the evaluation of (:eval (ellama-context-line)) from mode-line-format.

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

Description: Globalized version of ellama-context-mode-line-mode. This mode ensures that ellama-context-mode-line-mode is enabled in all buffers.

Usage: To enable or disable ellama-context-mode-line-global-mode, use the command:

M-x ellama-context-mode-line-global-mode

This globalized minor mode provides a convenient way to ensure that context-specific mode line information is always available, regardless of the buffer being edited.

6.5 Ellama Session Header Line Mode ¶

The ellama-session-header-line-mode is a minor mode that allows you to display the current Ellama session ID in the header line of your Emacs buffers. This feature helps keep track of which session you are working with, especially useful when managing multiple sessions.

• Enabling and Disabling
• Customization

M-x ellama-session-header-line-mode

M-x ellama-session-header-line-global-mode

6.6 Ellama Session Mode Line Mode ¶

The ellama-session-mode-line-mode is a minor mode that allows you to display the current Ellama session ID in the mode line of your Emacs buffers. This feature provides an additional way to keep track of which session you are working with, especially useful when managing multiple sessions.

• Enabling and Disabling
• Customization

M-x ellama-session-mode-line-mode

M-x ellama-session-mode-line-global-mode

7.1 Key Components of Ellama Blueprints ¶

1. Act: This is the primary identifier for a blueprint, representing the

action or purpose of the blueprint.

1. Prompt: The content that will be used to initiate the chat session. This

can include instructions, context, or any other relevant information needed to guide the conversation.

1. For Developers: A flag indicating whether the blueprint is intended for

developers.

7.2 Creating and Managing Blueprints ¶

Ellama provides several functions to create, select, and manage blueprints:

• ellama-blueprint-create: This function allows users to create a new blueprint from the current buffer. It prompts for a name and whether the blueprint is for developers, then saves the content of the current buffer as the prompt.
• ellama-blueprint-new: This function creates a new buffer for a blueprint, optionally inserting the content of the current region if active.
• ellama-blueprint-select: This function allows users to select a prompt from the collection of blueprints. It filters prompts based on whether they are for developers and their source (user-defined, community, or all).

7.3 Blueprints files ¶

You can also store blueprints as plain text files. You can store it globally inside ellama-blueprint-global-dir or locally in the project local directory ellama-blueprint-local-dir with ellama-blueprint-file-extensions.

7.4 Variable Management ¶

Blueprints can include variables that need to be filled before running the chat session. Ellama provides command to fill these variables:

• ellama-blueprint-fill-variables: Prompts the user to enter values for variables found in the current buffer and fills them.

7.5 Keymap and Mode ¶

Ellama provides a local keymap ellama-blueprint-mode-map for managing blueprints within buffers. The mode includes key bindings for sending the buffer to a new chat session, killing the current buffer, creating a new blueprint, and filling variables.

The ellama-blueprint-mode is a derived mode from text-mode, providing syntax highlighting for variables in curly braces and setting up the local keymap.

When in ellama-blueprint-mode, the following keybindings are available:

• C-c C-c: Send current buffer to a new chat session and kill the current buffer.
• C-c C-k: Kill the current buffer.
• C-c c: Create a blueprint from the current buffer.
• C-c v: Fill variables in the current blueprint.

7.6 Transient Menus ¶

Ellama includes transient menus for easy access to blueprint commands. The ellama-transient-blueprint-menu provides options for chatting with a selected blueprint, creating a new blueprint, and quitting the menu.

The ellama-transient-main-menu integrates the blueprint menu into the main menu, providing a comprehensive interface for all Ellama commands.

7.7 Running Blueprints programmatically ¶

The ellama-blueprint-run function initiates a chat session using a specified blueprint. It pre-fills variables based on 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 looks for skills in two locations:

1. Global: ‘~/.emacs.d/ellama/skills/’ (Customizable via

ellama-skills-global-path)

1. Project-Local: skills/ inside your project root (Customizable via

ellama-skills-local-path)

A skill is a directory containing a SKILL.md file. This file includes metadata (name and description, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle 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 ¶

SKILL.md must contain 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 automatically whenever a chat starts. Context: Skill metadata (name, description, location) is injected into the system prompt. Activation: The LLM uses the read_file tool to load the SKILL.md content when needed.