{"slug": "librecode-yet-another-agent-harness", "title": "Librecode (Yet Another Agent Harness)", "summary": "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.", "body_md": "**librecode is a small, local-first terminal AI agent.**\n\nNo sandbox. No MCP. No permission prompts. No marketplace. No telemetry.\n\nJust 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.\n\nImportant\n\nlibrecode 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.\n\nThe 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.\n\n**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/`\n\nkeeps state scoped to the repo.\n\nIt's a direct, capable tool. Treat it like one.\n\n**Interactive terminal chat**: streaming output, visible reasoning blocks, chronological tool activity, scrollback, prompt history, mouse selection, configurable loader text.**Seven built-in tools**:`read`\n\n,`write`\n\n,`edit`\n\n,`bash`\n\n,`grep`\n\n,`find`\n\n,`ls`\n\n. 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`\n\nin`.librecode/skills/`\n\nor`.agents/skills/`\n\nand it's discoverable. Autocomplete and explicit`/skill:<name>`\n\nloading 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.\n\nlibrecode 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.\n\nA few suggestions for using it comfortably:\n\n- Run it in workspaces you own, ideally under version control, so changes are easy to review and revert.\n- Use models you've found reliable for the kind of work you're asking for.\n- 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.\n\nIf you'd prefer per-action approval, sandboxing, or policy enforcement, other agent CLIs offer that and may suit you better.\n\n```\ngit clone https://github.com/omarluq/librecode.git\ncd librecode\nmise install          # optional: install the pinned Go/Task/golangci-lint/lefthook versions\ntask build            # writes ./bin/librecode\n./bin/librecode --help\n```\n\nIf you do not use `mise`\n\n, install a Go toolchain matching `go.mod`\n\nand [Task](https://taskfile.dev/) yourself.\n\n```\ngo install github.com/omarluq/librecode/cmd/librecode@latest\n```\n\nOpen a fresh interactive chat session:\n\n```\nlibrecode\n```\n\nResume the latest session for the current working directory:\n\n```\nlibrecode --resume\n# or\nlibrecode chat --resume\n```\n\nSend a one-shot prompt:\n\n```\nlibrecode prompt \"summarize this repo\"\nlibrecode prompt --resume \"continue from the last session\"\n```\n\nRun a built-in tool directly:\n\n```\nlibrecode tool list\nlibrecode tool run read '{\"path\":\"README.md\"}'\nlibrecode tool run bash '{\"command\":\"go test ./...\",\"timeout\":120}'\n```\n\nManage sessions:\n\n```\nlibrecode session new \"docs pass\"\nlibrecode session list\nlibrecode session show <session-id>\n```\n\nBuilt-in provider IDs:\n\n| Provider | Auth | API family |\n|---|---|---|\n`openai-codex` |\nBrowser OAuth for ChatGPT Plus/Pro | Codex Responses |\n`openai` |\nAPI key | OpenAI Responses |\n`anthropic-claude` |\nBrowser OAuth for Claude Pro/Max | Anthropic Messages |\n`anthropic` |\nAPI key | Anthropic Messages |\n`azure-openai-responses` |\nAPI key/custom config | OpenAI Responses |\n| OpenAI-compatible providers | API key | Chat Completions-compatible |\n\nOpenAI-compatible built-ins: `cerebras`\n\n, `deepseek`\n\n, `groq`\n\n, `mistral`\n\n, `moonshotai`\n\n, `moonshotai-cn`\n\n, `openrouter`\n\n, `vercel-ai-gateway`\n\n, `xai`\n\n, and `zai`\n\n.\n\nThe default assistant config is:\n\n```\nassistant:\n  provider: openai-codex\n  model: gpt-5.5\n  thinking_level: off\n  retry:\n    enabled: true\n    max_attempts: 3\n    base_delay: 2s\n    max_delay: 30s\n```\n\nBuilt-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.\n\nCredentials can come from:\n\n`/login openai-codex`\n\nfor ChatGPT/Codex subscription OAuth;`/login anthropic-claude`\n\nfor Claude Pro/Max OAuth;`/login <provider> <api-key>`\n\nfor API-key providers such as`anthropic`\n\n,`openai`\n\n,`openrouter`\n\n, or`zai`\n\n;- provider-specific environment variables such as\n`OPENAI_API_KEY`\n\n,`ANTHROPIC_API_KEY`\n\n,`ANTHROPIC_OAUTH_TOKEN`\n\n,`OPENROUTER_API_KEY`\n\n, or`ZAI_API_KEY`\n\n; - custom provider config stored in the runtime model document.\n\nProvider IDs are configured with `LIBRECODE_ASSISTANT_PROVIDER`\n\nor `assistant.provider`\n\n; model IDs use `LIBRECODE_ASSISTANT_MODEL`\n\nor `assistant.model`\n\n.\n\nlibrecode resolves config in this order:\n\n`--config <path>`\n\n`LIBRECODE_*`\n\nenvironment variables`./.librecode/config.yaml`\n\n`~/.librecode/config.yaml`\n\nor`$LIBRECODE_HOME/config.yaml`\n\n- built-in defaults\n\nUseful commands:\n\n```\nlibrecode config show\nlibrecode config validate\n```\n\nSee [ config.example.yaml](/omarluq/librecode/blob/main/config.example.yaml) for all current config keys. The in-progress loader text defaults to\n\n`Shenaniganing...`\n\nand is configurable with `app.working_loader.text`\n\n.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.\n\nDefault global persistence lives under one librecode home:\n\n- librecode home:\n`~/.librecode`\n\nor`$LIBRECODE_HOME`\n\n- config:\n`~/.librecode/config.yaml`\n\n- sessions database:\n`~/.librecode/librecode.db`\n\n- auth storage:\n`~/.librecode/auth.json`\n\nProject-local overrides live under `./.librecode/`\n\ntoo. If `./.librecode/auth.json`\n\nor `./.librecode/librecode.db`\n\nexists, librecode uses it instead of the global file for that project.\n\nSkills are Agent Skills-compatible directories containing `SKILL.md`\n\n. Skill metadata is always advertised to the model, and matching skills can be auto-activated by loading their full `SKILL.md`\n\ninto the request context.\n\nDefault skill roots, in priority order:\n\n`./.librecode/skills`\n\n`./.agents/skills`\n\n`~/.librecode/skills`\n\n`~/.agents/skills`\n\nDuplicate skill names are deduped by priority, so project-local `.librecode`\n\nskills win over project `.agents`\n\nand user-global skills. Discovery honors `.gitignore`\n\n, `.ignore`\n\n, and `.fdignore`\n\nfiles inside skill roots.\n\nA minimal skill looks like:\n\n```\n---\nname: my-skill\ndescription: Use when working on my project-specific workflow.\nlicense: MIT\ncompatibility: Works with librecode and Agent Skills-compatible agents.\nallowed-tools: Read Bash(git:*)\nmetadata:\n  author: me\n---\n\nFollow these project-specific instructions...\n```\n\nUseful commands:\n\n```\nlibrecode skill list\nlibrecode skill show my-skill\nlibrecode skill validate\n```\n\nInside chat, `/skill`\n\nlists discovered skills. Use `/skill my-skill`\n\nor `/skill:my-skill`\n\nto load a skill through the read-tool path and render a `loaded skill my-skill`\n\nblock. User-invocable skills also appear in slash autocomplete as `/skill:<name>`\n\n.\n\nExtensions 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.\n\nExtensions are declared with `extensions.use`\n\nin config. The default source is:\n\n```\nextensions:\n  enabled: true\n  use:\n    - path:.librecode/extensions\n```\n\nThe extension manager interface supports source strings and object entries with versions:\n\n```\nextensions:\n  use:\n    - official:vim-mode\n    - github:example/librecode-extension\n    - github:example/monorepo//extensions/fancy\n    - path:.librecode/extensions/local-dev\n    - source: github:example/librecode-extension\n      version: v1.2.3\n```\n\nStartup loads only entries declared in `extensions.use`\n\n; extra directories on disk are ignored. `path:`\n\nsources load from disk today, while `official:`\n\nand `github:`\n\nsources are installed and pinned by the extension manager.\n\nThe default chat UI is Go-owned and extensions are optional customization. Use `--no-extensions`\n\nto disable configured extensions for a single run.\n\nCurrent extension capabilities include:\n\n- registering commands and extension-backed tools;\n- listening to low-level runtime events;\n- intercepting key input with priorities;\n- reading and mutating runtime buffers such as\n`composer`\n\n,`status`\n\n,`transcript`\n\n,`thinking`\n\n, and`tools`\n\n; - creating namespaces, autocmds, and keymaps through a Neovim-inspired Lua API.\n\nFor architecture, roadmap, and API details, see:\n\n`docs/adr/0001-programmable-runtime.md`\n\n`docs/runtime-architecture.md`\n\n`docs/session-context.md`\n\n`docs/extension-runtime.md`\n\n`docs/extension-manager.md`\n\n`docs/extension-roadmap.md`\n\n`docs/extension-api.md`\n\n`docs/rendering-boundary.md`\n\n`docs/skills.md`\n\nInspect and manage extensions:\n\n```\nlibrecode extension list\nlibrecode extension add <source> [--version vX.Y.Z]\nlibrecode extension remove <source-or-name>\nlibrecode extension install\nlibrecode extension update\nlibrecode extension tidy\nlibrecode extension doctor\nlibrecode extension run <command> [args...]\n```\n\nSeven tools, kept deliberately small. No registry, marketplace, or external server lifecycle to manage.\n\n| Tool | Mutates? | Purpose |\n|---|---|---|\n`read` |\nNo | Read text/image files with truncation controls. |\n`ls` |\nNo | List directory entries. |\n`find` |\nNo | Search file paths by glob. |\n`grep` |\nNo | Search file contents. |\n`write` |\nYes |\nOverwrite/create files. |\n`edit` |\nYes |\nExact text replacement with uniqueness checks. |\n`bash` |\nYes |\nExecute shell commands with timeout/output limits. |\n\nThe `bash`\n\ntool executes commands directly in your shell with the permissions of the librecode process. There is no allowlist or interactive confirmation.\n\nOn Windows, the `bash`\n\ntool requires a real Bash shell rather than `cmd.exe`\n\n. librecode checks `LIBRECODE_BASH_PATH`\n\n, common Git Bash install paths, then `bash.exe`\n\non `PATH`\n\n. Native Windows users should install Git Bash/MSYS2/Cygwin or run librecode from WSL.\n\n```\nlibrecode [--resume] [--config path] [--no-extensions]\nlibrecode chat [--resume | --session id]\nlibrecode prompt [--resume | --session id | --name name] [message]\nlibrecode session new [name]\nlibrecode session list\nlibrecode session show <session-id>\nlibrecode skill list\nlibrecode skill show <name>\nlibrecode skill validate\nlibrecode tool list\nlibrecode tool run <name> [json-args|-] [--cwd path]\nlibrecode extension list\nlibrecode extension add <source> [--version vX.Y.Z]\nlibrecode extension remove <source-or-name>\nlibrecode extension install\nlibrecode extension update\nlibrecode extension tidy\nlibrecode extension doctor\nlibrecode extension run <command> [args...]\nlibrecode config show\nlibrecode config validate\nlibrecode migrate\nlibrecode version\n```\n\nUse `librecode <command> --help`\n\nfor exact flags and subcommands.\n\n```\ntask              # list tasks\ntask build        # build ./bin/librecode\ntask run          # build and run\ntask test         # go test -race ./...\ntask test-short   # short race-enabled tests\ntask test-coverage # coverage.out + coverage.html\ntask lint         # golangci-lint run\ntask fmt          # auto-format and auto-fix lint issues\ntask fmt-check    # check formatting without modifying files\ntask ci           # fmt-check + lint + test + build, non-mutating\ntask tidy         # go mod tidy\ntask clean        # remove build/test/cache artifacts\n```\n\nProject-local caches are used for reproducible local runs and are gitignored:\n\n`.gocache/`\n\n`.gomodcache/`\n\n`.tmp/`\n\n```\ncmd/librecode/          CLI commands and process entrypoint\ninternal/assistant/     Prompt orchestration, provider calls, tool loop, cache integration\ninternal/auth/          Provider credential storage, OAuth flows, and token refresh\ninternal/config/        Viper config defaults, loading, and validation\ninternal/core/          Resources: system prompts, context files, skills, slash prompts\ninternal/database/      SQLite repositories, migrations, ksqlDB client\ninternal/di/            Service wiring with samber/do\ninternal/extension/     Extension host and Lua runtime API bridge\ninternal/model/         Provider/model registry and auth resolution\ninternal/terminal/      Interactive terminal UI\ninternal/tool/          Built-in coding tools\ninternal/vinfo/         Version metadata injected at build time\n```\n\nReleases are built by GoReleaser from `v*.*.*`\n\ntags:\n\n```\ngit tag v0.1.0\ngit push origin v0.1.0\n```\n\nThe release workflow cross-compiles Linux, macOS, and Windows binaries, archives them, generates checksums, and publishes a GitHub release.\n\nMIT. See [ LICENSE.txt](/omarluq/librecode/blob/main/LICENSE.txt).", "url": "https://wpnews.pro/news/librecode-yet-another-agent-harness", "canonical_source": "https://github.com/omarluq/librecode", "published_at": "2026-06-04 23:32:50+00:00", "updated_at": "2026-06-04 23:47:35.237991+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "ai-products", "large-language-models", "artificial-intelligence"], "entities": ["librecode", "ChatGPT", "Codex", "Claude Pro", "Claude Max", "OpenAI"], "alternates": {"html": "https://wpnews.pro/news/librecode-yet-another-agent-harness", "markdown": "https://wpnews.pro/news/librecode-yet-another-agent-harness.md", "text": "https://wpnews.pro/news/librecode-yet-another-agent-harness.txt", "jsonld": "https://wpnews.pro/news/librecode-yet-another-agent-harness.jsonld"}}