OpsLens

OpsLens is a local-first incident investigation CLI. Start with an alert, exact error, symptom, or log dump. OpsLens opens an iterative terminal chat, retrieves project and incident context, runs bounded read-only evidence tools, and keeps a cited investigation trail for follow-up. Incident records include guarded lifecycle states, append-only operational events, and versioned evidence-backed hypotheses.

It ships as a single CGo-free Go binary. Project state stays in local SQLite. OpenAI provides embeddings and standalone answers; the investigation agent can use OpenAI or Anthropic directly, or run through an authenticated Claude Code or Codex CLI. Provider integrations are extensible through a trusted, read-only plugin system, so AWS, GCP, Datadog, or internal tools do not need to be compiled into OpsLens.

Homebrew works on macOS and Linux:

brew install niuguy/tap/opslens

Prebuilt archives and checksums are also available from GitHub Releases.

To build from source, install Go 1.25 or later and run:

git clone https://github.com/niuguy/opslens.git
cd opslens
make build
./dist/opslens --help

To make that build available as opslens without using sudo, copy it into a user-local binary directory and ensure that directory is on PATH:

mkdir -p "$HOME/.local/bin"
install -m 0755 dist/opslens "$HOME/.local/bin/opslens"
export PATH="$HOME/.local/bin:$PATH"
opslens --help

Add the PATH export to your shell profile to keep it across terminal sessions.

export OPENAI_API_KEY="your-api-key"
cd /path/to/project

opslens init .
opslens

OpenAI is the default for all model roles. To use Anthropic for investigation reasoning, initialize first, then change only models.agent in .opslens/config.json and export its key:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514"
}

export ANTHROPIC_API_KEY="your-api-key"

Keep the embedding and answer roles on OpenAI; those adapters are currently OpenAI-only.

You can also set models.agent.provider to claude-code or codex and select a model supported by the corresponding installed, authenticated CLI. OpsLens launches it in headless mode and automatically connects the OpsLens MCP bridge, including tools contributed by enabled plugins.

Type what you know. OpsLens accepts a vague symptom, exact error, pasted alert, or a focused log sample. The agent shows each read-only tool call and keeps the chat open for follow-up questions.

Type / to open the focused investigation command palette. It covers starting or resuming a session, recording an outcome, diagnostics, evidence ingestion, incident notes, and confirmed closure. Use the arrow keys to select, Tab or Enter to complete, and /exit to leave. The session is preserved. Prefix literal slash-leading evidence with //.

After a conclusion, choose what should be recorded:

1. Keep only the investigation session.
2. Record an incident.
3. Create a remediation issue.
4. Record both.

The model cannot make this choice or execute remediation.

OpsLens can load external integrations as MCP-stdio plugin executables. A plugin publishes strict read-only tools using the open v1alpha1 manifest schema, and can live in its own repository and release independently from OpsLens.

Registering a plugin pins checksums for its manifest and executable in a user-level trust registry. Each project must then enable it explicitly:

opslens plugin validate ./plugin.json
opslens plugin add ./plugin.json
opslens plugin doctor my-plugin
opslens plugin enable my-plugin
opslens plugin list

Enabled tools are namespaced, such as aws__filter_log_events, to prevent collisions. An investigation can use tools from several enabled plugins; inspect multiple registrations together with opslens plugin inspect aws datadog, or run opslens plugin doctor --all before an investigation. The same namespaced tools are exposed through the OpsLens MCP bridge, allowing Claude Code or Codex to discover and call plugin integrations while investigating.

The repository includes a development-stage AWS CLI plugin for bounded identity, EC2, and CloudWatch evidence. Plugin authors can use the public sdk/plugin Go package or implement the same MCP stdio contract in another language. See the plugin architecture and authoring guide for manifests, permissions, result schemas, process limits, and repository strategy.

Open the embedded, read-only React interface from any initialized project:

opslens ui

The UI is the primary browsing surface for investigation histories and audited tool activity, incidents, remediation issues, structured playbooks, cataloged services and telemetry queries, and index coverage. It binds only to a local loopback address, reads the same SQLite state as the CLI, and does not require an OpenAI API key. Use opslens ui --no-open to print the local URL without opening a browser, or --port <port> to select a stable port.

Ingestion is optional. Preview the smallest useful documentation or source directory before indexing it:

opslens ingest runbooks --dry-run
opslens ingest runbooks

Use --no-embeddings for local FTS5-only indexing. Sensitive paths such as .env*, credentials, private keys, databases, binaries, and archives are denied by default. Add a root .opslensignore for project-specific exclusions.

Existing Markdown runbooks work as ordinary evidence. Teams that want reviewed, portable diagnostic structure can also keep versioned OpsLens playbooks beside their code:

opslens playbook validate playbooks
opslens ingest playbooks --dry-run

The open v1alpha1 YAML format can describe triggers, evidence requests, bounded PromQL/LogQL/TraceQL/Jaeger queries, investigation steps, mitigation safeguards, ownership, and source attribution. Playbooks guide the agent; live or historical evidence must still support its findings.

See the playbook specification and demo playbook.

The optional Docker Compose demo starts Grafana, Loki, Prometheus, and a synthetic checkout workload that emits current payment-connection failures:

export OPENAI_API_KEY="your-api-key"
make demo-up

cd examples/demo
opslens inv "$(curl -fsS http://localhost:18080/investigation-prompt)"

Open the provisioned Grafana dashboard to see the same logs and metric. Run make demo-down to stop the stack, or make demo-reset to stop it and remove only its Docker volumes. Docker is not a runtime dependency of the CLI.

The interactive chat is the default on a terminal. One-shot and machine-readable paths remain available:

opslens inv --once "payment connection refused"
kubectl logs deployment/checkout --since=10m | opslens
opslens inv --json "payment connection refused"
opslens inv --record-only < error.log

Resume with opslens inv -s latest. Start against an existing incident with opslens inv --incident <incident-id> "symptom". Export a completed or active investigation as a self-contained report:

opslens export latest > investigation.md
opslens export latest --json > investigation.json

The primary help stays focused on everyday workflows; compatible script and automation commands are documented in the advanced reference.

Source files remain authoritative on disk. Configuration, indexed chunks, returned embeddings, investigation history, tool audits, incidents, issues, and compact observations are stored under .opslens/. Credentials are read from environment variables and are not written to config.

Model-backed commands send only the selected content needed for that request to the configured provider; OpsLens does not upload the SQLite database or indiscriminately send the whole project. Raw continuous telemetry remains in the observability backend. Live tools require bounded windows and persist audited compact results rather than a telemetry mirror.

When kubectl is installed, the investigation agent can also inspect an allowlisted set of Kubernetes resources with bounded, read-only get, describe, logs, and top operations. It uses the machine's current Kubernetes context, so review that context and its access before starting a model-backed investigation.

Plugins execute with the same operating-system permissions as OpsLens; the manifest policy is not an OS sandbox. Only register reviewed executables and grant each project the plugins it needs.

Read the data boundary before using sensitive project or incident data.

• One operator and one project-local SQLite database.
• OpenAI implements embedding, answer, and investigation-agent roles; Anthropic additionally implements the investigation-agent role.
• Exact local vector scanning is intended for small and medium indexes.
• Agent tools are read-only; remediation is never automatic.
• Catalog, Prometheus, Loki, Tempo, Jaeger, and local Kubernetes integrations are optional.
• Trusted external read-only plugins can contribute namespaced investigation tools through MCP stdio.
• Investigation sessions can be exported to Markdown or JSON.
• Shared storage and external issue-tracker synchronization are not implemented yet.

• Investigation workflow
• Investigation playbook specification
• Local and OpenAI data boundary
• Advanced command and telemetry reference
• Plugin architecture and development

Contributions are welcome; read CONTRIBUTING.md before submitting a change. Report vulnerabilities using the private process in SECURITY.md.