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 local 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.
Cordis engine	Persistent services coordinate agents, providers, tools, sessions, memory, and workflows. The dashboard has its own Cordis UI graph. Architecture.
Cordis plugins	Import compiled Harness/Cordis packages, configure components, and run isolated tools or services with explicit project grants. Guide.
Model orchestration	Choose an orchestrator and worker models across providers; run scoped scouts, builders, and reviewers concurrently. Setup.
Real tools	File edits, shell, code search, web search, git, HTTP requests, browser actions, screenshots, MCP tools, and more.
Provider routing	DeepSeek, 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.

Coding Workflows

Continue saved conversations, load scoped AGENTS.md instructions, isolate tasks in Git worktrees, review files and hunks, edit plans, steer or queue follow-ups, and delegate scoped work. Model discovery also exposes provider capabilities. See the coding workflow guide for commands and limits, and the implementation checklist for verification.

Install

Libre Claw uses Python 3.11+, pip, and Node.js for its Cordis engine. Use Node 22.19+ on macOS with sandbox-exec, or Node 25+ on Linux for enforced offline execution. Check your setup with libre-claw engine check. Run the commands below from the app repository. Python installs the application; the root pnpm workspace manages its JavaScript build tools. The website has its own repository and dependencies.

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]"

To rebuild and package the application, keep that virtual environment active and use the pinned pnpm version from package.json:

pnpm install --frozen-lockfile
pnpm run build
pnpm run test:runtime
pnpm run package

pnpm run package produces the wheel, source archive, checksums, and an artifact manifest in dist/. CI checks the generated bundles, runs Python and Node tests, validates the archives, then installs the wheel outside the checkout and checks both CLI commands and the offline engine. Download the libre-claw-dist artifact from a successful CI run. See the packaging guide for details.

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

Use libre-claw --help for grouped commands and examples. libre-claw status shows the configured workspace, model, theme, config files, and live daemon health; add --json for scripts. Run a single task with libre-claw run "Review the changes", or pipe a prompt into libre-claw run.

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.

Ctrl+P opens the command picker beside the composer. Use Up/Down to choose, Tab to fill the command, Enter to select it, and Escape to close. Contextual hints show the available keys; narrow terminals keep more room for the chat.

The default Libre Claw theme matches the website: warm charcoal, copper accents, and monospace type. Use /theme libre-light --global for the cream variant, or /theme libre --global to return to dark. The global choice also sets the dashboard theme; its Settings panel offers the same themes. All named themes share Libre's typography, square controls, and panel styling while keeping their own color palettes. Find them with /theme list.

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 deepseek
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 DEEPSEEK_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.

For direct DeepSeek access, run /setup key deepseek, then /setup deepseek. Use /models deepseek to discover available models. See the DeepSeek guide for thinking settings and image support.

For OpenCode Zen or Go, use libre-claw auth connect-opencode opencode or libre-claw auth connect-opencode opencode-go, then discover models with /models <provider>. Existing OpenCode API keys can be imported explicitly. See the OpenCode authentication and provider guide.

Prompt caching is configured automatically for supported providers. See the caching guide for controls and cache usage reports.

Choose A Model

Libre Claw discovers models from your provider instead of maintaining a list of model releases. The TUI, Telegram picker, and dashboard use the same catalog.

/models
/models openrouter
/models openrouter <search>
/models ollama --refresh
/model <provider>:<model-id> --global

/models uses the current provider; /model list is an alias. Results are cached, and --refresh fetches the latest catalog. Autocomplete uses discovered models alongside your configured IDs. You can always enter an ID directly, even when the provider is offline or does not expose a model list.

Discovery uses the configured endpoint and credentials for each provider. Codex uses its installed CLI and local model metadata. Provider availability and model capabilities depend on your account and endpoint.

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 deepseek
/provider moonshot
/provider ollama
/provider anthropic
/provider openai
/provider codex

Codex / ChatGPT Login

The codex provider uses the installed Codex CLI and its ChatGPT OAuth session:

libre-claw auth codex-login
libre-claw auth codex-status

Device sign-in must be enabled in your ChatGPT security settings or workspace permissions. For browser login, use libre-claw auth codex-login --browser. Codex stores and refreshes its own credentials; Libre Claw does not import tokens.

Inside the TUI:

/codex login
/provider codex
/models codex
/model codex:gpt-6-sol --global

Use /codex login browser for the browser flow. GPT-6 model IDs are gpt-6-luna, gpt-6-sol, and gpt-6-astra; availability depends on the CLI, signed-in account, rollout, and workspace. The picker discovers models from the installed CLI. See Codex setup and verification.

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 deepseek, 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
• DeepSeek integration: docs/DEEPSEEK.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.