diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..99dbb5d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,176 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is an AI multi-agent system called "Staff" that simulates a tech startup organization with different specialized AI agents (CEO, Product Manager, Engineers, etc.). The system integrates multiple LLM providers and implements a comprehensive task management workflow with Git-based operations.
+
+### Core Architecture
+
+- **Multi-Agent System**: Different AI agents with specialized roles (CEO, PM, Backend Engineer, Frontend Engineer, etc.)
+- **Task Management**: Git-based task tracking system with automated PR creation
+- **LLM Integration**: Unified interface supporting multiple providers (OpenAI, xAI, Claude, Gemini, local models)
+- **Agent Workflow**: Agents fetch tasks → process with LLM → create solutions → submit PRs
+
+### Key Components
+
+1. **`/server/`** - Go backend with core agent infrastructure
+   - **`agent/`** - Agent system that processes tasks autonomously using LLMs
+   - **`llm/`** - Unified LLM provider interface and factory system
+   - **`tm/`** - Task management interfaces and types
+   - **`git/`** - Git operations for PR creation and repository management
+   - **`cmd/`** - CLI commands and main entry point
+
+2. **`/operations/`** - Company operational structure
+   - **`agents/`** - Agent role definitions and system prompts
+   - **`tasks/`** - Task files and examples
+
+## Development Commands
+
+### Building and Running
+```bash
+# Build the application
+cd server && go build -o staff ./cmd/main.go
+
+# Run with specific commands
+./staff [command] [args]
+
+# Run tests
+go test ./server/...
+
+# Run specific package tests
+go test ./server/agent/...
+go test ./server/llm/...
+go test ./server/tm/...
+```
+
+### Common Development Tasks
+
+```bash
+# Format code
+go fmt ./...
+
+# Check for linting issues
+go vet ./...
+
+# Update dependencies
+go mod tidy
+
+# View available commands
+./staff --help
+```
+
+## Agent System Architecture
+
+### Agent Lifecycle
+1. **Configuration**: Each agent has a unique name, role, Git credentials, LLM provider, and system prompt
+2. **Task Processing Loop**: Continuously fetches assigned tasks from task manager
+3. **LLM Integration**: Sends task descriptions to configured LLM for solutions
+4. **Git Operations**: Creates branch, commits solution, pushes PR
+5. **Task Completion**: Marks task as completed in task management system
+
+### Agent Configuration
+- Each agent requires unique name, role, Git credentials, working directory
+- LLM configuration includes provider type, model, API credentials
+- System prompts define agent behavior and expertise area
+- Task manager integration for fetching and updating tasks
+
+### Task Management
+- Tasks have states: todo → in_progress → completed → archived
+- Task priorities: low, medium, high
+- Git-based task tracking with markdown files
+- Automated PR creation for task solutions
+
+## LLM Provider System
+
+### Supported Providers
+- OpenAI (GPT models)
+- xAI (Grok models)
+- Claude (Anthropic)
+- Gemini (Google)
+- Local models
+
+### Provider Interface
+All providers implement the same interface:
+- `ChatCompletion()` - Main chat completion endpoint
+- `CreateEmbeddings()` - Text embedding generation
+- `Close()` - Resource cleanup
+
+### Configuration
+Each provider requires:
+- API key and base URL
+- Timeout and retry settings
+- Provider-specific extra parameters
+
+## File Structure Patterns
+
+### Agent Definitions
+- Agent system prompts stored in `/operations/agents/{role}/system.md`
+- Each agent has detailed role definition and behavioral guidelines
+
+### Task Files
+- Task templates in `/operations/tasks/`
+- Format: `task-{timestamp}-{id}.md`
+- Include task metadata, description, and assignment info
+
+### Solution PRs
+- Agents create branches: `task/{task-id}-{clean-title}`
+- Solutions formatted as markdown with task metadata
+- Automated commit messages and PR descriptions
+
+## Key Dependencies
+
+### Go Modules
+- `github.com/spf13/cobra` - CLI framework
+- `github.com/google/uuid` - UUID generation
+- `github.com/stretchr/testify` - Testing framework
+- `golang.org/x/text` - Text processing
+- `gopkg.in/yaml.v3` - YAML parsing
+
+### Development Dependencies
+- Go 1.24.4+ required
+- Git for version control and PR operations
+- Access to LLM provider APIs (OpenAI, etc.)
+
+## Testing Strategy
+
+### Test Coverage
+- Unit tests for all major components
+- Agent configuration validation
+- LLM provider interface compliance
+- Task management operations
+- Git operations and branch creation
+
+### Test Execution
+```bash
+# Run all tests
+go test ./server/...
+
+# Run with coverage
+go test -cover ./server/...
+
+# Run specific test suites
+go test ./server/agent/ -v
+go test ./server/llm/ -v
+go test ./server/tm/ -v
+```
+
+## Security Considerations
+
+- API keys managed through environment variables
+- No hardcoded credentials in codebase
+- Git operations use configured user credentials
+- LLM responses processed but not executed directly
+
+## Integration Points
+
+### External Systems
+- Git repositories for task management and code storage
+- LLM provider APIs for agent intelligence
+- Task management systems (GitHub Projects, Asana, Jira)
+
+### Internal Communication
+- Agents communicate through task management system
+- PR review process for human oversight
+- Automated task assignment and completion tracking
\ No newline at end of file