@freelensapp/ai-extension

Freelens AI is an extension for Freelens that brings AI capabilities directly into your workflow.

With Freelens AI, you can harness the power of artificial intelligence to automate complex tasks and enhance productivity.

Video Demo

Video Demo

Quick Links:

• Install
• How to obtain a Google API Key (provider temporarily disabled)
• Build & Run Guide

Index

• @freelensapp/ai-extension
  • Video Demo
  • Index
  • Install
  • How it works
    • What the extension cannot use
  • Available Models
    • Using other providers through an OpenAI-compatible gateway
    • DeepSeek and other "thinking" models
    • Ollama
    • Connecting a model
    • Key Features
    • Base Agent
    • MCP Agent
      • Additional Resources

Install

Open freelens > file > extensions and add the folowing string to the textbox: @freelensapp/ai-extension

or:

Use a following URL in the browser: freelens://app/extensions/install/%40freelensapp%2Fai-extension

How it works

Freelens AI is a client of a large language model API. It does not run a model itself; instead it sends your prompts and the cluster context to a model provider and renders the response. The agent logic (the LangGraph supervisor, the cluster tools, structured output, and human-in-the-loop approvals) runs inside the extension, and only the model inference is delegated to the provider.

• Talks the OpenAI Chat Completions API. The extension is built on the OpenAI client and the OpenAI-compatible wire format. It works with OpenAI directly, and with any endpoint that implements the same API — either natively or through an OpenAI-compatible gateway such as LiteLLM (see Using other providers through an OpenAI-compatible gateway).
• Pay-as-you-go billing. You bring your own API key, and the provider bills you per token for the requests the extension makes. There is no bundled subscription or hosted backend; usage cost depends entirely on the model and provider you configure.
• Requires standard API access. Because the extension drives the model through the OpenAI-compatible API and its own tool/structured-output protocol, it can only use providers that expose such an API with a standard API key.

What the extension cannot use

Some providers do not offer a general-purpose, pay-as-you-go API key. Instead they grant access only through their own native tooling and a custom, proprietary SDK — for example Claude Code, which authenticates with a subscription token obtained via claude login / claude setup-token and is designed to be driven exclusively by Anthropic's own runtime and Agent SDK.

These providers are not compatible with this extension:

• The access is tied to a subscription/native client, not a standard pay-as-you-go API key, and reusing those tokens in a third-party app is outside the provider's terms.
• They expose their own agent loop, tools, and SDK rather than the OpenAI-compatible Chat Completions API and tool protocol the extension relies on, so they cannot be plugged in behind the existing provider/proxy.

If you want to use such a provider, run it through its own dedicated client. To use it with Freelens AI you would need an OpenAI-compatible endpoint and a standard API key (directly or through a gateway).

Available Models

The list of models is fully editable in the extension preferences. You can add or remove any model offered by the configured provider; the model name you enter is sent directly to the provider API.

The list comes seeded with these OpenAI models, which you can change at any time:

• gpt-5.5
• gpt-5.4
• gpt-5.4-mini

Model-specific behavior (for example, sending a reasoning effort instead of a temperature) is decided by heuristics on the model name, so adding a new model needs no code changes.

Currently the OpenAI provider is the only one enabled. Google/Gemini support is temporarily disabled and will return after further refactoring.

Using other providers through an OpenAI-compatible gateway

Although OpenAI is the only built-in provider, the extension talks to any endpoint that implements the OpenAI Chat Completions API. That means you can put a gateway such as LiteLLM in front of the extension and reach providers like Anthropic, Google/Gemini, DeepSeek, Qwen, and many others through a single OpenAI-compatible API.

To do this, set the Base URL in the OpenAI section of the preferences to your gateway (for example http://localhost:4000/v1) and use the model names exposed by that gateway. Requests are routed through the extension's local proxy, so the custom base URL works without any code changes.

DeepSeek and other "thinking" models

Some models reached through a gateway need extra handling, which the extension applies automatically based on the model name:

• DSML tool-call markup: DeepSeek models emit native tool calls in their "DSML" markup. OpenAI-compatible endpoints without a server-side tool-call parser leak this markup into the assistant text instead of returning structured tool calls. For these models the extension uses a client that recovers the tool calls from the markup so tools still run.
• Forced tool choice: DeepSeek and Qwen reasoning models reject a forced tool_choice while thinking mode is on; the extension requests tool_choice: "auto" for them instead.
• Disable thinking mode: some providers (for example DeepSeek via LiteLLM) expose a thinking mode that conflicts with the forced tool selection used for structured output. If you hit a Thinking mode does not support this tool_choice error, enable Disable thinking mode in the OpenAI preferences.

Ollama

Ollama exposes a natively OpenAI-compatible endpoint, so no gateway is needed to reach a model running on your own machine.

To connect it:

• Set the Base URL in the OpenAI section of the preferences to http://localhost:11434/v1.
• Set any non-empty API key. Ollama ignores its value, but a key must be set for the models to appear in the chat.
• Add the exact model name, including its tag (for example llama3.2:3b, as shown by ollama list), to the editable model list.

The model must support tool calling: the agent drives every cluster operation through tools, so a model without tool support cannot be used. Models with a "thinking" mode may need the handling described in DeepSeek and other "thinking" models.

No pricing data is available for local models, so the cost estimate stays hidden and only the token counter is shown.

On networks with TLS inspection, the first ollama pull may need the corporate root certificate to be trusted by Ollama's environment.

Connecting a model

Open the preferences page and, in the OpenAI section, set your API key and (optionally) a custom base URL. You can also provide the key through an environment variable instead:

• OPENAI_API_KEY = ...

A model is only offered in the chat dropdown once its provider has a key set; if no model is available, the chat shows a button that takes you to the preferences page.

The Base URL is a single global setting: every configured model is requested from that endpoint, so switching between a cloud provider and a local one means changing the Base URL. If you alternate between them regularly, put a gateway such as LiteLLM in front of the extension and keep one fixed URL, with the models routed by name.

Key Features

Talk to your cluster in natural language. The agent reads, explains, and (with your approval) changes Kubernetes resources, while the chat keeps the full context of the conversation.

Cluster operations through tools

• Any resource kind: list, get, create, update, patch, and delete any Kubernetes resource — built-in kinds and CRDs alike — instead of a fixed set of Pod/Deployment/Service operations.
• Pod logs: read a snapshot of container logs, including the previous (terminated) instance for CrashLoopBackOff, with a regular-expression filter to narrow chatty logs to only the matching lines.
• Smaller, focused output: metadata.managedFields is stripped by default, and JSONPath-style field selectors (the kubectl -o jsonpath subset) let the agent fetch only the fields it needs.
• In-place pod resize and scaling: patch the resize subresource to change a running Pod's CPU/memory without recreating it (Kubernetes 1.33+), or scale to change replicas.
• Delete and restart variants: graceful pod eviction that honors PodDisruptionBudgets, force delete with a zero grace period, finalizer clearing for objects stuck in Terminating, and rollout restart for workloads.
• Cluster insight: query the Kubernetes server version and analyze warning events in a namespace with explanations and remedies.

Safe, human-in-the-loop changes

• Approval gate: every change is shown for review — rendered as YAML — and applied only after you approve it.
• Backups: the current state of a resource is presented before it is changed, so a modification can be reverted.

Chat experience

• Persistent sessions: the chat transcript and agent state are stored by the host and survive application restarts; an unsent prompt draft is kept across view switches.
• Per-cluster context: each cluster keeps its own separate conversation.
• Token counter and cost estimate: a live per-session token count and cost estimate sit next to the model list.
• Automatic compaction: long sessions are compacted before they reach the model's input-token limit so the conversation can continue.
• Rich rendering: code blocks use the host Monaco editor, GitHub-flavored Markdown tables are supported, and model reasoning is shown in a collapsible block.
• Retry on errors: failed messages can be retried with one click.

Models and providers

• Editable model list seeded with OpenAI models, with model-specific behavior chosen by name heuristics (see Available Models).
• OpenAI-compatible gateways for reaching other providers, with built-in handling for DeepSeek and other "thinking" models.
• Custom agent rules can be added from the preferences to steer the agent.

Security

• The API key is injected in the main process rather than the renderer, the local AI proxy requires a per-launch bearer token, and CORS is restricted.

Base Agent

We have a base multi agent system that processes user prompts with a set of basic tools to get started. Go deeper by reading our Base Agent documentation.

MCP Agent

We support MCP Agent through a dedicated configuration. Go deeper by reading our MCP Agent documentation.

Additional Resources

• Contribute
• Build freelens-ai-extension extension
• Set up extension on freelens

If you find this project useful, please consider giving it a ⭐️ on GitHub!