Skip to main content
Glama

agentbelt

npm ci license

One install. Every AI agent. Safe tools for your real dev work.

⭐ If agentbelt is useful to you, star the repo so more developers can find it. · 📖 Guide · ✍️ Why I built it

agentbelt gives your AI coding apps the same set of safe, audited tools:

  • git with isolated task branches;

  • the project's own tests and checks;

  • workflows with approval gates.

You write them once, and they run everywhere through the Model Context Protocol (MCP). No API key and no extra LLM are needed: your AI app brings the model, agentbelt brings the tools.

npx agentbelt@0.3.0 setup

setup takes under a minute:

  1. It installs a pinned copy, with package install scripts disabled.

  2. It verifies the copy with real tool calls before activating it.

  3. It finds your AI apps (Claude Code, Codex, Cursor, VS Code, DeepSeek Harness, LM Studio, Claude Desktop, Goose), shows you each config change, and backs up each config file before changing it.

Works with

App

Status

How it connects

DeepSeek Harness

✅ verified 2026-11-13 with 0.2.2-rc.1: real tool calls

@deepseek-ai/dsh-mcp-client entry in your profile; needs setup --workspace <project> (DeepSeek gives servers no project)

Claude Code

✅ verified 2026-11-12 with Claude Code 2.1.257: real tool calls

claude mcp add-json --scope user

Codex

✅ verified 2026-11-12 with codex-cli 0.166.0: real tool calls

codex mcp add

Cursor

✅ verified 2026-11-13 with 3.30: real tool calls (open a folder first)

mcpServers.agentbelt in ~/.cursor/mcp.json (project from MCP roots: open a folder)

VS Code

✅ verified 2026-11-13 with 1.142 (Copilot agent mode)

servers.agentbelt in the user mcp.json (project from MCP roots)

Claude Desktop

config written by setup; not yet verified with a real call

mcpServers.agentbelt in claude_desktop_config.json; needs --workspace

LM Studio

✅ verified 2026-11-13 with 0.4.28 (turn on mcp/agentbelt in chat)

mcpServers.agentbelt in ~/.lmstudio/mcp.json; needs --workspace

Goose

config written by setup; not yet verified with a real call

extensions.agentbelt in ~/.config/goose/config.yaml; needs --workspace

Any MCP client

stdio server

command ~/.local/share/agentbelt/bin/agentbelt, args ["serve"]

"Verified" means the app called agentbelt tools in a real session and the result was checked in agentbelt's audit log, not just that a connection was made. See docs/compatibility.md.

Related MCP server: ContextBridge

What your AI can do with it

Tool

What it does

git_status, git_diff, git_log

Read the repository

git_task_start

Create an isolated task: a worktree in .agentbelt/worktrees/<id> on branch agentbelt/<id>

git_commit

Commit a task's changes to its agentbelt/<id> branch, never to your current branch, and never push

testing_detect, testing_run_checks

Find and run the project's own typecheck, lint, build and tests (npm, pnpm, yarn, Swift, Cargo, Go, pytest)

workflows_list, workflows_start, workflows_show, workflows_runs

Multi-step recipes like check, repo-health and safe-commit

agentbelt_status

Workspace, plugins, and how commands are isolated

Skills (in the Agent Skills format) come along as MCP prompts:

  • fix-failing-tests

  • review-diff

  • pr-description

  • repo-health

  • safe-dependency-update

Try it

Open your AI app in a project and say:

  • "Use agentbelt to run the checks and fix what fails."

  • "Review my uncommitted changes with agentbelt."

  • "Start the safe-commit workflow for task fix-login-1a2b3c."

Safety model

agentbelt is built so that a confused or manipulated model can't do much damage.

  • Permissions are enforced on every action. Plugins never touch the system directly. Every command, file read or write, and cross-tool call goes through a broker that checks the plugin's declared permissions and the core command policy:

    • arguments are passed as a list, never through a shell;

    • each program is limited to a list of allowed subcommands;

    • paths can't leave the project or reach .git.

  • No pushes, no destructive git. push, fetch, reset, checkout, rebase, clean and config are not allowed. Commits only go to agentbelt/* task branches.

  • You decide approvals. Workflow approval gates can only be decided with agentbelt approve in your terminal. There is no tool for it, so the model can't approve its own work.

  • Everything is audited. Each call is logged to .agentbelt/audit.jsonl, with secrets redacted. See it with agentbelt audit.

  • Honest isolation labels. Built-in plugins run as policy-only: the permission and command checks apply, but there is no OS sandbox. Project test scripts are your project's own code, and they run like they would in your terminal.

  • Third-party plugins run only in an OS sandbox. The sandbox has no network, no access to your files and no secrets in the environment. Their only way to act is the broker:

    • They are installed with package scripts disabled, and pinned to a hash of the reviewed files.

    • If no sandbox is available (macOS sandbox-exec or Linux bubblewrap), they are refused. agentbelt never falls back to running untrusted code with only policy checks.

Read SECURITY.md for the full model and its limits.

Updates you control

agentbelt update      # shows the new version, installs it next to the current one, verifies it, then switches
agentbelt rollback    # instant switch back to the previous version (always kept)
agentbelt doctor      # checks the install and makes real tool calls through it
agentbelt uninstall   # removes agentbelt from your apps (config backups are kept)

Nothing updates automatically. Your apps run a pinned version through a small shim, and a new version becomes active only after it passes verification. The switch is atomic.

Workflows

A workflow is JSON: steps call tools, and approval steps wait for you.

{
  "name": "safe-commit",
  "inputs": { "task": "", "message": "" },
  "steps": [
    { "id": "checks", "uses": "testing_run_checks", "with": { "task": "${inputs.task}" } },
    { "id": "review", "approval": "Commit ${inputs.message}?", "needs": ["checks"] },
    {
      "id": "commit",
      "uses": "git_commit",
      "with": { "task": "${inputs.task}", "message": "${inputs.message}" },
      "needs": ["review"]
    }
  ]
}

Put your own workflows in <project>/.agentbelt/workflows/*.json. Workflows run only when you (or your AI app at your request) start them, or when you opt in to the scheduler (below).

Optional extras (off by default)

  • Coding agent: agentbelt agent setup --provider local --model <name> (or --provider deepseek, or custom --base-url …). Your AI app can then hand a task to that model with agent_run. The key goes to the OS keychain. Verified with a local Ollama model (gpt-oss 20B); the DeepSeek API path is tested with a fake endpoint only.

  • Token optimization (0.2.0): for long agent runs on small-context local models, agent_run with compact: true shortens older tool results (keeps the lines that matter to the task and drops repeated outputs) before each model call. agentbelt tokens and the tokens_report tool show the input and output tokens the model server reported per run, with compaction off and on. Measured results, including where it did not help: docs/token-optimization.md.

  • Scheduler and triggers: agentbelt schedule add repo-health --cron "0 9 * * 1-5", agentbelt trigger add repo-health --on git --branch main, then keep agentbelt scheduler run going. Only file and git triggers; nothing runs unless you start the scheduler.

Plugins

agentbelt plugin list
agentbelt plugin add <npm-package | ./plugin.tgz>   # shows requested permissions; you approve
agentbelt plugin remove <name>

To write one, see docs/plugins.md. A plugin is a name, its permissions and a list of tools.

Requirements

  • Node.js 22.13 or newer, and git.

  • macOS or Linux. Third-party plugins need an OS sandbox: sandbox-exec on macOS, or bubblewrap (bwrap) on Linux with unprivileged user namespaces allowed.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md. Good first contributions include:

  • an adapter for another MCP client (for example Goose);

  • a new skill;

  • a test runner for another ecosystem.

License

Apache-2.0

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Secure local development platform that exposes controlled developer capabilities (FS, Git, search, command execution) to AI assistants via MCP with deny-by-default security and audit logging.
      -
    • A
      license
      B
      quality
      D
      maintenance
      A security-first MCP gateway that enables AI assistants to safely inspect and interact with GitHub repositories through a controlled, auditable tool layer with policy enforcement and human approval for mutations.
      27
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Gives any MCP-compatible AI chat or agent a safe, model-neutral coding runtime with file read/search, structured multi-file patches, command execution, interactive sessions, and git operations, all confined to a single workspace and gated by permission modes.
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Turns any AI coding agent or MCP client into a governed DevOps engineer by exposing policy-enforced tools for Kubernetes, Docker, Jira, Git/PR, CI/CD, AWS, Terraform, and incident response, with approvals, audit logging, secret redaction, and rollback enforced outside the model.
      6
      Apache 2.0