librecode is a small, local-first terminal AI agent.
No sandbox. No MCP. No permission prompts. No marketplace. No telemetry.
Just a model, your shell, and seven tools that do what they say, designed for developers who'd rather review their own diffs than click through approval dialogs.
Important
librecode is pre-release software. Expect bugs, rough edges, breaking changes, half-finished surfaces, and the occasional crash. APIs, config keys, and on-disk formats may shift without notice until 1.0. If you need stability, wait. If you want to help shape it, jump in: issues and PRs welcome.
The agent CLI space is moving toward more layers: permission models, sandboxed tool servers, plugin marketplaces, extension protocols. Those are reasonable choices for some teams. librecode is the smaller, simpler alternative for people who want fewer of them.
No MCP. Built-in tools plus optional Lua extensions are the entire surface area. Fewer moving parts, no separate servers to manage.No sandbox. Tools run with your permissions, in your shell, against your files. You decide what to run librecode against.No permission prompts. The agent acts within the project you launched it in, without interrupting to confirm each step.Bring your own model. OAuth into ChatGPT/Codex or Claude Pro/Max, use an API key for anything OpenAI-compatible, or define your own provider.One binary. Static Go. No Node, no Python venv, no Electron. Fast cold start, no background services.Local everything. Sessions in a SQLite file, auth in a JSON file. Project-local.librecode/
keeps state scoped to the repo.
It's a direct, capable tool. Treat it like one.
Interactive terminal chat: streaming output, visible reasoning blocks, chronological tool activity, scrollback, prompt history, mouse selection, configurable text.Seven built-in tools:read
,write
,edit
,bash
,grep
,find
,ls
. A small toolkit that covers most coding workflows.Persistent SQLite sessions: branchable, resumable, listable. Per-project or global.** Agent Skills support**: drop aSKILL.md
in.librecode/skills/
or.agents/skills/
and it's discoverable. Autocomplete and explicit/skill:<name>
included.Provider/model registry: OAuth for ChatGPT/Codex and Claude Pro/Max, API-key providers, automatic retries on transient failures, custom provider definitions.Lua extensions: an optional layer for commands, key interception, buffer mutation, and event hooks. Trusted local code rather than a plugin marketplace.YAML config + env vars: sane defaults and strict validation.
librecode executes shell commands and edits files as the model requests them, without per-action confirmation prompts. That's the design: it keeps the loop fast and the surface area small, but it's worth being explicit about.
A few suggestions for using it comfortably:
- Run it in workspaces you own, ideally under version control, so changes are easy to review and revert.
- Use models you've found reliable for the kind of work you're asking for.
- Treat a librecode session like running a script from an unfamiliar repo: fine when you've decided to trust it, worth pausing on when you haven't.
If you'd prefer per-action approval, sandboxing, or policy enforcement, other agent CLIs offer that and may suit you better.
git clone https://github.com/omarluq/librecode.git
cd librecode
mise install # optional: install the pinned Go/Task/golangci-lint/lefthook versions
task build # writes ./bin/librecode
./bin/librecode --help
If you do not use mise
, install a Go toolchain matching go.mod
and Task yourself.
go install github.com/omarluq/librecode/cmd/librecode@latest
Open a fresh interactive chat session:
librecode
Resume the latest session for the current working directory:
librecode --resume
librecode chat --resume
Send a one-shot prompt:
librecode prompt "summarize this repo"
librecode prompt --resume "continue from the last session"
Run a built-in tool directly:
librecode tool list
librecode tool run read '{"path":"README.md"}'
librecode tool run bash '{"command":"go test ./...","timeout":120}'
Manage sessions:
librecode session new "docs pass"
librecode session list
librecode session show <session-id>
Built-in provider IDs:
| Provider | Auth | API family |
|---|---|---|
openai-codex |
||
| Browser OAuth for ChatGPT Plus/Pro | Codex Responses | |
openai |
||
| API key | OpenAI Responses | |
anthropic-claude |
||
| Browser OAuth for Claude Pro/Max | Anthropic Messages | |
anthropic |
||
| API key | Anthropic Messages | |
azure-openai-responses |
||
| API key/custom config | OpenAI Responses | |
| OpenAI-compatible providers | API key | Chat Completions-compatible |
OpenAI-compatible built-ins: cerebras
, deepseek
, groq
, mistral
, moonshotai
, moonshotai-cn
, openrouter
, vercel-ai-gateway
, xai
, and zai
.
The default assistant config is:
assistant:
provider: openai-codex
model: gpt-5.5
thinking_level: off
retry:
enabled: true
max_attempts: 3
base_delay: 2s
max_delay: 30s
Built-in providers are intentionally limited to API families librecode implements directly: OpenAI/Codex Responses, OpenAI-compatible chat completions, and Anthropic Messages. Additional providers can still be added through custom model/provider definitions.
Credentials can come from:
/login openai-codex
for ChatGPT/Codex subscription OAuth;/login anthropic-claude
for Claude Pro/Max OAuth;/login <provider> <api-key>
for API-key providers such asanthropic
,openai
,openrouter
, orzai
;- provider-specific environment variables such as
OPENAI_API_KEY
,ANTHROPIC_API_KEY
,ANTHROPIC_OAUTH_TOKEN
,OPENROUTER_API_KEY
, orZAI_API_KEY
; - custom provider config stored in the runtime model document.
Provider IDs are configured with LIBRECODE_ASSISTANT_PROVIDER
or assistant.provider
; model IDs use LIBRECODE_ASSISTANT_MODEL
or assistant.model
.
librecode resolves config in this order:
--config <path>
LIBRECODE_*
environment variables./.librecode/config.yaml
~/.librecode/config.yaml
or$LIBRECODE_HOME/config.yaml
- built-in defaults
Useful commands:
librecode config show
librecode config validate
See config.example.yaml for all current config keys. The in-progress text defaults to
Shenaniganing...
and is configurable with app.working_.text
.Built-in memory limits protect untrusted input and remote bodies: prompt stdin and tool JSON stdin are capped at 1 MiB, provider response/error bodies at 16 MiB, and ksqlDB response bodies at 8 MiB.
Default global persistence lives under one librecode home:
- librecode home:
~/.librecode
or$LIBRECODE_HOME
-
config:
~/.librecode/config.yaml -
sessions database:
~/.librecode/librecode.db -
auth storage:
~/.librecode/auth.json
Project-local overrides live under ./.librecode/
too. If ./.librecode/auth.json
or ./.librecode/librecode.db
exists, librecode uses it instead of the global file for that project.
Skills are Agent Skills-compatible directories containing SKILL.md
. Skill metadata is always advertised to the model, and matching skills can be auto-activated by their full SKILL.md
into the request context.
Default skill roots, in priority order:
./.librecode/skills
./.agents/skills
~/.librecode/skills
~/.agents/skills
Duplicate skill names are deduped by priority, so project-local .librecode
skills win over project .agents
and user-global skills. Discovery honors .gitignore
, .ignore
, and .fdignore
files inside skill roots.
A minimal skill looks like:
---
name: my-skill
description: Use when working on my project-specific workflow.
license: MIT
compatibility: Works with librecode and Agent Skills-compatible agents.
allowed-tools: Read Bash(git:*)
metadata:
author: me
---
Follow these project-specific instructions...
Useful commands:
librecode skill list
librecode skill show my-skill
librecode skill validate
Inside chat, /skill
lists discovered skills. Use /skill my-skill
or /skill:my-skill
to load a skill through the read-tool path and render a loaded skill my-skill
block. User-invocable skills also appear in slash autocomplete as /skill:<name>
.
Extensions are trusted local code that runs in the same process as librecode. Lua is the first supported runtime; the host is designed so additional runtimes can be added later. Because extensions have direct access to runtime state, only install ones you've reviewed or trust the source of.
Extensions are declared with extensions.use
in config. The default source is:
extensions:
enabled: true
use:
- path:.librecode/extensions
The extension manager interface supports source strings and object entries with versions:
extensions:
use:
- official:vim-mode
- github:example/librecode-extension
- github:example/monorepo//extensions/fancy
- path:.librecode/extensions/local-dev
- source: github:example/librecode-extension
version: v1.2.3
Startup loads only entries declared in extensions.use
; extra directories on disk are ignored. path:
sources load from disk today, while official:
and github:
sources are installed and pinned by the extension manager.
The default chat UI is Go-owned and extensions are optional customization. Use --no-extensions
to disable configured extensions for a single run.
Current extension capabilities include:
- registering commands and extension-backed tools;
- listening to low-level runtime events;
- intercepting key input with priorities;
- reading and mutating runtime buffers such as
composer
,status
,transcript
,thinking
, andtools
; - creating namespaces, autocmds, and keymaps through a Neovim-inspired Lua API.
For architecture, roadmap, and API details, see:
docs/adr/0001-programmable-runtime.md
docs/runtime-architecture.md
docs/session-context.md
docs/extension-runtime.md
docs/extension-manager.md
docs/extension-roadmap.md
docs/extension-api.md
docs/rendering-boundary.md
docs/skills.md
Inspect and manage extensions:
librecode extension list
librecode extension add <source> [--version vX.Y.Z]
librecode extension remove <source-or-name>
librecode extension install
librecode extension update
librecode extension tidy
librecode extension doctor
librecode extension run <command> [args...]
Seven tools, kept deliberately small. No registry, marketplace, or external server lifecycle to manage.
| Tool | Mutates? | Purpose |
|---|---|---|
read |
||
| No | Read text/image files with truncation controls. | |
ls |
||
| No | List directory entries. | |
find |
||
| No | Search file paths by glob. | |
grep |
||
| No | Search file contents. | |
write |
||
| Yes | ||
| Overwrite/create files. | ||
edit |
||
| Yes | ||
| Exact text replacement with uniqueness checks. | ||
bash |
||
| Yes | ||
| Execute shell commands with timeout/output limits. |
The bash
tool executes commands directly in your shell with the permissions of the librecode process. There is no allowlist or interactive confirmation.
On Windows, the bash
tool requires a real Bash shell rather than cmd.exe
. librecode checks LIBRECODE_BASH_PATH
, common Git Bash install paths, then bash.exe
on PATH
. Native Windows users should install Git Bash/MSYS2/Cygwin or run librecode from WSL.
librecode [--resume] [--config path] [--no-extensions]
librecode chat [--resume | --session id]
librecode prompt [--resume | --session id | --name name] [message]
librecode session new [name]
librecode session list
librecode session show <session-id>
librecode skill list
librecode skill show <name>
librecode skill validate
librecode tool list
librecode tool run <name> [json-args|-] [--cwd path]
librecode extension list
librecode extension add <source> [--version vX.Y.Z]
librecode extension remove <source-or-name>
librecode extension install
librecode extension update
librecode extension tidy
librecode extension doctor
librecode extension run <command> [args...]
librecode config show
librecode config validate
librecode migrate
librecode version
Use librecode <command> --help
for exact flags and subcommands.
task # list tasks
task build # build ./bin/librecode
task run # build and run
task test # go test -race ./...
task test-short # short race-enabled tests
task test-coverage # coverage.out + coverage.html
task lint # golangci-lint run
task fmt # auto-format and auto-fix lint issues
task fmt-check # check formatting without modifying files
task ci # fmt-check + lint + test + build, non-mutating
task tidy # go mod tidy
task clean # remove build/test/cache artifacts
Project-local caches are used for reproducible local runs and are gitignored:
.gocache/
.gomodcache/
.tmp/
cmd/librecode/ CLI commands and process entrypoint
internal/assistant/ Prompt orchestration, provider calls, tool loop, cache integration
internal/auth/ Provider credential storage, OAuth flows, and token refresh
internal/config/ Viper config defaults, , and validation
internal/core/ Resources: system prompts, context files, skills, slash prompts
internal/database/ SQLite repositories, migrations, ksqlDB client
internal/di/ Service wiring with samber/do
internal/extension/ Extension host and Lua runtime API bridge
internal/model/ Provider/model registry and auth resolution
internal/terminal/ Interactive terminal UI
internal/tool/ Built-in coding tools
internal/vinfo/ Version metadata injected at build time
Releases are built by GoReleaser from v*.*.*
tags:
git tag v0.1.0
git push origin v0.1.0
The release workflow cross-compiles Linux, macOS, and Windows binaries, archives them, generates checksums, and publishes a GitHub release.
MIT. See LICENSE.txt.