lama_ole

A CLI tool to interact with Ollama instances. Supports streaming chat, tool calling, thinking-process handling, media understanding (image/video/audio), and flexible input/output options.

lama_ole.py --host localhost -m gemma4:26b-a4b-it-qat --chat -t -v --tool tools.dev_tools_readonly --tool tools.edit --logndjson log.ndjson

• Streaming Support — Real-time output as the model generates text.
• Thinking Process — Display or save the model's internal thought process (-t, --thoughtlog).
• Output Redirection — Save generated content to a log file (-o, --outlog).
• Tool Call Logging — Log tool calls and results to a separate file (--toolcalllog).
• Chat Input Logging — Log chat REPL input to a separate file (--chatinputlog).
• NDJSON Logging — Log every conversation message (timestamp, model, message) as its own NDJSON line (--logndjson).
• Flexible Input — Direct string (-i), file (-f), or stdin (--stdin).
• Chat Mode — Multi-turn REPL with slash commands (--chat).
• Plan / Build Modes — Switch between a read-only plan mode (write tools blocked, still advertised) and the full build mode with Shift+Tab, /plan, or /build.
• History Editing — Inspect and surgically edit the conversation history with /history and /cut (including undo); Ctrl-C only discards the incomplete part of the interrupted turn.
• Tool Calling — Load Python modules as callable tools (--tool).
• Tool Documentation — Inspect loaded tools, their signatures, and environment variables (--help-tools).
• Media Understanding — Image description/OCR, video frame analysis, audio transcription via bundled tools.media_understanding_tools.
• Model Listing — List available or running models (-l, --ps).
• Ollama Options — Pass through temperature, num_ctx, num_gpu, keep_alive.
• Model Transfer — Copy models between ollama instances (--transfer). Supports localhost-to-remote and remote-to-remote via a built-in blob HTTP server (--serve-blobs).

1. Ollama installed and running (ollama.com).
2. Python 3.9+.
3. The ollama Python library.

pip install ollama

python3 lama_ole.py -m gemma2:2b -i "Explain the theory of relativity."

python3 lama_ole.py -m gemma2:2b -t -i "Solve a complex math problem step by step."

python3 lama_ole.py -m gemma2:2b -i "Write a story" \
    --thoughtlog thoughts.txt -o story.txt

echo "Tell me a joke." | python3 lama_ole.py --stdin -m llama3.2:3b

python3 lama_ole.py --chat -m llama3.2:3b

With an initial system message:

python3 lama_ole.py --chat -m llama3.2:3b -i "You are a helpful assistant."

Load one or more tool modules. The LLM can then invoke them automatically.

python3 lama_ole.py -m llama3.2:3b -i "What's the weather in Paris?" \
    --tool tools.example_tools

python3 lama_ole.py --chat -m llama3.2:3b --tool tools.example_tools

Every file write made by a tool (edit, create_new_file, append_to_file, apply_patch) prints a colored unified diff in the output, so you can see exactly what changed:

[edit: src/foo.py] +3 -1
--- src/foo.py
+++ src/foo.py
@@ -12,3 +12,5 @@
 old line
+new line

Diff display is on by default. Disable it with --no-diff, or configure it via the env file (~/.config/lama_ole/lama_ole.env or ./lama_ole.env):

LAMA_OLE_SHOW_DIFF=false

Use --help-tools to see all loaded tools, their signatures, and which environment variables they read:

python3 lama_ole.py --help-tools --tool tools.media_understanding_tools

Output:

Tool Module: tools.media_understanding_tools
  Environment Variables:
    LAMA_OLE_VISION_HOST: Ollama host for vision/audio models (defaults to --host value)
  Functions:
    image_describe(path: string, [model: string]) — Describe the contents of an image using a vision model
    image_ask(path: string, question: string, [model: string]) — Ask a specific question about an image
    image_ocr(path: string, [lang: string]) — Extract text from an image using OCR (requires tesseract)
    video_describe(path: string, [interval: number], [model: string]) — Describe a video by extracting frames
    video_scene_changes(path: string, [threshold: number]) — Detect scene changes with ffmpeg
    video_transcribe(path: string, [model: string]) — Extract audio and transcribe with Whisper
    video_ask(path: string, question: string, [interval: number], [model: string]) — Ask about a video
    audio_transcribe(path: string, [model: string]) — Transcribe speech with Whisper
    audio_ask(path: string, question: string, [model: string]) — Transcribe and answer a question
    list_vision_models() — List available vision models configured via --vision_model

python3 lama_ole.py --chat -m llama3.2:3b \
    --tool tools.example_tools \
    --tool tools.media_understanding_tools \
    --tool tools.web_tools

The bundled tools.media_understanding_tools module provides image, video, and audio comprehension via Ollama vision models, Whisper transcription, and OCR.

Specify which vision models the tools should use with --vision_model (repeatable). The first model is the default when the LLM doesn't pick one.

python3 lama_ole.py --chat -m llama3.2:3b \
    --tool tools.media_understanding_tools \
    --vision_model gemma3:12b --vision_model llava:13b

The LLM can call list_vision_models() to see which models are available, then choose one by passing model="gemma3:12b" to any vision tool.

# Describe an image
python3 lama_ole.py -m llama3.2:3b -i "Describe this image" \
    --tool tools.media_understanding_tools \
    --vision_model llava-phi3:3.8b

# Ask about a video
python3 lama_ole.py -m llama3.2:3b -i "What objects are in this video?" \
    --tool tools.media_understanding_tools

# Transcribe audio
python3 lama_ole.py -m llama3.2:3b -i "Transcribe this recording" \
    --tool tools.media_understanding_tools

The tools.lsp_tools toolset gives the model IDE-style code intelligence by talking to a real Language Server over stdio (JSON-RPC 2.0 with Content-Length framing). All tools are read-only; files are still edited with the edit toolset and re-synced into the server automatically before every query.

python3 lama_ole.py -m <model> --chat --tool tools.lsp_tools --tool tools.edit

• lsp_start — start a session for a language (python, typescript, rust, go, cpp, c, json, ...). Sessions are long-lived; queries auto-start a session for the file's language, so lsp_start is optional.
• lsp_open / automatic sync — the server always sees the on-disk file content (mtime/size checks); edits made by other tools are picked up before each query.
• lsp_hover, lsp_definition, lsp_references, lsp_completion, lsp_signature_help, lsp_document_symbols, lsp_workspace_symbols — the standard code-intelligence queries. Positions are 0-based; character offsets are UTF-16 code units (per the LSP spec).
• lsp_diagnostics — errors/warnings cached from the server's publishDiagnostics push notifications (no round-trip).
• lsp_status / lsp_stop — inspect and shut down sessions.

Server commands come only from a built-in table or the LAMA_OLE_LSP_SERVERS environment variable — the model can never execute an arbitrary command:

export LAMA_OLE_LSP_SERVERS='{"python": "pyright-langserver --stdio", "rust": ["rust-analyzer"]}'

If a server crashes, the next query auto-restarts it once; a second crash in a row asks you to run lsp_start again. See llm_blueprint/lsp_tools/ for the design docs.

lama_ole can transfer models between ollama instances using --transfer.

python3 lama_ole.py -m gemma4:12b --transfer localhost other_host

The source must be localhost (the machine running lama_ole). The tool reads model blobs directly from the local ollama model store and uploads them to the destination ollama instance via its API.

On the source machine, start the blob HTTP server:

python3 lama_ole.py --serve-blobs --blob-port 9999

On the orchestrator machine, point --transfer at the blob server URL:

python3 lama_ole.py -m gemma4:12b \
    --transfer http://192.168.1.100:9999 other_host

The orchestrator downloads manifests and blobs from the source's blob server, then uploads them to the destination's ollama API. Blobs are streamed in chunks to avoid memory spikes.

ssh user@remote_source "lama_ole --serve-blobs --blob-port 9999" &
python3 lama_ole.py -m gemma4:12b \
    --transfer http://remote_source:9999 other_host

1. lama_ole reads the model manifest and all blob digests from the source
2. Each blob is uploaded to the destination via POST /api/blobs/
3. The FROM path in the Modelfile is rewritten to match the destination's model store
4. The model is created on the destination via POST /api/create

In chat mode (--chat), lines starting with / are commands:

Bare /tools prints the tool subcommand usage. Bare /skill prints the skill subcommand usage. Bare /systemprompt prints the current system prompt.

In chat mode a context-window usage meter is shown by default:

• The prompt shows a live gauge, e.g. [ctx 12,345/32,768 ████░░░░░░ 37%] , which is green below 70% usage, yellow from 70%, and red from 90%. It updates after every turn.
• /context prints the exact usage plus a per-category breakdown (system/user/assistant/tool), estimated and scaled to match the real token count; /context off and /context on toggle the meter.
• Before each turn a warning is printed when the typed message is predicted to overflow the window.
• The last-known usage is saved with the session and restored on /resume / /load, so the gauge is meaningful right away. The count is exact when the session's model is unchanged; after a model change (or a mid-session /model) it is shown as an estimate with a tilde, e.g. [ctx ~12,345/32,768 ████░░░░░░ ~37%] . The window size (num_ctx) does not affect the count — only the percentage, which recomputes against the current window.

The window size is resolved in order: --num_ctx, LAMA_OLE_CTX_SIZE, the running model's allocated context (ollama ps), the model's num_ctx parameter, the model's declared context length, otherwise unknown (token counts are shown without a percentage).

When the conversation grows too large for the context window, /compact summarizes the older turns into a single structured summary while keeping the most recent turns verbatim (mirroring how opencode compacts its sessions):

• Older turns are serialized into labeled text ([User]:, [Assistant]:, [Assistant tool call]:, [Tool result]:, ...), tool results are truncated to 2000 characters, and the head is handed to the summarizer model.
• The summarizer streams an anchored Markdown summary (Objective, Important Details, Work State, Next Move, Relevant Files). If the conversation was already compacted, the previous summary is passed as <previous-summary> and updated instead of being nested.
• The summarized head is replaced by a compacted user message and the recent tail (last 2 turns, bounded by a token budget) stays verbatim. The meter resets so usage is recomputed from the next request.
• Summaries use the model from --auto-compact-model, or the chat model by default. Confirmation is always requested before tokens are spent.

Auto-compaction triggers after a turn when the context usage crosses the threshold and asks for confirmation:

In chat mode /compact auto on / /compact auto off toggle auto-compaction at runtime and /compact auto shows the current setting.

Compaction configuration is saved with the session and restored on /resume.

Tab completion is enabled in interactive mode: commands, /tools, /skill, /compact and /systemprompt subcommands, and file paths (for /feed, /save, /load, /skill load and /systemprompt) are completed with Tab. Completion needs the readline module and is skipped automatically when stdin is not a terminal.

The chat agent runs in one of two opencode-style modes:

• Build (default) — full access to every loaded tool; changes are allowed.
• Plan — the model is told to analyze and plan without making changes. All loaded tools remain advertised so the model knows what exists, but write tools refuse to execute: a call returns a plan-mode notice instead of running. Read-only tools (modules marked __tool_readonly__ = True, e.g. tools.dev_tools_readonly, tools.web_tools, tools.media_understanding_tools) still work normally.

Switch modes with Shift+Tab (a single keystroke that toggles between /plan and /build), or type /plan / /build. The prompt always shows the current mode: a green [build] or a yellow [plan] . The mode is remembered in saved sessions, so resuming a plan session stays in plan mode. Start in a given mode with --mode plan (LAMA_OLE_MODE=plan). To make your own tool module plan-safe, add a module-level __tool_readonly__ = True.

Shift+Tab also works mid-turn — while the model is streaming or a tool is running, it switches mode without interrupting the current response. The switch takes effect immediately for tool execution: any write tool that arrives after the switch is blocked (the plan-mode notice is fed back to the model) while the advertised tool list stays unchanged. Printable keys typed mid-turn are captured and replayed into the next prompt's line buffer; Enter and arrow keys are ignored while the model is working.

Chat sessions are saved automatically. Each chat run is recorded after every turn and on exit, so you can leave and resume later without manual /save and /load.

• Storage: ~/.local/share/lama_ole/sessions/ (respects XDG_DATA_HOME, or override with LAMA_OLE_SESSION_DIR). One directory per project (the working directory encoded into a slug plus a short hash of the real path: /home/me/proj → home-me-proj-<hash>; the hash guarantees similar names like lama_ole vs lama-ole never collide), each session its own <session-id>.json file with 0600 permissions. The real directory path is stored inside the file.
• Auto-resume: starting --chat restores the most recent session for the current directory and prints a notice. The restored conversation is then replayed (user prompts and assistant replies, in their original colors) so it reads like you never left; thinking captured with -t is replayed only when -t is on, and tool call/result markers only in verbose mode — both matching their live visibility. If the session model differs from the CLI -m, you are asked which to keep (session / CLI / abort). /resume and /load replay the history the same way.
• Opt out: the two behaviors are independent toggles, both on by default:
  • --no-resume (or LAMA_OLE_RESUME=false) disables auto-loading.
  • --no-autosave (or LAMA_OLE_AUTOSAVE=false) disables writing session files. /resume and /sessions still work for manual recovery either way.
• Renames/moves: if a project directory is renamed, its sessions no longer match the new path automatically. Run /resume — sessions recorded elsewhere are listed (marked [moved]) and resuming one re-associates it to the current directory.
• /new: archives the current session (leaving it restorable) and starts a fresh one.
• /stats: shows the current model, the last turn's per-round breakdown (time, in/out tokens, tok/s), and session averages broken down per model. Averages and the last-turn breakdown are saved with the session (autosave, /save, /load, /resume) and restored on resume.
• Titles: sessions are titled from the first user message by default. /rename <new title> overrides it for the current session (persisted across autosaves), and /rename <id-prefix> <new title> renames any stored session by its session-id prefix. A renamed title is kept as-is; unrenamed sessions keep deriving from their first message.
• /save <path> / /load <path>: explicit portable snapshots for sharing or backup; they remain independent of the automatic sessions. /load first archives the current conversation to its auto-save slot, so a resumed session is never silently overwritten.

Every conversation message is numbered from M (oldest) down to 1 (newest), where M is the total number of messages — the same numbering used by /history and /cut. System messages are hidden from /history and are never removed by /cut.

/history lists the conversation with its message numbers, in order from oldest to newest. By default it shows user messages, assistant output, thinking and tool calls; tool responses are shown only with -t.

Every entry is prefixed with the time the event happened, e.g. [7] [2026-08-09 09:01:00] USER: .... Tool calls show the concrete function name and arguments (TOOL: [data from read_file: path='lama_ole/AGENTS.md']), not just an empty ASSISTANT (TOOLCALL) marker; the full tool response data still requires -t.

Ranges and numbers can be combined freely in one command.

/cut surgically removes entries from the conversation history. The removed messages are stored so they can be restored with /cut undo. System messages are never removed.

Example: after a /cut 3, the three most recent entries are gone, and the conversation continues from the remaining history. /cut undo brings them back, and a later /cut replaces the undo buffer (only the most recent cut is undoable).

When a turn is interrupted with Ctrl-C, only the incomplete part of that turn is removed from the history. Your last message — and the system prompt — are kept, and so are every completed tool round: a tool call that already returned its result stays visible in /history, so its context is preserved for the next turn. Only a tool call that was interrupted while still running (and its partial results) is dropped, along with whatever the model had started to generate when you pressed Ctrl-C.

Tools are Python functions decorated with @tool from tool_base:

from tool_base import tool


@tool(description="Multiply two numbers")
def multiply(a: int, b: int) -> int:
    return a * b


@tool(description="Get the population of a city")
def get_population(city: str) -> str:
    return f"Population of {city}: 2.5 million"

Parameter types are inferred from annotations. For complex schemas, pass explicit params:

@tool(
    description="Search the web",
    params={
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "Search query"},
        },
        "required": ["query"],
    },
)
def web_search(query: str) -> str:
    ...

Load your module:

python3 lama_ole.py -m llama3.2:3b -i "search for python tutorials" --tool mytools

Tools that read environment variables should define a module-level __tool_env__ dict. These are displayed by --help-tools:

__tool_env__ = {
    "MY_API_KEY": "API key for external service",
}

Most CLI flags can be given defaults via environment variables, so you don't have to repeat a long parameter list on every invocation.

CLI flag  >  shell env var  >  ./lama_ole.env (project)  >  ~/.config/lama_ole/lama_ole.env (user)  >  built-in default

• Values are stored in KEY=VALUE files, one per line. Blank lines and lines starting with # are ignored; optional surrounding quotes are stripped.
• The project file (./lama_ole.env in the current working directory) overrides the user file (~/.config/lama_ole/lama_ole.env).
• Anything already set in your shell environment wins over both files.
• An empty value (LAMA_OLE_MODEL=) means "unset" and falls back to the built-in default.
• Invalid values (e.g. LAMA_OLE_NUM_CTX=banana) print a warning to stderr and fall back to the default.

# ~/.config/lama_ole/lama_ole.env
LAMA_OLE_CHAT=true
LAMA_OLE_MODEL=llama3.2:3b
LAMA_OLE_THINKING=true
LAMA_OLE_SAFE=true
LAMA_OLE_TOOL=tools.example_tools tools.web_tools
LAMA_OLE_TEMPERATURE=0.2

python3 lama_ole.py                                # chat, llama3.2:3b, thinking+safe, example/web tools
python3 lama_ole.py --no-thinking                 # same, but thinking off
python3 lama_ole.py --no-chat -i "explain X"      # one-shot query, thinking still on
python3 lama_ole.py --tool tools.audio_tools      # config tools + audio_tools (merged)
python3 lama_ole.py --ignore-config-tools --tool tools.audio_tools
                                                  # audio_tools only

Because --chat, --thinking, --safe and --ollama_websearch accept both --flag and --no-flag, they can be turned on or off per run regardless of the configured default.

The LAMA_OLE_COLOR_* variables customize the ANSI colors used for the chat prompt, your typed input, the thinking stream, the LLM output, and the context meter (green below 70% usage, yellow from 70%, red from 90%). Each accepts a comma-separated color spec: a named foreground color (black…white, bright_*, grey/gray), a 256-color number (0–255), a hex value (#rrggbb), plus attributes (bold, italic, underline, dim, reverse). Examples: bold,green, #ff8700, bright_cyan. Use default or none to restore the built-in color. Your typed input is echoed in the input color by appending its escape code to the prompt (so it matches the replay); the default is bright_cyan while the model output defaults to bright_white. These are theme preferences, so they are configured via the env/config files only (the CLI keeps just the --color on/off switch); an invalid value prints a warning and keeps the built-in default.

Booleans accept 1/true/yes/on and 0/false/no/off (case-insensitive). --tool values are merged with the configured default (config first, deduplicated) unless --ignore-config-tools is given, which uses only the CLI --tool values. --vision_model always replaces the configured default when given on the command line.

Tool modules may read additional environment variables, e.g. LAMA_OLE_VISION_HOST (see --help-tools). These can live in the same config files.

• Connection Error — Ensure Ollama is running and --host matches your setup (default http://localhost:11434).
• File Exists Error — The script refuses to overwrite existing files. Remove the target file first or use a different path.
• Missing Library — Run pip install ollama. For media tools, also pip install Pillow.
• Tool not found — Use dotted module names, not file paths: --tool tools.example_tools (not --tool tools/example_tools.py).
• Media: no vision model found — Use --vision_model MODEL to specify which installed Ollama models are vision-capable. Run --help-tools with your tool module to verify configuration.
• Chat errors — Model errors in chat mode are caught gracefully and printed without exiting the REPL.

This project is open-source and available under the

Apache License Version 2.0, January 2004.