@garuda-agent/garuda

中文文档
0.20.2发布于 2026/11/14Apache-2.0ES Module构建来源已验证近 30 天下载 1959

Garuda: a terminal coding agent with an OS sandbox, approvals and an audit log.

原始使用文档
文档目录6 节
  1. What Garuda does on your machine
  2. Install
  3. Quick start
  4. User guide
  5. Contributing
  6. License

Garuda

CI

Website and docs: https://madhu-sv.github.io/garuda/

Garuda is a coding agent for the terminal, and for editors over the Agent Client Protocol. It reads and edits your code, runs commands in an OS sandbox, and keeps an audit log of its permission decisions. It works with Claude and with OpenAI-compatible models, local ones too. This is version 0.20.2. Release notes: CHANGELOG.md.

What Garuda does on your machine

  • read_file, glob and grep run with no question.
  • write_file and edit_file show a diff first. You allow once, allow for this session, or deny.
  • Commands (bash) run in an OS sandbox when your machine has one: Seatbelt on macOS, bubblewrap on Linux. There they run with no question, but they can write only in the project, temp folders and package caches, cannot read secrets in your home folder (such as ~/.ssh) or your personal folders (Documents, Downloads, Pictures and the like, outside the project), and have no network unless you open an allowlist. So a command can change project files without a question; /undo restores the files in its snapshot (ignored files, such as build output, are not in it).
  • A command outside the sandbox asks first, unless one of your allow rules covers it. The strict profile forbids it. Without a sandbox, each command asks first, unless one of your allow rules covers it.
  • With staged commands (0.17, off by default), a sandboxed command runs in a copy of the project, and its changes reach the project only after you apply them.

The details: Sandbox, permissions and policy. The known gaps: Status and known limits and the issue register.

Install

You need Node 22.23.4, 24.22.1 or 26.12.1, or a later release of the same line: the latest security release of a supported line (Homebrew installs it). Garuda warns at start on an older Node.

npm install -g @garuda-agent/garuda

Or with Homebrew (macOS and Linux). Homebrew loads a formula from a third-party tap only after you trust it, so trust the Garuda formula first:

brew tap madhu-sv/garuda
brew trust --formula madhu-sv/garuda/garuda
brew install garuda

To build from source, see CONTRIBUTING.md. Native Windows is not supported; use WSL.

Quick start

garuda setup                            # once: pick a provider and model, enter the key
garuda                                  # chat in the current folder
garuda -p "Explain what this repo does" # run one task and exit
echo "Explain this repo" | garuda       # the same, from stdin

garuda setup stores the model in ~/.garuda/models.json and the key in ~/.garuda/credentials (mode 0600; commands in the sandbox cannot read it). ANTHROPIC_API_KEY and GARUDA_MODEL in the environment still work and win.

User guide

PageWhat it covers
Install and first runInstall, garuda setup, the chat, one task, JSON output for scripts, the standalone binary.
ModelsClaude, OpenAI-compatible providers, local models, prices and context windows.
Chat, sessions and undoThe chat's keys and commands, sessions, limits, context, plan mode, undo, the todo list.
EditorsZed, JetBrains, Neovim, Emacs and VS Code over the Agent Client Protocol.
Project instructions, commands, skills and agentsgaruda init, custom slash commands, skills, custom agents, subagents, Java and Python projects.
Sandbox, permissions and policyThe OS sandbox, the network allowlist, staged commands, permissions, hooks, the team policy, the audit log.
MCP, web and code intelligenceMCP servers, web fetch and search, the code index, language plugins, LSP diagnostics, formatters.
Scheduled jobs and the night shiftPlan now, build later on its own branch, with tests before and after and a review.
EvalsMeasure a model or a setting on eval tasks, also tasks from your repo's history.
Status and known limitsWhat each release added, and the known limits of this version.

Design documents: docs/ (architecture, high-level design, low-level design per component). The requirements doc defines the scope; code, tests and commits refer to its IDs (F1–F26, N1–N8).

Contributing

Contributions are welcome. Read CONTRIBUTING.md first: how to build, test and send a pull request. Everyone who takes part follows the Code of Conduct. To report a security problem, see SECURITY.md; do not open a public issue for it.

License

Garuda is licensed under the Apache License, Version 2.0. See NOTICE.

版本与发布记录

@garuda-agent/garuda 共发布 14 个版本,首次发布于 2026/10/06;过去 12 个月发布了 14 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.20.2latest2026/11/142 天前
0.20.12026/11/123 天前
0.20.02026/11/115 天前
0.19.12026/11/096 天前
0.19.02026/11/079 天前
0.18.22026/11/079 天前

关于 @garuda-agent/garuda 的常见问题

@garuda-agent/garuda 是什么?

Garuda: a terminal coding agent with an OS sandbox, approvals and an audit log.

如何安装 @garuda-agent/garuda?

在项目目录运行 npm install @garuda-agent/garuda,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 garuda,可以用 npx garuda 直接运行。

@garuda-agent/garuda 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/garuda-agent__garuda 是否存在。

@garuda-agent/garuda 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@garuda-agent/garuda 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js ^22.23.4 || ^24.22.1 || >=26.12.1。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@garuda-agent/garuda 可以商用吗?

@garuda-agent/garuda 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@garuda-agent/garuda 的下载量有多少?

根据 npm 官方下载统计,@garuda-agent/garuda 在 2026/10/16 – 2026/11/14 这 30 天内被下载 1,959 次,日均约 65 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@garuda-agent/garuda 还在维护吗?

最新版本 0.20.2 发布于 2026/11/14(2 天前);至今共发布 14 个版本,其中过去 12 个月发布了 14 个;首次发布于 2026/10/06。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。