Add CLAUDE.md files for Claude Code guidance and add Groq/OpenRouter …

CLAUDE.md

@@ -0,0 +1,94 @@
+# OpenWorker Claude Code Guide
+
+## Overview
+
+OpenWorker is a desktop AI assistant application with a Python backend (coworker/) and a React/Tauri frontend (surfaces/). It uses a multi-agent system with persistent memory, tool integrations via MCP, and a skill system for progressive capability disclosure.
+
+## Key Components
+
+### Backend (coworker/)
+- `agent.py`: Main engine assembly
+- `agents/`: Different agent personalities (Code, Chat, Cowork, MyHelper)
+- `connectors/`: 25+ integrations (GitHub, Slack, Jira, Notion, HubSpot, etc.)
+- `engine.py`: Turn engine processing agent interactions
+- `mcp/`: Model Context Protocol client for tool integrations
+- `memory/`: Persistent SQLite-based memory storage
+- `providers/`: LLM providers (OpenAI, Anthropic, Gemini, Ollama, etc.)
+- `server/`: FastAPI server exposing agent functionality
+- `skills/`: Progressive disclosure skill system
+- `tools/`: Agent-available tools (file ops, shell, web search, etc.)
+
+### Frontend (surfaces/gui/)
+- `src/`: React/TypeScript frontend
+  - `App.tsx`: Root application component
+  - `components/`: Reusable UI cards, views, modals
+  - `api.ts`: Backend communication layer
+  - `tauri.ts`: Tauri bridge code
+- `src-tauri/`: Rust-based Tauri shell supervising the frontend
+- `e2e/`: Playwright end-to-end tests
+- `e2e-live/`: Live tests requiring actual services
+
+### Other Components
+- `stt/`: Rust-based speech-to-text engine
+- `packaging/`: Installer scripts and dev environment bootstrap
+- `docs/`: Design specs and decision logs
+- `ui-mocks/`: UI mockups/design assets
+- `tests/`: Backend test suite
+
+## Development Guidelines
+
+### Code Style
+- Follow existing code patterns in the codebase
+- Use type annotations in Python (PEP 484) and TypeScript
+- Keep functions focused and single-responsibility
+- Write descriptive variable and function names
+- Add comments for complex logic
+
+### Python Backend
+- Use type hints consistently
+- Follow existing error handling patterns
+- Use the agent system patterns in `coworker/agents/`
+- Follow MCP patterns in `coworker/mcp/` for tool integrations
+- Write unit tests in the `tests/` directory
+
+### Frontend (React/Tauri)
+- Follow existing React component patterns
+- Use TypeScript strictly
+- Follow existing state management patterns
+- Keep components small and reusable
+- Follow existing styling patterns in components
+
+### Making Changes
+1. Create a branch for your changes
+2. Make your changes following the existing patterns
+3. Ensure tests pass (both backend and frontend)
+4. Update documentation if needed
+5. Submit a pull request with clear description
+6. Include screenshots for UI changes
+7. Reference any related issues
+
+### Running the Application
+See `packaging/setup_dev_env.sh` for development environment setup.
+The application uses a client-server architecture where the React/Tauri frontend communicates with the Python backend via WebSocket.
+
+## Issue Reporting
+When reporting issues:
+1. Check if similar issues already exist
+2. Include steps to reproduce
+3. Include screenshots if applicable
+4. Include relevant logs from both frontend and backend
+5. Specify OS and version information
+6. Specify which agent/system is involved
+
+## Pull Request Process
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Ensure all tests pass
+5. Update documentation as needed
+6. Submit pull request with clear description
+7. Reference any related issues
+8. Await review from maintainers
+
+## License
+MIT - see LICENSE file.

coworker/CLAUDE.md

@@ -0,0 +1,203 @@
+# coworker/ Claude Code Guide
+
+## Overview
+This directory contains the Python backend for OpenWorker - the core agent engine that handles:
+- Agent reasoning and decision making
+- Tool execution and permission checking
+- Memory and conversation storage
+- Integration with external services via connectors
+- Model provider management and routing
+- Skill system and automation framework
+- WebSocket server for GUI communication
+
+## Key Subsystems
+
+### Agent System (`agents/`)
+- `base.py`: Base agent class defining the interface
+- `chat.py`: Conversational agent for general assistance
+- `code.py`: Coding assistant with development tool expertise
+- `cowork.py`: General-purpose coworker agent
+- `myhelper.py`: Personal assistant for individual tasks
+- `registry.py`: Agent discovery and instantiation
+
+### Core Engine (`engine.py`)
+- Main turn processing loop
+- Agent interaction and tool execution coordination
+- Permission checking and user approval workflows
+- Action planning and execution tracking
+
+### Memory System (`memory/`)
+- `sqlite_store.py`: Persistent conversation and context storage
+- `base.py`: Memory interface definition
+- `tools.py`: Memory-related agent tools
+
+### Connectors System (`connectors/`)
+- **Adapters**: Real-time messaging platforms (Slack, Telegram)
+- **Senders**: Stateless message sending to various services
+- **Gateway**: Inbound webhook handling and routing
+- **Relay Clients**: Cloud relay connections for managed services
+- **Tool Definitions**: MCP-compatible tool specifications
+- **Adapters**: Third-party service integrations (GitHub, Jira, etc.)
+
+### Model Providers (`providers/`)
+- **Base Interface**: Standardized provider contract
+- **Specific Providers**: OpenAI, Anthropic, Google Gemini, Ollama, etc.
+- **Router**: Model routing, caching, and capabilities detection
+- **Registry**: Provider discovery and configuration
+- **Matrix**: Curated model recommendations and labels
+
+### Tools System (`tools/`)
+- Individual tool implementations (file operations, web search, etc.)
+- Tool permissions and risk assessment
+- Tool composition and chaining capabilities
+- Custom tool development framework
+
+### Skills System (`skills/`)
+- Progressive capability disclosure mechanism
+- Skill categorization and dependency tracking
+- Skill activation and deactivation workflows
+- Built-in skills for common agent capabilities
+
+### Automation System (`automation/`)
+- Scheduled task management (`scheduler.py`)
+- Persistent storage for automation rules (`store.py`)
+- Automation-specific tools (`tools.py`)
+- Data models for scheduled work (`models.py`)
+
+### Security and Permissions
+- `permissions.py`: Main permission evaluation engine
+- `risk.py`: Risk classification system for tools
+- `secrets.py`: Secure credential storage and management
+- `config.py`: Allowed command lists and security policies
+
+## Development Guidelines
+
+### Adding New Agents
+1. Inherit from `agents.base.BaseAgent`
+2. Implement required methods: `initialize()`, `step()`, `shutdown()`
+3. Register in `agents.registry.AGENT_REGISTRY`
+4. Follow existing patterns for prompt construction and tool usage
+5. Add unit tests in `tests/test_*agent*.py`
+
+### Adding New Connectors
+1. Choose the appropriate integration pattern:
+   - Real-time: Implement `BasePlatformAdapter` (like Slack/Telegram)
+   - Stateless: Extend `connectors.senders` 
+   - Polling: Implement periodic checkers in `connectors.integration_tools`
+2. Follow security patterns for credential handling
+3. Add to `connectors.make_adapter()` factory function
+4. Create corresponding tests in `tests/test_*connectors*.py`
+
+### Adding New Model Providers
+1. Implement `ProviderClient` interface from `providers.base`
+2. Add descriptor to `providers.registry.DESCRIPTORS`
+3. Handle API key resolution following existing patterns
+4. Implement both `complete()` and `stream()` methods
+5. Add model capability detection via `providers.capabilities`
+6. Add to `providers.matrix.MATRIX` if it meets curated criteria
+7. Add comprehensive tests in `tests/test_*provider*.py`
+
+### Adding New Tools
+1. Implement function following tool signature conventions
+2. Add appropriate risk classification in `risk.py`
+3. Register in the appropriate tool category
+4. Add schema documentation for agent consumption
+5. Write tests in `tests/test_tools_*.py`
+6. Consider permission implications and test accordingly
+
+### Modifying Permissions System
+1. Understand the `RiskClass` system in `risk.py`
+2. Follow the principle of least privilege
+3. Test both allowed and denied scenarios
+4. Consider impact on different modes (PLAN, INTERACTIVE, AUTO)
+5. Update corresponding tests in `tests/test_permissions_*.py`
+
+### Working with the Agent Loop
+1. Understand the flow in `engine.py`: perceive → think → act → learn
+2. Respect the permission system - never bypass user approval for consequential actions
+3. Handle `needs_user` decisions properly by pausing for input
+4. Manage state properly across turns using the memory system
+5. Follow the tool result format for consistent agent consumption
+
+## Code Quality Standards
+
+### Type Hints
+- Use Python 3.8+ type hints consistently
+- Import typing constructs only when needed
+- Use `from __future__ import annotations` for forward references
+- Be explicit about Optional types and default values
+
+### Error Handling
+- Catch specific exceptions rather than bare `except:`
+- Provide meaningful error messages to users
+- Log unexpected errors for debugging
+- Fail gracefully and maintain system stability
+- Use custom exception types when appropriate
+
+### Logging
+- Use the standard `logging` module
+- Follow existing logger naming conventions (`logging.getLogger("coworker.subsystem")`)
+- Log at appropriate levels (DEBUG, INFO, WARNING, ERROR)
+- Avoid logging sensitive information (tokens, passwords, etc.)
+
+### Performance Considerations
+- Avoid blocking operations in async contexts
+- Use efficient data structures and algorithms
+- Consider caching for expensive operations
+- Profile before optimizing - measure first
+- Be mindful of memory usage in long-running processes
+
+### Testing Practices
+- Write tests before implementing new features (TDD when possible)
+- Achieve meaningful test coverage (>80% for new code)
+- Test both happy paths and error conditions
+- Use fixtures to reduce test setup duplication
+- Mock external dependencies appropriately
+- Test edge cases and boundary conditions
+
+## Common Patterns to Follow
+
+### Dependency Injection
+- Prefer constructor injection over global state
+- Make dependencies explicit in function signatures
+- Use interfaces/abstract classes for pluggable components
+- Keep classes focused and loosely coupled
+
+### Configuration Handling
+- Use dataclasses for configuration objects
+- Provide sensible defaults
+- Validate configuration at startup
+- Allow override via environment variables or user settings
+
+### Resource Management
+- Properly initialize and clean up resources
+- Use context managers (`with` statements) when applicable
+- Handle async resource cleanup in `__aexit__` or similar
+- Prevent resource leaks in long-running processes
+
+### Event Handling
+- Follow observer/pub-sub patterns for loose coupling
+- Use asyncio primitives for event coordination
+- Handle event ordering and race conditions appropriately
+- Provide clear unsubscription/disposal mechanisms
+
+## Debugging and Troubleshooting
+
+### Logging Strategies
+- Enable debug logging for specific subsystems when needed
+- Trace request/response flows through the system
+- Monitor performance metrics and resource usage
+- Correlate logs across components using request IDs
+
+### Common Issues
+- Circular imports: Refactor to break dependencies
+- Async/await confusion: Ensure proper coroutine handling
+- Permission denied errors: Review risk classifications and allowlists
+- Model provider failures: Check API keys and network connectivity
+- Memory leaks: Monitor object retention and cleanup
+
+### Diagnostic Tools
+- Use Python's built-in `debugger` or IDE debugging tools
+- Profile performance with `cProfile` or similar
+- Inspect state through available introspection methods
+- Check logs in the application data directory

coworker/providers/matrix.py

@@ -11,9 +11,8 @@
 degraded results. Ids verified against vendor/reseller catalogs on 2026-07-04; refresh the
 reseller rows when catalogs rotate (they rename on every model generation).
 
-Resellers: Together + Fireworks for now. TODO: add Groq and OpenRouter entries here AND their
-descriptors in ``registry.py`` once the current provider surface is tested — deliberately
-deferred to bound how much needs verifying at once.
+Resellers: Together + Fireworks, Groq, and OpenRouter.
+See corresponding entries in ``registry.py`` for providers.
 """
 
 from __future__ import annotations
@@ -112,6 +111,47 @@ class ModelEntry:
     "fireworks:accounts/fireworks/models/llama4-maverick-instruct-basic": ModelEntry(
         "Llama 4 Maverick · via Fireworks"
     ),
+    # Groq
+    "groq:llama3-8b-8192": ModelEntry(
+        "Llama 3 8B · via Groq"
+    ),
+    "groq:llama3-70b-8192": ModelEntry(
+        "Llama 3 70B · via Groq"
+    ),
+    "groq:mixtral-8x7b-32768": ModelEntry(
+        "Mixtral 8x7B · via Groq"
+    ),
+    "groq:gemma-7b-it": ModelEntry(
+        "Gemma 7B IT · via Groq"
+    ),
+    # OpenRouter
+    "openrouter:anthropic/claude-3.5-sonnet": ModelEntry(
+        "Claude 3.5 Sonnet · via OpenRouter"
+    ),
+    "openrouter:anthropic/claude-3-opus": ModelEntry(
+        "Claude 3 Opus · via OpenRouter"
+    ),
+    "openrouter:anthropic/claude-3-haiku": ModelEntry(
+        "Claude 3 Haiku · via OpenRouter"
+    ),
+    "openrouter:openai/gpt-4o": ModelEntry(
+        "GPT-4o · via OpenRouter"
+    ),
+    "openrouter:openai/gpt-4-turbo": ModelEntry(
+        "GPT-4 Turbo · via OpenRouter"
+    ),
+    "openrouter:openai/gpt-3.5-turbo": ModelEntry(
+        "GPT-3.5 Turbo · via OpenRouter"
+    ),
+    "openrouter:google/gemini-pro-1.5": ModelEntry(
+        "Gemini Pro 1.5 · via OpenRouter"
+    ),
+    "openrouter:meta-llama/llama-3-8b": ModelEntry(
+        "Llama 3 8B · via OpenRouter"
+    ),
+    "openrouter:meta-llama/llama-3-70b": ModelEntry(
+        "Llama 3 70B · via OpenRouter"
+    ),
 }
 
 

coworker/providers/registry.py

@@ -315,10 +315,24 @@ def _compat(
         env_key="META_API_KEY",
         endpoint_help="Prefilled with the Meta Model API endpoint (public preview, US-only as of 2026-07).",
     ),
+    _compat(
+        "groq",
+        "Groq",
+        base_url="https://api.groq.com/openai/v1",
+        recommended_model="llama3-8b-8192",
+        env_key="GROQ_API_KEY",
+        endpoint_help="Prefilled with Groq's OpenAI-compatible API endpoint.",
+    ),
+    _compat(
+        "openrouter",
+        "OpenRouter",
+        base_url="https://openrouter.ai/api/v1",
+        recommended_model="anthropic/claude-3.5-sonnet",
+        env_key="OPENROUTER_API_KEY",
+        endpoint_help="Prefilled with OpenRouter's OpenAI-compatible API endpoint.",
+    ),
     # Resellers: many labs' models behind one key, using THEIR model namespaces (the curated
-    # ids + display labels live in providers/matrix.py). TODO: add Groq and OpenRouter here
-    # (+ their matrix rows) once the current provider surface is tested — deliberately
-    # deferred to bound how much needs verifying at once (owner call, 2026-07-04).
+    # ids + display labels live in providers/matrix.py).
     _compat(
         "together",
         "Together AI",