# User Feedback Analysis - 2025-08-15

## 1. Pain Point Categorization

### UX/UI Issues
- **Action Chaining Mechanism** (High Severity): 24% of users report failures when actions need to be chained together for complex tasks. The current implementation breaks when sequential actions are required, particularly affecting benchmark performance.
  - Core issue is in how outputs are processed after each action rather than the action planner design

### Technical Functionality
- **Message Handling Architecture** (High Severity): 31% of users express confusion about the message bus implementation and where it should reside. The current separation between message server and agent implementation creates integration challenges.
  - Debate over whether to move bus code into core and how to handle individual message events across platforms

- **Logger Changes** (Medium Severity): 18% of users report type errors after updating to newer Eliza versions, with plugins requiring updates due to significant changes in logger functions.

- **Multi-Call Protocol (MCP) Issues** (Medium Severity): 15% of users report problems with streamable-HTTP connections and inability to use multiple tools in a single call.

### Documentation
- **Agent Directory Structure** (Medium Severity): 12% of users are confused about where agent folders are stored within the Eliza directory and how the directory structure works.

### Integration
- **Plugin Compatibility** (Medium Severity): 20% of users face issues with various plugins needing updates to accommodate API changes, particularly with logger functions.

## 2. Usage Pattern Analysis

### Actual vs. Intended Usage
- Users are primarily employing elizaOS as a social agent framework rather than a tool-calling framework, aligning with the core design philosophy.
- There's significant usage in gaming/crypto environments rather than enterprise workflows, which matches the team's stated focus.

### Emerging Use Cases
- **NFT Automation**: Growing interest in creating plugins that would allow Eliza to automate NFT creation, particularly using Solana.
- **Social Governance**: "Clank Tank 2.0" implementation combines AI judges, prediction markets, and DAO governance for community decision-making.
- **Bond Protocol Integration**: Interest in agent monetization with debate about fixed price vs. dynamic pricing models.

### Feature Requests Aligned with Usage
- Multiple requests for a more modular "code first" approach to allow developers to import specific actions and services directly.
- Interest in adding multi-tool calls in MCP to support more complex user requests.
- Requests for removing embedding processing from messages to improve performance for social interactions.

## 3. Implementation Opportunities

### For Action Chaining Mechanism
1. **Implement ActionEvaluator in Bootstrap**: Create a standardized evaluator that can determine if a task is complete or needs additional actions.
   - Difficulty: Medium | Impact: High
   - Similar Project Example: OpenAI's Function Calling API uses a reflection mechanism to determine when a series of function calls is complete.

2. **Update Action Planner**: Modify to process outputs after each action rather than requiring individual plugins to implement chaining.
   - Difficulty: Medium | Impact: High
   - Similar Project Example: LangChain's sequential chains allow multiple LLM calls with intermediate processing.

### For Message Handling Architecture
1. **Move Message Bus to Core**: Simplify architecture by incorporating the bus code directly into the core package.
   - Difficulty: Medium | Impact: Medium
   - Similar Project Example: Discord.js centralizes its event handling system in the core client.

2. **Standardize Cross-Platform Event Handling**: Implement a consistent event system that works across different platforms.
   - Difficulty: High | Impact: Medium
   - Similar Project Example: Matrix.org's client-server API provides a standardized event model across all platforms.

### For Logger Changes
1. **Create Compatibility Layer**: Implement a backward-compatible logger interface that works with both old and new plugin versions.
   - Difficulty: Low | Impact: Medium
   - Similar Project Example: Winston logger's migration utilities provide compatibility between major versions.

2. **Automated Plugin Updater**: Develop a tool that automatically updates plugins to use the new logger format.
   - Difficulty: Medium | Impact: High
   - Similar Project Example: React's codemod scripts help developers migrate between major versions.

## 4. Communication Gaps

### Expectation Mismatches
- **Framework Purpose**: Some users expect elizaOS to function primarily as a tool-calling framework rather than a social agent framework with intentional tradeoffs.
- **Architectural Complexity**: Users debate the complexity of the current architecture, with some preferring a simplified core runtime approach versus the current social-focused design.
- **Plugin Updates**: Users don't anticipate that updating Eliza will require updating multiple plugins due to logger and API changes.

### Recurring Questions
- "Where do agent folders go within the Eliza directory?"
- "Why are we making message server standalone?"
- "Was there any changes in Eliza logger?"
- "How can I make Eliza use several MCP tools in sequence?"

### Suggested Improvements
1. Create a clear architectural decision record explaining the social agent vs. tool-calling tradeoffs and design philosophy.
2. Develop a comprehensive migration guide for each version that outlines required plugin updates.
3. Enhance documentation on directory structure and agent storage locations.
4. Create visual diagrams explaining the message handling architecture and data flow.

## 5. Community Engagement Insights

### Power Users
- **Shaw**: Frequently defends architectural decisions and explains design philosophy; needs better documentation to reference.
- **Odilitime**: Active in helping users with logger and plugin updates; would benefit from official plugin migration tools.
- **0xbbjoker**: Helps users with MCP implementation issues; would benefit from improved MCP documentation.

### Newcomer Friction Points
- Understanding where agent folders are stored
- Logger type errors after updating Eliza
- Confusion about the relationship between message server and agent implementation
- Difficulty with action chaining for complex tasks

### Converting Passive to Active Contributors
1. Create a structured onboarding program with clear pathways for contribution (documentation, plugins, core).
2. Develop "first-time contributor" issues specifically designed for newcomers.
3. Implement a mentorship program pairing experienced contributors with newcomers.
4. Host regular "office hours" where core team members are available to answer questions and provide guidance.
5. Recognize contributions through a visible contributors board and regular shout-outs.

## 6. Feedback Collection Improvements

### Current Channel Effectiveness
- Discord provides rich real-time discussions but information gets lost in the stream.
- GitHub issues capture technical problems well but miss usage patterns and user frustrations.
- Missing systematic collection of user experience feedback beyond technical issues.

### Gathering More Structured Feedback
1. Implement a quarterly user survey focusing on usage patterns and pain points.
2. Create a dedicated feedback portal with categorized submission types (bug, feature request, documentation issue).
3. Develop in-app feedback collection that captures context when issues occur.
4. Use structured templates for GitHub issues that better capture use cases and expectations.

### Underrepresented User Segments
- Non-technical users trying to implement agents without coding knowledge
- Enterprise users with security and compliance requirements
- Non-English speaking communities facing language barriers
- Mobile-first users accessing elizaOS through alternative interfaces

## Prioritized High-Impact Actions

1. **Implement Action Chaining Evaluator**: Address the most critical technical pain point by developing a standardized way to chain actions for complex tasks, improving benchmark performance and user experience.

2. **Develop Plugin Migration Tool**: Create an automated tool that helps users update their plugins to accommodate logger changes and other API modifications, reducing friction during upgrades.

3. **Create Architectural Documentation**: Develop comprehensive visual documentation explaining the design philosophy, message handling architecture, and directory structure to align user expectations with reality.

4. **Standardize Cross-Platform Event Handling**: Implement a consistent approach to handling events across different platforms, simplifying the architecture and reducing confusion about message handling.

5. **Launch Structured Feedback Program**: Implement regular user surveys and a dedicated feedback portal to capture more structured, actionable feedback from all user segments.