claude-workshop-live.md

repo	johnlindquist/claude-workshop-live
url	https://github.com/johnlindquist/claude-workshop-live
homepage
starredAt	2025-11-21T21:09:18Z
createdAt	2025-08-08T13:28:25Z
updatedAt	2025-11-21T21:09:19Z
language	TypeScript
license	NA
branch	main
stars	13
isPublic	true
isTemplate	false
isArchived	false
isFork	false
hasReadMe	true
refreshedAt	2025-11-22T22:30:53.943Z
description
tags

claude-workshop-live

A collection of TypeScript agents and utilities for enhancing Claude Code CLI functionality with custom configurations, MCP integrations, and specialized workflows.

Prerequisites

Install Bun

This project requires Bun, a fast all-in-one JavaScript runtime. Install it using:

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Windows (via PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

# Or via npm/yarn if you have Node.js
npm install -g bun

Install Claude CLI

Make sure you have the Claude CLI installed:

npm install -g @anthropic-ai/claude-code

Quick Start

1. Clone the repository:

git clone https://github.com/johnlindquist/claude-workshop-live.git
cd claude-workshop-live

2. Install dependencies:

bun install

3. Build all agents:

bun run watch  # Watches and auto-compiles all agents
# OR
bun compile agents/designer.ts  # Compile a specific agent

Setting Up Agents as Global Commands

This project compiles TypeScript agents into standalone binaries that can be used as global commands. Here's how to set up the designer agent (or any other agent) as a global command:

Method 1: Using bun watch (Recommended for Development)

The bun watch command automatically compiles all agents in the agents/ directory and watches for changes:

# Start the watcher (compiles all agents and watches for changes)
bun run watch

This will:

• Compile all TypeScript files in agents/ to binaries in bin/
• Watch for changes in agents/ and prompts/ directories
• Automatically recompile when files change
• Remove binaries when source files are deleted

Method 2: Manual Compilation

Compile individual agents as needed:

# Compile a specific agent
bun compile agents/designer.ts

# The binary will be created at ./bin/designer

Making Agents Globally Available

After compilation, add the bin directory to your PATH to use agents as global commands:

# Add to your shell profile (~/.bashrc, ~/.zshrc, ~/.bash_profile, etc.)
export PATH="$PATH:/path/to/claude-workshop-live/bin"

# Reload your shell configuration
source ~/.zshrc  # or ~/.bashrc, depending on your shell

# Now you can use agents as commands from anywhere
designer "Create a responsive landing page"
contain "Analyze this codebase"
planner "Help me plan a new feature"

How the Designer Agent Works

The designer agent is a specialized Claude CLI launcher that:

1. Loads custom configurations: Reads settings from settings/designer.settings.json and MCP config from settings/designer.mcp.json
2. Applies system prompts: Includes a design-focused system prompt from system-prompts/designer-prompt.md
3. Enables MCP tools: Integrates with Figma and Playwright for design workflows
4. Passes through arguments: Any arguments you provide are passed to Claude

Example usage:

# After adding bin/ to PATH
designer "Create a card component with hover effects"

# Or run directly from the project
./bin/designer "Help me design a navigation menu"

# Or use bun to run the TypeScript directly
bun run agents/designer.ts "Design a color palette for a tech startup"

Project Structure

• agents/ - TypeScript agents that spawn Claude CLI with custom configs
• bin/ - Compiled standalone binaries (generated by build/watch)
• settings/ - JSON configuration files for agents
• system-prompts/ - System prompts for specialized behaviors
• prompts/ - Markdown prompt templates
• hooks/ - Scripts that run in response to Claude events
• lib/ - Core utilities for Claude CLI interaction
• scripts/ - Build and development utilities

Available Agents

Each agent is a specialized Claude instance with custom configurations:

• designer - Design mode with Figma/Playwright integrations
• contain - Isolated environment with custom settings
• planner - Strategic planning mode
• builder - Interactive building workflows
• chain - Chain multiple Claude instances
• parallel - Run parallel operations
• gemsum - Gemini-powered summarization
• claude-mix - Mixed capabilities mode
• orient - Generates a comprehensive orientation map (markdown) for a concept, feature, or file
• brainstorm - Generate 5 AI agent variations from your idea and select one to develop
• update-claudemd - Maintain and update CLAUDE.md files following best practices
• diagram-all - Project-wide, exhaustive event flow diagram generator
• diagram-topic - Generate diagrams limited to a single topic
• diagram-consolidate - Verify, deduplicate, and bundle diagrams by topic

Diagram Agents

• Run project-wide diagrams:
  • bun run agents/diagram-all.ts [optional focus words]
• Run topic-focused diagrams:
  • bun run agents/diagram-topic.ts <topic> [extra focus]
• Consolidate existing diagrams:
  • bun run agents/diagram-consolidate.ts [optional filters]

Development Commands

# Watch and auto-compile all agents
bun run watch

# Compile a specific agent
bun compile agents/[agent-name].ts

# Format and lint code
bun run lint

# Run type checking
bun run check

# Run the main entry point
bun run index.ts

Creating Your Own Agent

1. Create a new TypeScript file in agents/:

// agents/my-agent.ts
import { spawn } from "bun";

const child = spawn(["claude", "--model", "claude-3-opus", ...args], {
    stdin: "inherit",
    stdout: "inherit",
    stderr: "inherit",
});

await child.exited;

2. Create corresponding settings files (optional):

• settings/my-agent.settings.json - Claude settings
• settings/my-agent.mcp.json - MCP tool configurations

3. Compile your agent:

bun compile agents/my-agent.ts
# Creates ./bin/my-agent

4. Use your agent:

./bin/my-agent "Your prompt here"

Tips

• The watch script monitors both agents/ and prompts/ directories
• Changes to prompts trigger a full rebuild since they're imported at compile time
• Binaries are self-contained and include all dependencies
• Each agent can have its own MCP tools, settings, and system prompts
• Use environment variables like CLAUDE_PROJECT_DIR to pass context to agents

This project was created using bun init in bun v1.2.9.

Orient Agent

Generate an orientation map that traces files, dependencies, dependents, functions, event flow hints, and tests around a concept or file.

Usage:

# Analyze a concept/keyword
bun run agents/orient.ts "authentication"

# Analyze a specific file
bun run agents/orient.ts src/utils/loader.ts

# Options
bun run agents/orient.ts router --out-dir ./orientations --max-files 0 --ext ts,tsx,js,jsx,json,md --debug

Output:

• Creates a markdown file in ./orientations/ named like authentication-YYYYMMDD-HHMMSS.md.
• Sections include: Overview, Files Referencing, Dependencies/Dependents (if file target), Functions Near Topic, Event Flow Hints, Tests Touching Topic, and Next Steps.

Agents & Prompts: Behaviors and Usage Scenarios

This repo ships multiple focused agents wired to well-structured prompts. The prompts follow consistent best practices to improve reliability and parsing.

Common Prompt Expectations

• Private scratchpad: agents think step-by-step privately; outputs contain results and rationale only (no chain-of-thought).
• Structured outputs: agents emit XML-like tagged blocks per turn (e.g., <turn>, <options>, <verification>, <commit>, <next>) or domain blocks like <orientation>, <planning>, <claude_md_update>, <github_examples>, <brainstorm>.
• Code fences: labeled with language and a filename comment; changes are minimal and reversible.
• Tool safety: read before edit; avoid destructive commands; never expose secrets.
• Decision loops: many prompts present EXACTLY 3 options and block for a 1/2/3 selection or a minimal modification.

When To Use Which Agent

• designer (system-prompts/designer-prompt.md)

  • Token-first design system work (colors/typography → atoms → organisms → pages).
  • Produces <turn> blocks with 3 options, Storybook/Playwright MCP validation, and accessibility gates.
  • Use when establishing or evolving design systems with visual validation.

• builder (system-prompts/builder-prompt.md)

  • Iterative implementation from a markdown plan, per-feature <turn> with plan/preview/verification/commit.
  • User controls progression with proceed/modify/skip; tracks state and tests.
  • Use for incremental, reviewable delivery from an agreed plan.

• refactor (system-prompts/refactor-prompt.md; prompts/refactor-prompt.md)

  • Internal-structure improvements that preserve external behavior; baselines first, small reversible steps.
  • <turn> with options, parity verification, commit message, churn limits.
  • Use to pay down tech debt without changing behavior.

• feature (system-prompts/feature-prompt.md)

  • Turn a dictated feature into shippable code with verifiable acceptance criteria.
  • 3 options per step; <turn> includes verification plan before implementation.
  • Use for net-new functionality from a narrative or user story.

• fix (system-prompts/fix-prompt.md)

  • Bug remediation with mandatory failing test before patch; <turn> format.
  • Use for reliable, test-first bug fixes with guardrails.

• performance-tuner (system-prompts/performance-tuner.md)

  • Set targets, capture baselines, then smallest safe optimizations with measurement plan.
  • Use for performance work where reproducibility matters.

• planner (system-prompts/plan-generator.md)

  • Proposes plans only; does not implement code. Produces <planning> with options and a commit/file-specific plan.
  • Use to converge on an actionable plan before starting work; can be chained.

• orient (system-prompts/orient-prompt.md)

  • Orientation analysis with <orientation> output: overview, structure, tech, commands, workflow, recent, next.
  • Use when onboarding to a repo or scoping a change area.

• update-claudemd (system-prompts/update-claudemd-prompt.md)

  • Maintains CLAUDE.md; emits <claude_md_update> with summary/diff/updated file/verification.
  • Use to create or refresh project memory for Claude Code.

• brainstorm (system-prompts/brainstorm-prompt.md)

  • Generates 5 distinct agent ideas; <brainstorm> with <ideas> and a recommendation.
  • Use for ideation before committing to an approach.

• github-examples (prompts/github-examples.md)

  • Searches GitHub for real-world examples and writes ai/github-examples/<slug>.md.
  • Emits <github_examples> block with examples, comparisons, and path.
  • Use to discover patterns, validate approaches, or gather inspiration.

• claude-mix (prompts/claude-mix.md)

  • Repomix-focused flows for packing repos and generating analysis; structured outputs when saving/parsing.
  • Use to produce compact repository representations for downstream LLMs.

• claude-video / gemsum

  • Gemini-powered video analysis and summarization; claude-video can pass extracted instructions to Claude.
  • Requires GEMINI_API_KEY; writes outputs under ai/claude-video or ai/gemsum.
  • Use to extract comprehensive instructions or summaries from .mp4 content.

• jsonl-formatter(.ts/.tsx)

  • Runs Claude in JSONL print mode and demonstrates jq recipes to extract insights.
  • Use to learn/automate JSONL parsing for costs, tools, models, content, and timelines.

• parallel

  • Splits a task into independent subtasks and runs them concurrently via Claude.
  • Use to parallelize well-separated work items; be mindful of model cost.

• chain

  • Runs planner to generate a plan and then launches contain with that plan preloaded.
  • Use to move from planning → constrained execution in one command.

• contain

  • Launches Claude with repo-scoped settings/MCP (container-style environment); consistent, reproducible context.
  • Use for “standardized” sessions across machines or teams.

• Conversation utilities: latest, search, conv

  • Map current repo to ~/.claude/projects and inspect/export JSONL conversations.
  • Use to quickly find and export past sessions or generate transcripts.

Credentials & Tools

• Gemini features require GEMINI_API_KEY in the environment.
• Some agents fetch secrets via 1Password CLI (op)—ensure you’re signed in.
• GitHub MCP usage requires a valid token (see agents/github-examples.ts notes).

Runtime Consistency

• All CLI agents use a Bun shebang and handle SIGINT/SIGTERM to cleanly stop child processes.
• Prompts enforce structured outputs, three-option decision loops where relevant, and non-destructive tool use.