chore: add CLAUDE.md for Claude Code guidance

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: jack-arturo

CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Building and Development
+```bash
+npm run build          # Compile TypeScript to dist/
+npm run dev           # Watch mode with tsx for development
+npm start             # Run compiled server from dist/
+```
+
+### Code Quality
+```bash
+npm run lint          # ESLint on src/**/*.ts
+npm run format        # Prettier formatting on src/**/*.ts
+npm test              # Run test file
+```
+
+## Architecture
+
+### MCP Server Pattern
+This is a Model Context Protocol (MCP) server for Toggl Track time tracking:
+- Main server entry point at `src/index.ts` sets up StdioServerTransport
+- Tools are defined with JSON schemas and registered via `setRequestHandler`
+- Each tool maps to a Toggl Track API operation
+
+### File Structure
+- `src/index.ts` - MCP server entry point, tool definitions
+- `src/toggl-api.ts` - Toggl Track API client wrapper
+- `src/cache-manager.ts` - Caching layer for API responses
+- `src/types.ts` - TypeScript type definitions
+- `src/utils.ts` - Utility functions
+
+### Toggl API Integration
+The `TogglAPI` class (`src/toggl-api.ts`) wraps the Toggl Track API:
+- Uses API token authentication
+- Supports time entries, projects, clients, and reports
+- Caching layer reduces API calls for frequently accessed data
+
+### TypeScript Configuration
+- ES2022 modules with strict mode enabled
+- Compiles to ES modules (not CommonJS)
+- All imports require `.js` extensions (even for `.ts` files)
+
+## Environment Variables
+
+Required:
+- `TOGGL_API_TOKEN`: Your Toggl Track API token (get from https://track.toggl.com/profile)
+
+Optional:
+- `TOGGL_WORKSPACE_ID`: Default workspace ID
+
+## Key Implementation Patterns
+
+### Caching Strategy
+- `cache-manager.ts` provides TTL-based caching
+- Reduces API rate limiting issues
+- Cache invalidation on write operations
+
+### Error Handling
+- API errors wrapped with descriptive messages
+- Rate limiting handled with retry logic
+- Missing resources return clear error states