beige-toolkit

🛠️ A collection of tools for Beige agents.

Beige is an open-source AI agent framework with a gateway/sandbox architecture. This toolkit provides gateway-side tools that give agents access to external services — GitHub, Slack, Confluence, Chrome, macOS Calendar, conversation history, and other agents.

All tools run on the gateway (host machine), not inside agent sandboxes. Each tool supports fine-grained access control via config-level allow/deny lists so you can scope exactly what each agent is permitted to do.

Tools

| Tool | Description | Requires | |------|-------------|----------| | github | Interact with GitHub via the gh CLI — repos, issues, PRs, releases, workflow runs, and more. Repository deletion is permanently blocked. Raw API access is off by default. | gh installed and authenticated | | slack | Interact with Slack workspaces — list conversations, read message history, send messages, add reactions. Access controlled via command-level allow/deny lists. | slackcli installed and authenticated | | confluence | Read and write Atlassian Confluence — pages, spaces, search, attachments, comments, content properties, and exports. Supports both command-level and space-level access control. | confluence-cli installed and authenticated | | chrome | Control a Chrome browser — navigation, screenshots, DOM inspection, JS evaluation, network monitoring, performance analysis. Each agent gets its own persistent browser profile. | Google Chrome installed | | apple-calendar | Read events from macOS Calendar — supports iCloud, Google, Exchange, and subscribed calendars. List calendars, view events by date/range, and search by title, notes, or location. Read-only. | macOS, Xcode Command Line Tools | | sessions | Browse and search conversation history. Agents can only access their own sessions — listing, full message retrieval, and pattern-based search. | — | | spawn | Spawn other Beige agents (or sub-agents of yourself) with multi-turn conversations. Depth-limited and opt-in — no targets allowed until explicitly configured. | — |

Installation

Install all tools

From npm (recommended for stable releases):

beige tools install npm:@matthias-hausberger/beige-toolkit

# Specific version
beige tools install npm:@matthias-hausberger/[email protected]

From GitHub (latest from main branch):

beige tools install github:matthias-hausberger/beige-toolkit

Install individual tools

Cherry-pick specific tools from the repository via GitHub:

beige tools install github:matthias-hausberger/beige-toolkit/tools/github
beige tools install github:matthias-hausberger/beige-toolkit/tools/chrome
beige tools install github:matthias-hausberger/beige-toolkit/tools/slack

Install from local checkout (development)

beige tools install ./path/to/beige-toolkit

Usage

After installing, add tools to your agents in config.json5:

{
  agents: {
    assistant: {
      model: { provider: "anthropic", model: "claude-sonnet-4-6" },
      tools: ["github", "chrome", "slack", "sessions"],
    },
  },
}

Installed tools are auto-discovered — no need to specify path or target. Add a tools.<name> entry only for custom config:

{
  tools: {
    github: {
      config: { allowedCommands: ["repo", "issue", "pr"] },
    },
    slack: {
      config: { denyCommands: ["messages send", "messages draft"] },
    },
    chrome: {
      config: { headless: true, idleTimeoutMinutes: 15 },
    },
  },
}

Access Control

Every tool supports fine-grained permission scoping via config:

tools: {
  github: {
    config: { allowedCommands: ["issue", "pr"] },
  },
  slack: {
    config: { denyCommands: ["messages send", "messages draft"] },
  },
},

Per-Agent Overrides

Use per-agent toolConfigs to deep-merge overrides with the base tool config:

tools: {
  chrome: {
    config: { headless: true, timeout: 60 },
  },
},
agents: {
  qa: {
    tools: ["chrome"],
    toolConfigs: {
      chrome: { headless: false, timeout: 120 },
    },
  },
  assistant: {
    tools: ["chrome"],
    // uses base config as-is
  },
},

See each tool's README for the full list of config options.

Managing Tools

beige tools list                    # List all installed tools
beige tools update                  # Update all tools
beige tools update github           # Update a specific tool
beige tools remove github           # Remove a tool

Documentation Structure

Each tool has two documentation files:

| File | Audience | Purpose | |---|---|---| | README.md | Users / developers | Overview, prerequisites, configuration reference | | SKILL.md | AI agents | Usage examples, calling conventions, workflows |

Development

Prerequisites

• Node.js ≥ 22
• pnpm

Setup

git clone https://github.com/matthias-hausberger/beige-toolkit
cd beige-toolkit
pnpm install

Working Locally Against Beige

devDependencies references the published @matthias-hausberger/beige npm package so the project builds on any machine without extra setup. When you also have the beige repository checked out as a sibling directory (../beige), pnpm's overrides block in package.json automatically redirects the dependency to that local copy, letting you test against unreleased changes.

parent/
  beige/          ← local beige repo (optional)
  beige-toolkit/  ← this repo

# With sibling beige repo — uses local beige automatically via pnpm overrides
cd beige-toolkit
pnpm install

# Without sibling beige repo — installs the published npm version, no extra steps needed
cd beige-toolkit
pnpm install

If you are on a machine that does not have a sibling beige directory, remove or comment out the pnpm.overrides entry in package.json before running pnpm install, or pnpm will error because the file:../beige path does not exist:

// package.json — comment out when ../beige is not present
"pnpm": {
  "overrides": {
    // "@matthias-hausberger/beige": "file:../beige"
  }
}

To start the gateway and install the toolkit for local development:

# Start the beige gateway
cd ../beige
pnpm run beige gateway start

# Install the local toolkit
cd ../beige-toolkit
bash scripts/dev-install.sh

Beige symlinks the local directory, so edits to tools/ take effect on the next gateway restart.

Running Tests

pnpm test              # Run all tests
pnpm test:watch        # Watch mode
pnpm typecheck         # Type-check
pnpm smoke             # Full smoke sequence

Adding a New Tool

1. Create tools/<name>/ with tool.json, package.json, index.ts, README.md, SKILL.md
2. Write tests in tools/<name>/__tests__/
3. If the tool has npm dependencies, add them to tools/<name>/package.json under dependencies

Each tool has its own package.json so it can be installed individually via GitHub. For tools with no runtime dependencies, the package.json just needs name and type:

{
  "name": "@beige/tool-my-tool",
  "private": true,
  "type": "module"
}

Publishing

npm publish --access public

The files field in the root package.json controls what goes into the npm tarball. Only tool source files are included — tests, scripts, and dev config are excluded.

Repository Structure

beige-toolkit/
├── package.json              # npm package config
├── tsconfig.json
├── vitest.config.ts
├── tools/
│   ├── github/
│   │   ├── tool.json         # Tool manifest (name, description, target)
│   │   ├── package.json      # Tool's own dependencies (if any)
│   │   ├── index.ts          # Handler (runs on the gateway host)
│   │   ├── README.md         # User/developer documentation
│   │   ├── SKILL.md          # Agent usage guide
│   │   └── __tests__/
│   ├── chrome/
│   │   ├── tool.json
│   │   ├── package.json
│   │   ├── index.ts
│   │   ├── mcp-client.ts     # Additional module
│   │   ├── process-manager.ts
│   │   ├── README.md
│   │   ├── SKILL.md
│   │   ├── skills/           # Detailed agent guides
│   │   └── __tests__/
│   ├── slack/
│   ├── confluence/
│   ├── apple-calendar/
│   ├── sessions/
│   └── spawn/
├── test-utils/
├── tests/                    # Repo-level smoke tests
└── scripts/
    ├── dev-install.sh
    └── smoke.sh

License

MIT