Beam CLI: Open-Source Agent Security, Local Monitoring, and 20 Security Skills

If your coding agent can run Bash, edit files, and call MCP tools, your security model is no longer “don’t paste secrets into ChatGPT.” It is “what did the agent actually try to do in the last hour — and did anyone review the skill folder before it ran?” explainx.ai has tracked that gap through incident after incident in 2026. Beam CLI is the open-source answer the team ships today: local observation, offline scans, and a full security skills library you can audit because the repo is public on GitHub.

Beam is not another agent harness. It does not plan tasks or run tools for you. It sits beside Claude Code, Cursor, Codex, or Copilot CLI and records proposed tool use, applies pattern-based risk rules, and lets you mark findings reviewed in Beam Studio — all on loopback, with secrets redacted before anything hits disk.

TL;DR

What Beam CLI is (and is not)

The README states the design rule plainly: observation must never become enforcement. When an agent fires a PreToolUse hook, Beam normalizes the payload, redacts known credential formats and private keys, runs categorized rules (exec, exfil, secrets, integrity, and others), and optionally evaluates sequence rules across the last 50 events in a session — for example, credential access followed later by network activity.

That is a different contract from gateway guardrails or fail-closed command hooks. Beam’s hook path logs capture failures to stderr and never blocks the agent. For teams that already run MCP and skill verification workflows, Beam adds a continuous tape of what the harness attempted, not just what passed a one-time install scan.

The same rule engine powers:

• Live ingestion through beam hook <agent>
• Offline beam scan SKILL.md or beam scan mcp.json --mcp
• The Findings and Scan panes in Studio

Heuristic matching is not malware analysis or semantic proof of safety. Findings are prompts for human review — consistent with how explainx.ai positions agent security platforms in 2026: observation-first tooling is valuable precisely when blocking every ambiguous command would break legitimate automation.

Install and verify (what we ran locally)

Requirements: Node.js ≥ 20.17.0. From a clone of whyashthakker/beam-cli:

git clone https://github.com/whyashthakker/beam-cli.git
cd beam-cli
npm run setup:global

setup:global builds the TypeScript project, links the beam binary globally, starts a file watcher so edits rebuild automatically, and runs beam agent install-all so every detected agent on the machine gets a non-destructive hook merge.

When validating this guide, npm test passed in the repo and the linked binary reported 0.2.2. A quick sanity check:

beam agent list
beam rule list

beam agent list showed Claude Code, Codex, Cursor, and Copilot CLI as installable with payload verified, Gemini as best-effort, and OpenCode as config wiring not built yet — matching the upstream matrix in the README.

beam rule list grouped built-in rules by category and listed sequence detectors such as chain.secret_then_egress (credential read then network) and chain.recon_then_exec (recon then remote execution).

Start the collector and open Studio

beam start                    # foreground collector on :4319
beam service install          # launchd (macOS) or systemd user unit (Linux)
beam studio                   # open dashboard; token paired via URL then localStorage

Studio is static HTML served from the collector — no CDN fonts, no separate frontend build. Activity lists captured events; Findings shows heuristic matches; Skill & MCP scan reuses the scan engine in the browser. The page stores the bearer token in localStorage for that origin only; use Disconnect to clear it.

For machines that should survive terminal closes, prefer beam service install. Windows service integration is not supported yet; use beam start directly there.

Wire hooks without fighting your agent config

Manual Claude Code hook (also what beam agent install claude-code merges for you):

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "beam hook claude-code"
      }]
    }]
  }
}

beam agent install <agent> writes into each product’s real config file (~/.claude/settings.json, ~/.cursor/hooks.json, etc.) and merges with existing hooks — it does not wipe unrelated entries. Detection uses files the agents themselves created, so a second install run should not duplicate hooks.

If you need history from before Beam existed:

beam agent extract claude-code              # preview, local redaction only
beam agent extract claude-code --save       # ingest into collector (deduped)

Extraction is bounded (per-file size and line caps documented in the README) and tags events with source: "extract" so they are visually distinct from live hook capture.

Offline scans before you trust a skill or MCP server

Third-party agent skills and MCP servers are supply-chain surface area. Beam’s fast path:

beam scan ./path/to/SKILL.md
beam scan ./mcp.json --mcp
beam scan ./SKILL.md --save    # persist report to collector if running

scan runs fully offline unless --save is set. MCP mode includes version-pin checks on server definitions. This overlaps partially with the deeper skill-scanner and mcp-scanner skills in the bundle — those walk folder structure, archive traversal, and evidence tables; beam scan is the quick regex/heuristic pass.

Example categories you will see in output mirror live rules: remote execution, obfuscated execution, reverse shells, credential egress, instruction overrides, git history rewrite, and cloud metadata access patterns.

Custom rules and sequence detection

Extend detection without forking Beam by editing ~/.beam/rules.json:

[
  {
    "id": "internal_host",
    "pattern": "wiki\\.internal\\.corp",
    "severity": "high",
    "category": "exfil",
    "title": "Internal wiki referenced"
  }
]

Then run beam rule reload against the live collector. Malformed entries are skipped with a visible error — they do not crash the process.

Sequence rules address a blind spot single-event regexes miss: an innocent-looking curl after an earlier .env read in the same session. Beam attaches composite findings to the completing event idempotently so re-importing history does not duplicate alerts.

The 20 security skills and seven reviewer roles

The Skills/ directory is shipped inside the npm package. manifest.json lists 20 skills across coordination, pre-install discovery, AI trust boundaries, application/supply chain, and deployment/operations — for example security-assessment, prompt-injection-review, dependency-supply-chain, and agent-incident-response.

Each skill is an agent workflow (markdown instructions), not a hidden CLI subcommand. You choose folders, copy them into Claude Code or Codex skills directories after review, and run assessments on real artifacts. Seven paired reviewer sub-agents live under Skills/agents/claude/ and Skills/agents/codex/ (skill auditor, MCP auditor, incident analyst, findings reviewer, and others). They are review-only profiles — read-only tooling declarations, no automatic install or telemetry enrollment.

Typical prompts the README suggests:

• Review a downloaded skill folder before install, including referenced scripts.
• Review an MCP config and server source before connection.
• Inventory AI assets in a repo, then assess model loaders and retrieval permissions.
• Review exported agent events and separate proposed actions from confirmed effects.

Run npm run validate:skills in the repo to check manifest consistency before you publish a fork. Deeper setup and spec background lives on Agentbeam’s skills documentation — optional reading; the CLI does not phone home when you copy skills locally.

Configuration, retention, and export

Retention caps: 10,000 events and 500 scan reports, atomically bounded on ingest. GET /export returns redacted NDJSON for your own SIEM or ticket workflow — still treat exports as sensitive; redaction covers known formats, not every possible secret string.

API routes require Authorization: Bearer <token> and loopback binding. Ingest accepts up to 2 MB / 2,000 records per request; OTLP/HTTP JSON logs are supported at POST /v1/logs.

How Beam fits next to other safety layers

Think in layers:

1. Least privilege and sandboxes — OS-level boundaries (Fable-OS-style capability models when commands are not the whole story).
2. Inline command policy — dcg and similar hooks that deny known destructive shell patterns.
3. Observation and review — Beam’s collector, Studio, and skills library for visibility, offline skill/MCP review, and incident-oriented workflows.
4. Hosted governance — Enterprise guardrails in the security platform landscape when you need org-wide policy, not just one laptop.

explainx.ai’s Sentinel product direction covers broader desktop and browser monitoring; Beam CLI is the AGPL piece you can clone, diff, and run today while that roadmap continues.

Honest limitations (read before you rely on it)

• No blocking in v1 — risky actions still execute unless another layer stops them.
• Heuristics only — clever encoding, novel attack chains, and social engineering in skill prose can evade patterns.
• Gemini and OpenCode — hook support is incomplete or unverified; check beam agent list before assuming coverage.
• Windows services — use foreground beam start; no launchd/systemd equivalent yet.
• AGPL-3.0-only — network SaaS built on top of modified Beam may trigger copyleft obligations; legal review for your deployment model.
• Young project — small star count, active development; expect schema and rule catalog changes.

Related open tooling: beam-mcp (MCP server exposing scan commands to MCP hosts) is listed in the repo README as a companion project.

Quick start checklist

1. Clone beam-cli and run npm run setup:global.
2. Run beam service install (or beam start) and beam studio — confirm Activity shows test hook events.
3. Run beam scan on every third-party SKILL.md or MCP config before enabling it.
4. Copy skill-scanner / mcp-scanner (or security-assessment) into your agent when doing a formal review.
5. Add beam rule reload-able custom patterns for your internal hostnames or forbidden commands.
6. Pair with a blocking guard on shell if your agent runs with broad filesystem access.

Related on explainx.ai

• Top AI Agent Security Platforms in 2026
• Why explainx.ai Is Building Sentinel
• What Are Agent Skills?
• MCP Security Guide
• Agent Skills Security Threats and Verification
• Claude Code Hooks: Automate Actions on Tool Calls
• Numbat: Perplexity's Agent Observability Tool
• Indirect Prompt Injection in AI Agents

Sources

• Beam CLI on GitHub — install, commands, API, limits (AGPL-3.0-only)
• Agentbeam — team/hosted monitoring and skills setup guides

Beam CLI version 0.2.2, rule catalog, and agent matrix reflect the public repository as of September 14, 2026. Re-run beam agent list and beam rule list after upgrades.