> ## Documentation Index
> Fetch the complete documentation index at: https://beige.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# @matthias-hausberger/beige-toolkit

{/* Run: pnpm run docs:sync-toolkit */}

🛠️ A collection of tools for [Beige](https://github.com/matthias-hausberger/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](./tools/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`](https://cli.github.com/) installed and authenticated |
| [slack](./tools/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](./tools/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](./tools/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](./tools/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](./tools/sessions/)             | Browse and search conversation history. Agents can only access their own sessions — listing, full message retrieval, and pattern-based search.                                                | —                                                           |
| [spawn](./tools/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):

```bash theme={null}
beige tools install npm:@matthias-hausberger/beige-toolkit

# Specific version
beige tools install npm:@matthias-hausberger/beige-toolkit@0.1.0
```

From GitHub (latest from main branch):

```bash theme={null}
beige tools install github:matthias-hausberger/beige-toolkit
```

### Install individual tools

Cherry-pick specific tools from the repository via GitHub:

```bash theme={null}
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)

```bash theme={null}
beige tools install ./path/to/beige-toolkit
```

## Usage

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

```json5 theme={null}
{
  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:

```json5 theme={null}
{
  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`:

```json5 theme={null}
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:

```json5 theme={null}
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

```bash theme={null}
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

```bash theme={null}
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
```

```bash theme={null}
# 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:

```json5 theme={null}
// 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:

```bash theme={null}
# 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

```bash theme={null}
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`:

```json theme={null}
{
  "name": "@beige/tool-my-tool",
  "private": true,
  "type": "module"
}
```

## Publishing

```bash theme={null}
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