Nitzan's AI Assistant

Multi-purpose AI assistant powered by Claude Agent SDK for YouTube processing, Google Workspace management, coding assistance, financial analysis, and memory.

Features

• Session Memory: Multi-turn conversations with context retention using ClaudeSDKClient
• YouTube Processing: Extract transcripts, download videos, create study notes via subagent
• Subagents: Specialized agents for YouTube processing and agent creation
• Skills System: FFmpeg/Whisper processing, skill creation
• Google Workspace: Gmail, Calendar, Drive (requires MCP setup - see GOOGLE_WORKSPACE.md)
• Coding Assistant: Debug, refactor, code review
• Financial Analysis: Calculations and data analysis
• Rich CLI: Colorful terminal UI with streaming responses
• Permission Management: Control over tool usage
• Tool Visibility: See all agent actions in real-time

Prerequisites

• Python 3.12+
• uv package manager
• Authentication: Claude subscription (default) OR Anthropic API key

Quick Start

1. Clone and navigate to project

   cd nitzan-assistant

2. Install dependencies

   uv sync

3. Authentication (Choose one)

   Option A: Claude Subscription (Recommended)

   • No setup needed! Just run the assistant
   • Uses your Claude subscription automatically

   Option B: API Key

   cp .env.example .env
   # Edit .env and uncomment: ANTHROPIC_API_KEY=your_key_here

   Get API key from: https://console.anthropic.com/

4. Run the assistant

   # Interactive mode
   uv run main.py
   
   # Single query mode
   uv run main.py "What can you help me with?"

Usage

Interactive Mode (with Session Memory)

Start the assistant in interactive REPL mode with persistent session memory:

uv run main.py

The assistant will remember your conversation across multiple turns within the session.

Commands:

• help - Show available commands and capabilities
• clear - Clear screen
• exit/quit - Exit assistant

Single Query Mode

Run one-off queries:

uv run main.py "Process this YouTube video: https://youtube.com/watch?v=..."

Architecture

Session Management

Uses ClaudeSDKClient for multi-turn conversations with context retention:

• Maintains conversation history across queries
• Remembers context within session
• Proper async context manager lifecycle

Subagents (Configured in Code)

Specialized agents invoked via Task tool:

• youtube: Process YouTube videos - transcripts, downloads, frames, study notes
  • Tools: Bash, Read, Write, WebFetch, Grep, Glob
  • Model: Sonnet
• meta-agent: Generate new subagent configuration files dynamically
  • Tools: Write, Read, WebFetch
  • Model: Opus

Skills (File-based in .claude/skills/)

Loaded from filesystem via setting_sources:

• video-processor: FFmpeg + Whisper for video/audio processing
• meta-skill: Create new skills dynamically

Custom Tools (Google Workspace)

Uses in-process custom tools via create_sdk_mcp_server():

• Drive: List, upload, download files
• Calendar: List events, create events
• Gmail: Read, send, archive, label, filter emails (15 tools total)
• Implementation: @tool decorator with direct Google API calls
• Pattern: Same-process Python functions (not external MCP servers)

See ARCHITECTURE.md for detailed explanation of custom tools vs MCP servers.

Configuration

• Session Memory: ClaudeSDKClient maintains context across turns
• Streaming: Real-time response streaming via receive_response()
• Permissions: acceptEdits mode (prompts for dangerous ops)
• Tools: Explicit allowlist (Google tools, Skills, Task, Bash, Read, Write, etc.)
• Custom Tools: In-process MCP server via create_sdk_mcp_server
• Setting Sources: ["user", "project", "local"] - loads .claude configs
• Model: Claude Sonnet (default), Opus for meta-agent
• Max turns: 100 conversation turns per session

Customization

Modify System Prompt

Edit main.py in get_agent_options() function (lines 128-145) to customize the agent's behavior.

Add New Subagents

1. Use the meta-agent to create new subagents:

   uv run main.py "Create a subagent for financial analysis"

2. Or manually add to agents dict in get_agent_options() (line 148):

   agents={
       "your-agent": {
           "description": "When to use this agent...",
           "prompt": "System prompt for agent...",
           "tools": ["Read", "Write"],
           "model": "sonnet"
       }
   }

Add New Skills

Use the meta-skill skill to create new capabilities:

uv run main.py "Create a skill for managing my calendar"

Configure Google Workspace

Google tools are already integrated! Just need to authenticate:

1. Setup OAuth (first time only):

   # Copy setup script from personal-assistant project
   python setup_google_oauth.py

   This creates storage/google_token.json with your credentials.

2. Tools available:

   • Gmail: 10 tools (list, read, send, archive, label, filter, etc.)
   • Drive: 3 tools (list, upload, download)
   • Calendar: 2 tools (list events, create event)

See ARCHITECTURE.md for how custom tools work (spoiler: NOT external MCP - simpler!)

Change Permission Mode

Edit main.py in get_agent_options() (line 119):

• acceptEdits - Prompt for dangerous operations (default)
• acceptAll - Auto-approve everything (use with caution)
• requireApproval - Prompt for all tool uses

Development

Project Structure

nitzan-assistant/
├── main.py                  # Main entry (ClaudeSDKClient + custom tools setup)
├── pyproject.toml           # Dependencies
├── .env                     # API key (optional, not in git)
├── .env.example             # Template
├── ARCHITECTURE.md          # Custom tools vs MCP explanation
├── tools/                   # Custom tools
│   ├── __init__.py
│   └── google_services.py   # GoogleTools class (15 Google Workspace tools)
├── .claude/                 # Skills and agents
│   ├── skills/              # File-based skills (loaded via setting_sources)
│   │   ├── video-processor/ # FFmpeg + Whisper skill
│   │   └── meta-skill/      # Skill creation skill
│   └── agents/              # Subagent definitions (also configured in code)
│       ├── youtube-agent.md # YouTube processing subagent
│       └── meta-agent.md    # Agent creation subagent
└── README.md

Dependencies

• claude-agent-sdk>=0.1.6 - Claude Agent SDK
• rich>=13.0.0 - Terminal UI
• python-dotenv>=1.0.0 - Environment variables
• google-api-python-client>=2.0.0 - Google APIs
• google-auth-httplib2>=0.2.0 - Google auth
• google-auth-oauthlib>=1.0.0 - Google OAuth

Troubleshooting

Authentication

By default, uses Claude subscription (no setup needed).

To use API key instead:

1. Create .env file: cp .env.example .env
2. Uncomment and set: ANTHROPIC_API_KEY=your_key_here

Import Error

ModuleNotFoundError: No module named 'claude_agent_sdk'

Solution: Run uv sync

Google Tools Not Working

[ERROR] Not authenticated with Google

Solution: Run OAuth setup:

python setup_google_oauth.py

Creates storage/google_token.json with your Google credentials.

Resources

• Claude Agent SDK Docs
• Python SDK Reference
• Get API Key

License

Private project for Nitzan