---
title: "Agent Guide"
description: "Use official beUI components with additional Asharca workspace APIs, installation steps and examples; no self-hosted service is required."
documentation: "https://asharca.github.io/ui/docs/ai-agents"
markdown: "https://asharca.github.io/ui/docs/ai-agents.md"
---

# Agent Guide

> Use official beUI components with additional Asharca workspace APIs, installation steps and examples; no self-hosted service is required.

## Agent skill

The asharca/ui edition of the beui skill supplements normal beUI usage with WorkspaceShell, WorkspaceSidebar and WorkspaceTabBar installation, APIs and examples. Official beUI components remain available and can be freely combined with these additions. Choose components that fit the interface and the user's preferences.

After the changes are merged into the default branch:

```bash
npx skills add asharca/ui --skill beui
```

## Custom components without deployment

Before this branch is merged, clone it and install the skill from the local checkout:

```bash
git clone --single-branch --branch rebuild/beui-workspace https://github.com/asharca/ui.git asharca-ui-source
# Run the next command from the consuming project; adjust the absolute path.
npx skills add /absolute/path/asharca-ui-source/skills/beui --skill beui
```

A skill install supplies documentation, not the whole component repository. From the source checkout:

```bash
git rev-parse HEAD
bun install --frozen-lockfile
bun scripts/export-component.ts workspace-shell --out /absolute/new-directory/workspace-shell.json
```

Then in the configured consumer, review the proposed changes before installing:

```bash
npx shadcn@latest add /absolute/new-directory/workspace-shell.json --dry-run
npx shadcn@latest add /absolute/new-directory/workspace-shell.json --diff
npx shadcn@latest add /absolute/new-directory/workspace-shell.json
```

The exporter includes all required source files, helpers and the MIT license without starting Next.js or MCP. The custom entry inventory is skills/beui/source-policy.json; APIs and examples are in skills/beui/references/workspace.md. The inventory is reference data, not a restriction on using official components. Review shared-file changes and preserve the consuming project's customizations.

## MCP server (optional)

The official beUI MCP provides discovery and source inspection for its hosted catalog. Connecting it is optional; custom workspace examples and local export work independently. The hosted address is `https://mcp.beui.dev/mcp`.

```bash
# Claude Code
claude mcp add --transport http beui https://mcp.beui.dev/mcp

# Codex
codex mcp add beui --url https://mcp.beui.dev/mcp

# Amp
amp mcp add beui https://mcp.beui.dev/mcp
```

Manual configuration:

```json
{
  "mcpServers": {
    "beui": {
      "type": "http",
      "url": "https://mcp.beui.dev/mcp"
    }
  }
}
```

Available tools: `list_components`, `search_components`, `get_component`, and `get_install_command`.

## Endpoints

| Endpoint | Purpose |
| --- | --- |
| `/llms.txt` | Markdown discovery index |
| `/r` | JSON catalogue of every component |
| `/r/{slug}` | Component detail with files, dependencies, and source |
| `/registry.json` | shadcn directory-compatible catalogue |
| `/r/{slug}.json` | shadcn install item with inline file content |
| `/r/{slug}/raw` | Copy-ready plain-text source |
| `/components/{category}/{slug}.md` | Component documentation as Markdown |

## Agent flow

Explore official components through their published catalog:

1. Fetch `https://beui.dev/r` to discover components.
2. Select an item by its published name and description.
3. Fetch `https://beui.dev/r/{slug}` for source, files, and dependencies.
4. Review the files and merge them into the consumer's paths, preserving local changes.
5. Install compatible external dependencies from the response.

For the additional Asharca workspace components, the local export and bundled reference above provide the source and APIs. Compose official and custom components together as needed.

## shadcn flow

```bash
# Official beUI component
npx shadcn@latest view @beui/animated-toast-stack
npx shadcn@latest add @beui/animated-toast-stack --dry-run
npx shadcn@latest add @beui/animated-toast-stack

# Official registry URL alternative
npx shadcn@latest add https://beui.dev/r/animated-toast-stack.json
```

## Entry shape

Registry detail entries include the component slug, name, description, category, documentation URLs, package dependencies, internal helpers, and every source file required by the install. The local exporter produces a self-contained shadcn install item instead, including alias-aware file targets and provenance metadata.

## Generative UI

To let a model compose beUI components into a live interface, follow the [OpenUI integration guide](https://asharca.github.io/ui/docs/openui.md).