Beth

She doesn't do excuses. She doesn't do hand-holding. She does results—and she'll have your entire project shipping while everyone else is still scheduling their kickoff meeting. Think of her as the managing director your codebase didn't know it needed, but absolutely deserves.

They broke her wings once. They forgot she had claws.

What Is This?

Beth is a multi-agent AI orchestrator with a TypeScript runtime, CLI toolchain, MCP integrations, and subagent delegation—all driven by a ruthless coordinator who runs your development team the way Beth Dutton runs Schwartz & Meyer.

She commands seven specialized agents, each with their own expertise, tools, and handoff chains. On top of the GitHub Copilot agent layer, Beth ships a TypeScript core engine with a full agentic loop: agent routing, conversation context management, tool calling, subagent spawning, and agent handoffs—all backed by an Azure OpenAI LLM provider with streaming and retry.

The system has four execution layers:

Layer	What It Does	Status
Copilot Agents	`.agent.md` definitions running in VS Code Agent Mode	Live
CLI Toolchain	`beth init`, `beth doctor`, `beth quickstart` — TypeScript commands	Live
Orchestration Engine	Fan-out routing, tool calling loop, subagent spawning, handoffs	Live
Tool Abstraction	6 CLI tools + MCP bridge — uniform interface for all agent capabilities	Live
LLM Provider	Azure OpenAI with Entra ID auth, streaming, retry, tool calling	Live

814 tests. 813 pass, 1 skip, 0 fail.

Architecture

flowchart LR
    Input["Copilot Chat / CLI"] --> Beth["@Beth"]
    Beth --> Agents["PM · UX · Dev · Sec · Test · Research"]
    Beth --> Skills["Skills · MCP"]

    style Beth fill:#1e3a5f,color:#fff

Tech Stack

Category	Technology	Notes
Runtime	Node.js ≥ 18	ES modules, built-in test runner
Language	TypeScript (strict mode)	No `any`. Zod for runtime validation
Target Framework	React 19 + Next.js App Router	Server Components, Server Actions, Suspense, streaming
Styling	Tailwind CSS + `class-variance-authority` (cva)	Utility-first with typed variants
Components	shadcn/ui	Radix primitives, copy-paste ownership
LLM Provider	Azure OpenAI via `openai` SDK	Entra ID auth (no API keys), streaming + tool calling
Auth	`@azure/identity` DefaultAzureCredential	az login, managed identity, VS Code creds
Frontmatter	`gray-matter`	Parses `.agent.md` and `SKILL.md` YAML
Testing	Node.js built-in test runner	814 tests — unit, integration, E2E
Task Tracking	beads (`bd` CLI)	Dependency-aware issue tracking for agents
Package Manager	pnpm	Lockfile committed

Production dependencies: 1 (gray-matter). That's it. Minimal attack surface by design.

Getting Started

One command:

npx beth-copilot init

Global install:

npm i -g beth-copilot
beth init

Then open VS Code, switch Copilot Chat to Agent mode, and type @Beth.

Verify everything works:

beth doctor       # Health check: Node.js, beads, agents, skills
beth quickstart   # Init + doctor + beads setup in one shot

For detailed setup (prerequisites, task tracking, MCP servers): docs/INSTALLATION.md

CLI Commands

Command	What It Does
`beth init`	Install agents, skills, VS Code settings, beads tracking
`beth init --force`	Overwrite existing files
`beth doctor`	Validate Node.js ≥18, beads CLI, agents frontmatter, skills directories
`beth quickstart`	Run init + doctor + beads init in one shot
`beth help`	Show all commands and options

Flags: --force, --skip-backlog, --skip-mcp, --skip-beads, --verbose

Agent Orchestration

Beth doesn't micromanage. She delegates to specialists over subagent and handoff channels, tracks dependencies with beads, and holds every agent accountable.

The Family

Agent	Role	What They Do
@Beth	The Boss	Orchestrates everything. Routes work. Takes names.
@product-manager	The Strategist	WHAT to build: PRDs, user stories, priorities, success metrics
@researcher	The Intelligence	Competitive analysis, user insights, market dirt
@ux-designer	The Architect	HOW it works: component specs, design tokens, accessibility
@developer	The Builder	React/TypeScript/Next.js — UI and full-stack
@tester	The Enforcer	Quality assurance, accessibility, performance
@security-reviewer	The Bodyguard	OWASP, compliance, threat modeling

Delegation Model

flowchart LR
    Beth["@Beth"] -->|subagent| PM["PM"] & UX["UX"] & Dev["Dev"] & Sec["Sec"] & Test["Test"] & Res["Research"]
    PM -.->|handoff| UX & Dev
    Dev -.->|handoff| Test & UX

    style Beth fill:#1e3a5f,color:#fff

Subagent vs Handoff

Mechanism	Control	Use When
Subagent	Beth decides	Task can run autonomously, no human review needed
Handoff	User decides	User needs to review before proceeding

// Beth spawns a specialist — autonomous execution
runSubagent({
  agentName: "developer",
  prompt: "Implement JWT auth flow with refresh token rotation...",
  description: "Implement auth"
})

Workflow: New Feature

sequenceDiagram
    participant U as User
    participant B as Beth
    participant PM as PM
    participant UX as UX
    participant D as Dev
    participant S as Sec
    participant T as Test

    U->>B: Request
    B->>PM: Requirements
    PM-->>B: PRD
    B->>UX: Design
    UX-->>B: Specs
    B->>D: Build
    D-->>B: Done
    par Quality gates
        B->>S: Security
        S-->>B: Approved
    and
        B->>T: Verify
        T-->>B: Pass
    end
    B->>U: Ship ✅

Bug Hunt? Tester → Developer → Security → Tester Security Audit? Security → Developer → Tester → Security sign-off

MCP Integrations

Model Context Protocol servers extend agent capabilities. All optional — agents gracefully degrade without them.

Server	Agent	Capability
shadcn/ui	Developer	Component browsing & installation
Playwright	Tester	Browser automation, E2E testing
Azure	Developer, Security	Cloud resource management
Brave Search	Researcher	Internet research
DeepWiki	All	Repository documentation lookup

Quick Setup

# Copy example config and enable what you need
cp mcp.json.example .vscode/mcp.json

{
  "servers": {
    "shadcn":     { "command": "npx", "args": ["shadcn@latest", "mcp"] },
    "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] },
    "azure":      { "command": "npx", "args": ["@azure/mcp-server"] },
    "web-search": { "command": "npx", "args": ["@brave/brave-search-mcp-server"] },
    "deepwiki":   { "url": "https://mcp.deepwiki.com/mcp" }
  }
}

Full details: docs/MCP-SETUP.md

Skills (On-Demand Knowledge)

Skills are domain-knowledge modules that agents load automatically when trigger phrases match. Each skill lives in .github/skills/<name>/SKILL.md.

Skill	Triggers On	Used By
PRD Generation	"create a prd", "product requirements"	Product Manager
Framer Components	"framer component", "property controls"	UX Designer
React/Next.js Best Practices	React performance, Next.js patterns	Developer
Web Design Guidelines	"review my UI", "check accessibility"	UX Designer
shadcn/ui	"shadcn", "ui component"	Developer
Security Analysis	"security review", "OWASP", "threat model"	Security Reviewer
Azure Operations	Azure resource management	Developer
Web Search	Internet research via Brave	Researcher

How It Works

Beth runs inside VS Code Copilot Agent Mode. The @Beth agent parses requests, delegates to specialist agents via subagent spawning, and tracks work through beads.

flowchart LR
    Msg["@Beth message"] --> Route["Agent Router"]
    Route -->|subagent| Agent["Specialist"]
    Agent -->|tools| Work["Code · Test · Review"]
    Agent -->|done| Route
    Route --> Done["Response"]

    style Route fill:#1e3a5f,color:#fff

Key capabilities:

Agent routing — @mention parsing, subagent spawning, handoff chains
Skill injection — Domain knowledge loaded on trigger phrases
Task tracking — beads (bd) for epics, subtasks, dependencies
MCP integration — Optional external tool servers (shadcn, Playwright, Azure)

// Beth spawns a specialist
runSubagent({
  agents: loadAgents('.github/agents'),
  skills: loadSkills('.github/skills'),
  provider: new AzureOpenAIProvider(config),
  toolRegistry: createDefaultRegistry(),
  toolContext: { workingDir: process.cwd(), permissions: { ... } },
});

const result = await orchestrator.processMessage('Implement the login page');
// result.response — final text
// result.agentId — who handled it
// result.toolCallsExecuted — what tools ran
// result.subagentResults — any nested agent work
// result.injectedSkills — skills loaded for this turn

Tool Abstraction Layer

A uniform interface for all agent capabilities — file I/O, terminal, search, beads, subagent spawning, and MCP server tools. Tools expose OpenAI-compatible function calling schemas so the LLM can invoke them directly.

Tool	What It Does	Key Features
readFile	Read file contents	Line ranges, path validation, traversal guards
editFile	Atomic string replacement	Single-match enforcement, whitespace-safe
search	Ripgrep search	Node.js fallback, regex support, file filtering
terminal	Execute shell commands	`execFile('/bin/sh')` — no shell injection, timeouts
beads	Issue tracking	`bd create`, `bd close`, `bd list` via CLI wrapper
subagent	Spawn nested agents	Returns structured result for orchestrator to process
MCP Bridge	External tool servers	JSON-RPC 2.0 over stdio, JSONC config, namespaced tools

import { createDefaultRegistry, ToolRegistry, loadAllMCPTools } from 'beth-copilot';

// Built-in tools
const registry = createDefaultRegistry();
// → readFile, editFile, search, terminal, beads, subagent

// Add MCP server tools
const { tools: mcpTools } = await loadAllMCPTools('.vscode/mcp.json');
for (const tool of mcpTools) {
  registry.register(tool); // e.g., mcp_shadcn_listComponents
}

// Get OpenAI function calling definitions
const definitions = registry.getDefinitions();
// Pass to LLM as tools parameter

CLI Toolchain

The CLI handles scaffolding and health checks — distributing agent and skill files to target projects.

flowchart LR
    CLI["beth"] --> Init["init"]
    CLI --> Doctor["doctor"]
    CLI --> QS["quickstart"]
    Init --> Templates[".agent.md · SKILL.md · settings"]
    Doctor --> Checks["Node ≥18 · beads · agents · skills"]
    QS --> Init & Doctor

Commands:

beth init — Scaffold agents, skills, VS Code settings, beads tracking
beth doctor — Validate Node.js, beads CLI, agent frontmatter, skill directories
beth quickstart — Run init + doctor + beads init in one shot

TypeScript Core

The engine that powers everything. Parses agent and skill definitions, manages conversations, routes requests, executes tools, and provides typed APIs for the full agentic loop.

Project Structure

beth/
├── bin/
│   └── cli.js                      # CLI entry point (init, doctor, quickstart, help)
├── src/
│   ├── index.ts                    # Barrel exports (all public API)
│   ├── cli/commands/
│   │   ├── doctor.ts               # System health validation
│   │   └── quickstart.ts           # Guided setup flow
│   ├── core/
│   │   ├── orchestrator.ts         # Agentic loop: route → LLM → tools → response
│   │   ├── router.ts               # @mention routing, skill matching, agent lookup
│   │   ├── context.ts              # Conversation state, token truncation, skill injection
│   │   ├── handoffs.ts             # Agent handoff transfers, loop detection
│   │   ├── agents/
│   │   │   ├── types.ts            # AgentDefinition, AgentFrontmatter, AgentHandoff
│   │   │   └── loader.ts           # Parse .agent.md → typed definitions
│   │   └── skills/
│   │       ├── types.ts            # SkillDefinition, TriggerMap
│   │       └── loader.ts           # Parse SKILL.md, extract triggers, match queries
│   ├── lib/
│   │   └── pathValidation.ts       # Traversal/injection guards
│   ├── tools/
│   │   ├── interface.ts            # Tool interface + toToolDefinition()
│   │   ├── types.ts                # ToolError, ToolResult, ToolContext, ToolPermissions
│   │   ├── registry.ts             # ToolRegistry: register, get, list, getDefinitions
│   │   ├── cli/
│   │   │   ├── readFile.ts         # File reading with line ranges
│   │   │   ├── editFile.ts         # Atomic string replacement
│   │   │   ├── search.ts           # Ripgrep with Node.js fallback
│   │   │   ├── terminal.ts         # Secure command execution
│   │   │   ├── beads.ts            # Issue tracking via bd CLI
│   │   │   └── subagent.ts         # Agent spawning interface
│   │   └── mcp/
│   │       ├── client.ts           # JSON-RPC 2.0 over stdio
│   │       └── bridge.ts           # JSONC config, tool namespacing
│   └── providers/
│       ├── interface.ts            # LLMProviderBase abstract class
│       ├── azure.ts                # AzureOpenAIProvider (Entra ID, streaming, tools)
│       ├── types.ts                # 17 types: ChatMessage, ToolCall, LLMError, etc.
│       ├── retry.ts                # Exponential backoff with jitter
│       ├── config.ts               # Environment + dotfile config loader
│       └── streaming.ts            # StreamAccumulator, collectStream, mapStream
├── templates/
│   └── .github/
│       ├── agents/                 # 7 agent definitions (.agent.md)
│       └── skills/                 # 8 skill modules (SKILL.md)
└── docs/
    ├── INSTALLATION.md
    ├── MCP-SETUP.md
    ├── CLI-ARCHITECTURE.md
    └── SYSTEM-FLOW.md

Test Coverage

814 tests (813 pass, 1 skip, 0 fail):

Suite	Tests	What It Covers
Orchestration
Orchestrator	30+	Agentic loop, tool calling, subagent spawning, iteration limits
AgentRouter	30+	@mention routing, skill matching, agent resolution
ConversationContext	30+	Token truncation, skill injection, tool call repair
HandoffManager	30+	Context transfer, depth limits, ping-pong detection
Tools
Tool interface	20+	Tool → ToolDefinition conversion, schema validation
ToolRegistry	20+	Register, get, list, definitions, duplicate detection
readFile	30+	Line ranges, path validation, encoding
editFile	30+	String replacement, single-match enforcement
search	30+	Ripgrep, Node.js fallback, regex, file filtering
terminal	30+	Command execution, timeouts, output capture
beads	30+	bd CLI wrapper, create/close/list/ready
subagent	30+	Spawn interface, result marking, agent validation
MCP client	30+	JSON-RPC 2.0, protocol handshake, tool listing
MCP bridge	30+	JSONC parsing, tool namespacing, error handling
Tool suite	10+	createDefaultRegistry, integration tests
Providers
Provider types	40+	LLMError codes, ChatMessage shapes, ToolDefinition schemas
Provider retry	40+	Exponential backoff, jitter, transient error detection
Provider config	30+	Env precedence, dotenv parsing, URL validation
Provider streaming	40+	Chunk accumulation, tool call delta assembly
Provider Azure	30+	Message mapping, response mapping, error wrapping
Core & CLI
Agent loader	30+	Frontmatter parsing, validation, code fence stripping, handoffs
Skill loader	30+	Trigger extraction, query matching, trigger map building
CLI E2E	52	Init/doctor pipeline, MCP template validation, help output
Path validation	33	Traversal detection, injection prevention, allowlists

IDEO Design Thinking

Beth follows human-centered design methodology across agent workflows:

flowchart LR
    E["1. Empathize<br/>@researcher"] --> D["2. Define<br/>@product-manager"] --> I["3. Ideate<br/>@ux-designer"] --> P["4. Prototype<br/>@developer"] --> T["5. Test<br/>@tester"]
    T -.->|iterate| E

Quality Standards

Beth doesn't ship garbage:

Standard	Gate	Enforced By
WCAG 2.1 AA	Accessibility compliance	UX Designer + Tester
Core Web Vitals	LCP < 2.5s, FID < 100ms, CLS < 0.1	Developer
OWASP Top 10	Zero known vulnerabilities	Security Reviewer
TypeScript Strict	No `any`	Developer
Test Coverage	Unit + Integration + E2E	Tester

flowchart LR
    Code["Code"] --> Gates["a11y · Perf · OWASP · Types · Tests"]
    Gates -->|Pass| Ship["🚀 Ship"]
    Gates -->|Fail| Fix["🔧 Fix"] --> Code

Quick Commands

Don't waste her time. Be direct.

@Beth Build me a dashboard for user analytics with real-time updates.

@Beth Security review for our authentication flow. Find the holes.

@developer Implement a drag-and-drop task board. Make it fast.

@security-reviewer OWASP top 10 assessment on our API endpoints.

@tester Accessibility audit. WCAG 2.1 AA. No excuses.

Why Beth?

Look, you could try to coordinate seven specialists yourself. You could context-switch between product strategy, security reviews, and accessibility audits while keeping your sanity intact.

Or you could let Beth handle it.

She's got the crew. She's got the workflows. She delegates like a managing director because that's exactly what she is. You bring the problem, she brings the people—and somehow, the code ships on time, secure, and accessible.

Is it magic? No. It's just competence with very good hair.

"I made two decisions in my life based on fear, and they almost ruined me. I'll never make another."

Requirements

Node.js ≥ 18
VS Code with GitHub Copilot extension
GitHub Copilot Chat in Agent mode
beads for task tracking (bd CLI)

Installing Beads

curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

CGO Troubleshooting (Linux/WSL): Beads uses Dolt (a Git-for-data database) which requires CGO. If bd init or bd doctor fails with CGO-related errors:

# Install C compiler toolchain (required for CGO)
sudo apt-get update && sudo apt-get install -y build-essential gcc

# Verify CGO is available
export CGO_ENABLED=1
go env CGO_ENABLED  # should print 1

# Re-install beads
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

Common beads issues:

bd: command not found — Add ~/.local/bin to your PATH: export PATH="$HOME/.local/bin:$PATH"
bd doctor warnings about metadata — Run bd doctor --fix to auto-repair
Dolt migration errors — Delete .beads/ and re-initialize with bd init

# Verify beads is working
bd doctor

Optional: MCP Servers

See MCP Integrations above or docs/MCP-SETUP.md for setup.

Documentation

Doc	Purpose
Installation Guide	Full setup: prerequisites, VS Code config, beads
MCP Setup	Optional server integrations
CLI Architecture	Dual-interface design, implementation phases
System Flow	Agent orchestration diagrams
Contributing Guide	How to contribute (PR process, review checklist)
Changelog	Version history
Security Policy	Vulnerability reporting

License

MIT — Take it. Run it. Build empires.

Built with the kind of ferocity that would make John Dutton proud.

Name		Name	Last commit message	Last commit date
Latest commit History 139 Commits
.github		.github
assets		assets
bin		bin
docs		docs
src		src
tasks		tasks
templates		templates
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
Backlog.md		Backlog.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
DEMO.md		DEMO.md
README.md		README.md
SECURITY.md		SECURITY.md
mcp.json.example		mcp.json.example
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
sbom.json		sbom.json
tsconfig.json		tsconfig.json

stephschofield/beth

Folders and files

Latest commit

History

Repository files navigation

Beth

What Is This?

Architecture

Tech Stack

Getting Started

CLI Commands

Agent Orchestration

The Family

Delegation Model

Subagent vs Handoff

Workflow: New Feature

MCP Integrations

Quick Setup

Skills (On-Demand Knowledge)

How It Works

Tool Abstraction Layer

CLI Toolchain

TypeScript Core

Project Structure

Test Coverage

IDEO Design Thinking

Quality Standards

Quick Commands

Why Beth?

Requirements

Installing Beads

Optional: MCP Servers

Documentation

License

About

Resources

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages