Weaverse Agent

🔗 Enhanced intelligent agent that bridges Weaverse Studio and Hydrogen theme code with Claude Code-like capabilities.

Weaverse Agent is a powerful WebSocket server that acts as an intelligent bridge between the Weaverse Builder and your local development environment. It provides Claude Code-like codebase analysis, automatic component registration, and enhanced AI context for intelligent code generation.

✨ Features

🧠 Smart Codebase Analysis

• Biome Integration - Rust-powered code analysis with 35x faster performance
• Pattern Recognition - Automatic extraction of coding patterns and style guides
• Component Discovery - Intelligent identification of reusable components
• Quality Metrics - Real-time code quality analysis and suggestions

🔧 Automatic Code Operations

• Component Registration - Auto-register components using magicast AST manipulation
• Import Optimization - Smart import resolution based on dependency analysis
• Style Consistency - Generated code matches project's Biome configuration
• File Watching - Real-time incremental analysis with chokidar

📊 Project Intelligence

• Dependency Analysis - Project structure insights with madge
• Circular Dependency Detection - Identify and prevent dependency issues
• Reusable Component Tracking - Discover components suitable for AI context
• Performance Monitoring - LRU caching and optimized analysis

🎯 AI Context Enhancement

• Rich Context Generation - Provide reusable components and patterns to AI
• Code Quality Insights - Real-time metrics for intelligent suggestions
• Component Metadata - Export information, complexity, and usage patterns
• Project Structure Awareness - Understanding of codebase organization

🚀 Quick Start

Prerequisites

• Node.js 22 or higher
• npm package manager (or pnpm/yarn)
• A Weaverse project with studio access
• Hydrogen theme project structure

Production Usage

Navigate to your theme directory and run:

cd /path/to/your/theme
npx @weaverse/agent

Development Usage

For local development with configurable working directories:

# Run with Naturelle theme
cd /path/to/weaverse-project/agent
npm run dev:naturelle

# Run with custom theme directory
AGENT_WORKING_DIR=/path/to/your/theme npm run dev

# Run with relative path
AGENT_WORKING_DIR=../my-theme npm run dev

Configuration

Environment Variables

# Required: Your Weaverse project ID
export WEAVERSE_PROJECT_ID=your-project-id

# Development: Working directory for the agent
export AGENT_WORKING_DIR=../naturelle

# Optional: Additional configuration
export WEAVERSE_API_KEY=your-api-key
export PUBLIC_STORE_DOMAIN=your-store.myshopify.com

Using .env Files

Create a .env file in your theme directory:

WEAVERSE_PROJECT_ID=your-project-id
AGENT_WORKING_DIR=.

Or in the agent directory for development:

WEAVERSE_PROJECT_ID=your-project-id
AGENT_WORKING_DIR=../naturelle

📖 Development Guide

Available Scripts

# Standard development (current directory)
npm run dev

# Development with Naturelle theme
npm run dev:naturelle

# Development with custom theme
AGENT_WORKING_DIR=/path/to/theme npm run dev

# Production build
npm run build

# Production start with Naturelle
npm run start:naturelle

Development Workflow

1. Start the agent in your theme directory:

   cd /path/to/weaverse-project/agent
   AGENT_WORKING_DIR=../naturelle npm run dev

2. Start the Builder Studio (in another terminal):

   cd /path/to/weaverse-project/builder
   pnpm dev

3. Verify connection in the Builder Studio:

   • Look for green "Agent Online" status
   • Check for blue "Enhanced" badge when advanced features are working

For detailed development setup, see DEVELOPMENT.md.

🔧 Troubleshooting

Common Issues

Agent can't find theme directory:

❌ Working directory does not exist: /path/to/theme

• Check that the path exists and you have read permissions
• Use absolute paths if relative paths don't work

Missing WEAVERSE_PROJECT_ID:

❌ WEAVERSE_PROJECT_ID is required

• Set the environment variable in your shell or .env file
• Ensure the .env file is in the correct working directory

Enhanced features not working:

• Check that all dependencies are installed (npm install)
• Verify Biome is configured in your theme project
• Look for errors in the agent console output

Debug Information

The agent provides helpful startup information:

📂 Agent working directory: /path/to/naturelle
✅ Changed working directory to: /path/to/naturelle
📁 Found sections directory: /path/to/naturelle/app/sections
👀 File watcher started successfully
🔌 Weaverse Agent ready

🙏 Acknowledgments

• Built with ❤️ by the Weaverse team
• Powered by WebSocket technology for real-time communication
• Designed for seamless developer experience

Need help? Join our Slack community or check out the documentation.