Libre Claw

Libre Claw is a terminal-native autonomous coding agent harness built by Kroonen AI. It gives you a serious local TUI, Telegram control, durable runs, persistent memory, browser tools, scheduled tasks, and multi-provider model routing in one Python application.

It is built for developers who want an agent that can actually work in a project, ask before side effects, remember useful context, and keep running when the terminal closes.

Current release: Version 0.1.0.

Highlights

Capability	What it means
Terminal UI	Streaming chat, file explorer, command palette, approvals, run timeline, and artifacts.
Telegram bridge	Talk to the same agent from Telegram, approve tools inline, and receive scheduled reports.
Durable runs	Every task gets a run ID, JSONL event log, summary, verification notes, and optional diff.
Local dashboard	Start, inspect, cancel, and approve daemon-owned runs from a browser on localhost.
Memory and skills	Local persistent memory, SOUL.md persona files, user/project SKILL.md workflows, and optional Vercel Skills discovery.
Real tools	File edits, shell, code search, web search, git, HTTP requests, browser actions, screenshots, MCP tools, and more.
Provider routing	Kimi Code/Moonshot, OpenRouter, Ollama/Ollama Cloud, llama.cpp/llama-swap, Anthropic, OpenAI, Codex OAuth, and local-compatible endpoints.
Reproducible evals	A Harbor adapter runs the real Libre Claw loop against Terminal-Bench 2.1.
Petdex companion	Optional local state updates for the Petdex desktop companion app.
Safe defaults	API keys stay out of project config, dangerous commands are blocked, and writes require approval.

The evaluation adapter, reproduction commands, and recorded smoke results are documented in benchmarks/README.md.

Install

Recommended local install:

git clone https://github.com/kroonen-ai/libre-claw.git
cd libre-claw
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

One-command installer:

curl -fsSL https://raw.githubusercontent.com/kroonen-ai/libre-claw/main/scripts/install.sh | sh

For browser tools:

python -m pip install -e ".[browser]"
python -m playwright install chromium

For local web search, run a private SearXNG instance:

libre-claw searx init
libre-claw searx up
libre-claw searx test

Libre Claw uses http://127.0.0.1:8888 by default through the web_search tool. The generated SearXNG settings enable JSON output, which is required for agent searches. Once searx init has written the files, libre-claw start also brings the container up automatically, so manual searx up is only needed for the first setup or explicit control. The implementation walkthrough lives in docs/SEARXNG_INTEGRATION.md.

Update an installed Git checkout safely:

libre-claw update

The updater fetches origin/main, compares commits, writes a backup under ~/.libre-claw/backups/updates/, then applies a fast-forward update. It refuses to pull over uncommitted changes; use libre-claw update --dry-run to check first.

The same updater is available as /update in the TUI and authorized Telegram chats. Use /update --dry-run to check only. After an update, restart the TUI or run /restart in Telegram to load the new code.

Optional Petdex companion integration:

[petdex]
enabled = true
base_url = "http://127.0.0.1:7777"
token_path = "~/.petdex/runtime/update-token"
source = "libre-claw"
bubble_prefix = "🦞"

When enabled, Libre Claw sends local lifecycle updates to Petdex for daemon, TUI, Telegram, scheduled runs, tool calls, approvals, success, and errors. Use /petdex status in the TUI or Telegram to verify the token and endpoint. The TUI also renders the active Petdex sprite from ~/.petdex when the companion is enabled and a pet is installed.

First Run

Start the TUI:

libre-claw

Equivalent entrypoints:

libre-claw tui
libre-claw chat
python -m libre_claw

The TUI runs full-screen by default. Use PageUp / PageDown to scroll the transcript, Ctrl+Home / Ctrl+End to jump, and Ctrl+Shift+C to copy the current Textual selection. If you want normal terminal scrollback instead, launch with libre-claw tui --inline. If you want clickable Textual mouse controls, launch with libre-claw tui --mouse or set [tui].mouse = true.

File edits are rendered as compact unified diffs. Press Ctrl+E or run /review to open the focused change drawer, then use its Previous/Next controls to inspect every edit without digging through tool output. Permission prompts show the exact patch, file contents, or shell command before approval.

You can attach images in the TUI by dragging an image into the terminal or pasting its local path into a message. Use /attach <image-path> to queue an image for the next prompt, /attach paste or /paste-image to pull an image from the OS clipboard, /attach list to inspect queued images, and /attach clear to reset them. Libre Claw renders a small terminal preview and sends the image to vision-capable providers.

Inside the app, run:

/setup status
/setup provider openrouter
/setup key openrouter
/model openrouter:openrouter/auto --global

The --global flag saves the selected provider/model to ~/.libre-claw/config.toml.

Provider Setup

Libre Claw does not need real API keys in project files. Use the key store:

libre-claw auth set-key openrouter
libre-claw auth set-key moonshot
libre-claw auth set-key anthropic
libre-claw auth set-key openai
libre-claw auth set-key ollama
libre-claw auth status

Or use environment variables:

export OPENROUTER_API_KEY="..."
export KIMI_API_KEY="..."
export ANTHROPIC_API_KEY="..."
export OPENAI_API_KEY="..."
export OLLAMA_API_KEY="..."

Key lookup order:

1. Environment variable.
2. OS keyring.
3. Encrypted local fallback file at ~/.libre-claw/.keys.

Common Model Commands

/model list
/model openrouter:qwen/qwen3.7-max --global
/model openrouter:qwen/qwen3.7-flash --global
/model openrouter:sakana/fugu-ultra --global
/model openrouter:poolside/laguna-s-2.1 --global
/model openrouter:poolside/laguna-s-2.1:free --global
/model openrouter:deepseek/deepseek-v4-flash --global
/model openrouter:deepseek/deepseek-v4-flash-0731 --global
/model openrouter:~deepseek/deepseek-v4-flash-latest --global
/model openrouter:moonshotai/kimi-k3 --global
/model openrouter:moonshotai/kimi-k2.7-code --global
/model openrouter:z-ai/glm-5.2 --global
/model openrouter:minimax/minimax-m3 --global
/model openrouter:google/gemini-3.6-flash --global
/model openrouter:google/gemini-3.5-flash-lite --global
/model openrouter:anthropic/claude-opus-5 --global
/model openrouter:anthropic/claude-opus-5-fast --global
/model openrouter:anthropic/claude-sonnet-5 --global
/model openrouter:nvidia/nemotron-3-ultra-550b-a55b:free --global
/model moonshot:k3 --global
/model moonshot:kimi-for-coding --global
/model moonshot:kimi-for-coding-highspeed --global
/model ollama:glm-5.2:cloud --global
/model ollama:minimax-m3:cloud --global
/model ollama:kimi-k2.6:cloud --global
/model anthropic:claude-opus-5 --global
/model anthropic:claude-sonnet-5 --global
/model anthropic:claude-opus-4-8 --global
/model openai:gpt-5.5 --global
/model codex:gpt-5.6-sol --global

Claude Opus 5 is the default direct Anthropic model. Libre Claw uses its documented one-million-token context window with a conservative 65,536-token output cap (the model supports up to 128,000), leaves adaptive thinking at the provider default, omits unsupported sampling parameters, and privately round-trips signed thinking blocks across tool calls. The OpenRouter routes preserve the corresponding ordered reasoning_details blocks. See the Anthropic model overview and OpenRouter reasoning guide.

Fallback slots let Libre Claw keep working if the primary provider is rate-limited or down before it starts streaming. Configure up to three ordered backups:

/fallback list
/fallback set 1 openrouter:openrouter/auto --global
/fallback set 2 ollama:kimi-k2.6:cloud --key-env OLLAMA_BACKUP_API_KEY --global
/fallback set 3 anthropic:claude-sonnet-5 --global
/fallback recheck 3 --global
/fallback clear all --global

While running on a fallback, Libre Claw retries the primary after the configured number of fallback provider calls. The default is 3.

llama.cpp And llama-swap

Local llama.cpp endpoints work through the llamacpp provider. It targets the OpenAI-compatible API that both llama-server and llama-swap expose, so llama-swap can hot-swap between every model in its config:

[providers.llamacpp]
base_url = "http://localhost:8080"
default_model = "qwen3-30b" # a model id from your llama-swap config

Discover which model ids the endpoint can serve:

curl http://localhost:8080/v1/models        # straight from llama-swap
curl http://127.0.0.1:8766/models/llamacpp  # through the Libre Claw daemon

The dashboard composer also lists discovered models as suggestions when the llama.cpp (llama-swap) provider is selected. Switch with:

/provider llamacpp
/model llamacpp:qwen3-30b --global

No API key is needed for local endpoints; set api_key_env only when the server sits behind an authenticating proxy.

Local Web Search

web_search is backed by SearXNG so the agent can search the web without scraping a commercial search page through bash or the browser. The default config is:

[web_search]
enabled = true
provider = "searxng"
base_url = "http://127.0.0.1:8888"
max_results = 10

Useful commands:

libre-claw searx init      # write compose/settings files
libre-claw searx up        # start local SearXNG with Docker Compose
libre-claw searx status    # show container status
libre-claw searx test      # verify JSON search output
libre-claw searx down      # stop local SearXNG

Implementation notes and debugging tips: docs/SEARXNG_INTEGRATION.md.

Use /provider when you only want to switch providers:

/provider openrouter
/provider moonshot
/provider ollama
/provider anthropic
/provider openai
/provider codex

Codex / ChatGPT Login

Codex uses the supported Codex CLI login flow instead of an OpenAI API key:

libre-claw auth codex-login

Or inside the TUI:

/codex login
/provider codex
/model codex:gpt-5.6-sol --global

Libre Claw's OAuth picker follows OpenAI's current Codex model guide:

Model	Best fit
gpt-5.6-sol	Flagship model for complex coding, computer use, research, and cybersecurity.
gpt-5.6-terra	Balanced everyday work with strong reasoning and tool use at a lower cost.
gpt-5.6-luna	Fast, affordable execution for clear, repeatable, high-volume tasks.
gpt-5.5	Previous-generation frontier model for complex coding and knowledge work.
gpt-5.3-codex-spark	Text-only, near-instant coding research preview for ChatGPT Pro users.
gpt-5.4	Professional work with strong coding, reasoning, tool use, and agentic workflows.
gpt-5.4-mini	Fast, efficient coding tasks and subagents.

OpenAI marks gpt-5.2 and gpt-5.3-codex as deprecated for ChatGPT sign-in, so Libre Claw excludes them from the OAuth picker. Model availability still depends on the signed-in ChatGPT account and workspace.

Run Surfaces

TUI

libre-claw tui

Best for interactive coding, approvals, file browsing, artifacts, and local work.

Daemon And Dashboard

libre-claw start
libre-claw daemon

Open:

http://127.0.0.1:8766/dashboard

The daemon owns active runs, keeps them alive after the TUI exits, exposes a local dashboard, supervises schedules, and can start Telegram automatically when Telegram is enabled and a stored bot token exists.

Lifecycle helpers:

libre-claw shutdown
libre-claw restart

restart reuses the last recorded mode, so a running telegram up stack comes back as telegram up. Logs go to ~/.libre-claw/daemon.log.

Use libre-claw stop when you want to cancel the active daemon turn without shutting down Libre Claw.

Telegram

libre-claw telegram setup --user-id 123456789
libre-claw telegram up

Telegram uses your numeric Telegram user ID, not your @username. If you are blocked, the bot replies with the exact allow command to run.

Telegram messages can include photos or image documents. Libre Claw stores uploads locally under ~/.libre-claw/telegram/uploads/, passes them to vision-capable providers, and keeps captions as the user prompt.

Useful Telegram commands:

/start
/help
/new
/restart
/model
/models
/provider
/cost
/usage
/status
/daemon
/runs
/run
/compact
/schedule
/heartbeat
/memory
/cancel
/stop
/shutdown
/btw
/steer

What The Agent Can Do

Libre Claw ships with production-oriented tools for:

• Reading, writing, editing, searching, and listing project files.
• Running shell commands with timeout, truncation, and permission checks.
• Inspecting git status and creating commits with approval.
• Making direct HTTP requests for APIs and downloads.
• Browsing pages with persistent Playwright profiles.
• Clicking, typing, waiting, extracting page data, dismissing cookie banners, taking screenshots, and saving downloads.
• Creating, updating, pausing, resuming, deleting, and listing Libre Claw schedules through the same permission system.
• Calling configured MCP tools through the same permission system.

Write/edit/shell/browser action tools ask first. Read-only tools are allowed by default.

Core Workflows

Durable Runs

Every user task gets a run under:

~/.libre-claw/runs/<run-id>/

Each run can include:

• events.jsonl
• summary.md
• verification.md
• diff.patch
• browser artifacts
• tool and permission events

Useful commands:

/runs
/run <id>
/resume <id>
/cancel <id>
/artifacts summary <id>
/changes <id>
/approvals

Persistent Memory

Libre Claw stores local memory in three layers:

• Raw session archives in ~/.libre-claw/sessions/.
• Durable run archives in ~/.libre-claw/runs/.
• Searchable memory items in ~/.libre-claw/memory.db.

It can automatically extract durable facts, preferences, project decisions, and workflow summaries after completed runs. Credential-looking data is redacted before indexing or injection.

Useful commands:

/memory status
/memory list
/memory search <query>
/memory add <text>
/memory forget <id>
/memory summarize
/memory on
/memory off

Skills And Persona

Libre Claw loads reusable skills from:

~/.libre-claw/skills/
<project>/.libre-claw/skills/

AgentSkills-style packages with SKILL.md are supported. Libre Claw can also opt into the open Vercel Skills ecosystem by caching vercel-labs/skills and exposing a read-only skills_search tool to the agent.

Enable external skill discovery in ~/.libre-claw/config.toml:

[skills]
enabled = true
external_discovery_enabled = true
external_auto_refresh = true
vercel_source_enabled = true
cli_command = "npx -y skills@latest"

Persona files are loaded from:

~/.libre-claw/SOUL.md
<project>/.libre-claw/SOUL.md
<project>/SOUL.md

Useful commands:

/skills list
/skills sync
/skills show <name>
/skills show --external find-skills
/skills add --project <name>
/soul status
/soul init --project
/soul show

See docs/VERCEL_SKILLS_INTEGRATION.md for the full Vercel Skills setup and maintenance notes.

Scheduled Work And Heartbeats

Create recurring local runs:

/schedule examples
/schedule add daily 09:00 | Daily repo health check | Inspect git status, tests, and risks.
/schedule add daily 08:00 @ America/Montreal | Morning brief | Send a compact morning report.
/schedule list
/schedule pause <id>
/schedule resume <id>

The agent can also create and edit Libre Claw schedules itself with the schedule_list and schedule tools. These are daemon automations, not host cron entries, so they stay portable across TUI, dashboard, and Telegram. Use an IANA timezone suffix such as @ America/Montreal for location-specific jobs; otherwise schedules use the daemon's local timezone.

Scheduled runs are bounded by the [automations] settings in ~/.libre-claw/config.toml. Libre Claw limits concurrent runs, preserves time for a final response, gives partial-report finalization its own timeout, and backs off a provider after confirmed quota or rate-limit failures. Adjust max_concurrent_runs, run_timeout_seconds, deadline_reserve_seconds, and the provider cooldown values when operating under tighter service limits.

Start lightweight periodic check-ins:

/heartbeat status
/heartbeat once
/heartbeat start every 30 minutes
/heartbeat stop

Goal Mode

Use /goal for bounded autopilot work:

/goal Fix the failing tests and explain the result

Libre Claw runs a normal agent turn, asks a separate judge model whether the goal is complete, then continues until the judge marks it done or the turn limit is reached.

Important Slash Commands

/help
/clear
/cancel
/exit
/cost
/compact
/model [provider:]<model> [--global]
/fallback list|set|clear|recheck
/provider <name>
/setup status
/tools list
/runs
/memory status
/skills list
/workspace status
/telegram
/petdex status

Keybindings:

• Ctrl+B: toggle file explorer.
• Ctrl+P: command palette.
• Ctrl+Shift+C: copy last assistant response.
• Esc: cancel active generation/tool execution.
• Ctrl+C: exit the app.
• Tab: accept the first slash-command suggestion.

Configuration

Main config:

~/.libre-claw/config.toml

Show bundled defaults:

libre-claw config defaults

Common environment overrides:

LIBRE_CLAW_DEFAULT_PROVIDER=openrouter
LIBRE_CLAW_DEFAULT_MODEL=openrouter/auto
LIBRE_CLAW_WORKING_DIRECTORY=/path/to/project

Initialize a dedicated workspace:

libre-claw workspace init

By default, this creates:

~/Documents/.workspace/libre-claw

Safety Model

Libre Claw is powerful because it can touch your files, shell, browser, and git history. The default posture is local-first and permissioned:

• API keys are read from environment variables, keyring, or encrypted local fallback storage.
• Provider keys are not written to project config files.
• File writes, edits, shell commands, browser navigation/actions, downloads, git commits, and MCP actions ask for approval.
• Dangerous shell patterns are blocked by the sandbox layer.
• File access is restricted to the configured working directory by default.
• Memory redacts credential-looking strings before indexing or prompt injection.
• Runs are append-only and inspectable through JSONL logs and artifacts.

Troubleshooting

macOS says externally-managed-environment

Use a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

Missing API key

libre-claw auth status
libre-claw auth set-key openrouter

Replace openrouter with moonshot, anthropic, openai, or ollama. For Codex:

libre-claw auth codex-login

Ollama Cloud returns 401

Make sure you stored the real Ollama API key, not the model name:

libre-claw auth set-key ollama

For direct Ollama Cloud API use:

[providers.ollama]
base_url = "https://ollama.com"
api_format = "ollama"
api_key_env = "OLLAMA_API_KEY"

For local Ollama daemon use:

[providers.ollama]
base_url = "http://localhost:11434"
api_format = "ollama"
api_key_env = ""

Documentation

• Website: libreclaw.sh
• Docs: libreclaw.sh/docs
• Getting started: docs/GETTING_STARTED.md
• Kimi Code and Moonshot integration: docs/MOONSHOT_KIMI.md
• SearXNG integration: docs/SEARXNG_INTEGRATION.md
• Vercel Skills integration: docs/VERCEL_SKILLS_INTEGRATION.md
• Security: SECURITY.md
• Roadmap: ROADMAP.md
• Demos: docs/DEMOS.md

Development

python -m pytest
python -m compileall src tests
git diff --check

Libre Claw is released under Apache-2.0 by Kroonen AI.