Librecode (Yet Another Agent Harness)

Librecode, a new local-first terminal AI agent, has been released as pre-release software by developer Omar Luq. The tool operates without sandboxing, MCP protocol support, permission prompts, or telemetry, instead offering seven built-in tools and optional Lua extensions for developers who prefer reviewing diffs over clicking through approval dialogs. The agent runs as a single static Go binary with local SQLite sessions and supports multiple AI model providers, positioning itself as a simpler alternative to more layered agent CLI systems.

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 loader 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 a SKILL.md in .librecode/skills/ or .agents/skills/ and it's discoverable. Autocomplete and explicit /skill:<name loading 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 https://taskfile.dev/ 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 or 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 as anthropic , openai , openrouter , or zai ;- provider-specific environment variables such as OPENAI API KEY , ANTHROPIC API KEY , ANTHROPIC OAUTH TOKEN , OPENROUTER API KEY , or ZAI 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 /omarluq/librecode/blob/main/config.example.yaml for all current config keys. The in-progress loader text defaults to Shenaniganing... and is configurable with app.working loader.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 loading 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 , and tools ; - 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, loading, 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 /omarluq/librecode/blob/main/LICENSE.txt .