├── .claude
    └── commands
    │   ├── create_image.md
    │   ├── echo.md
    │   ├── edit_image.md
    │   ├── finance_categorizer.md
    │   ├── more_training_data.md
    │   ├── morning_debrief.md
    │   └── prime.md
├── .env.sample
├── .gemini
    └── settings.json.sample
├── .gitignore
├── .mcp.json.sample
├── README.md
├── ai_docs
    ├── ai_docs.md
    ├── astral-uv-single-file-scripts.md
    ├── claude-code-python-sdk.md
    └── watch-dog-python-docs.md
├── drops.yaml
├── edit_image_input_files
    └── cat_sitting_in_chair.jpg
├── example_input_files
    ├── bank_statement.csv
    ├── cats.txt
    ├── cats_edit.json
    ├── cats_enhanced.txt
    ├── echo.txt
    ├── twitter_classification_dataset.csv
    └── yt_script_5_agent_interaction_patterns_4m.mp4
├── images
    └── arch.png
├── sfs_agentic_drop_zone.py
└── specs
    └── simple_multi_processing_solution.md


/.claude/commands/create_image.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | name: Create Image
 3 | allowed-tools: Bash, mcp__replicate__create_models_predictions, mcp__replicate__get_predictions
 4 | description: Generate image(s) via Replicate
 5 | ---
 6 | 
 7 | # Create Image
 8 | 
 9 | This command generates image(s) based on the provided prompt using Replicate.
10 | 
11 | ## Variables
12 | 
13 | DROPPED_FILE_PATH: [[FILE_PATH]]
14 | DROPPED_FILE_PATH_ARCHIVE: agentic_drop_zone/generate_images_zone/drop_zone_file_archive/
15 | IMAGE_OUTPUT_DIR: agentic_drop_zone/generate_images_zone/image_output/<date_time>/
16 |     - This is the directory where all images will be saved
17 |     - The date_time is the current date and time in the format YYYY-MM-DD_HH-MM-SS
18 | MODEL: google/nano-banana
19 | ASPECT_RATIO: 16:9
20 | 
21 | ## Workflow
22 | 
23 | - First, read `DROPPED_FILE_PATH`.
24 | - Create output directory: `IMAGE_OUTPUT_DIR/<date_time>/`
25 | - IMPORTANT: For every image prompt detailed in the `DROPPED_FILE_PATH` do the following:
26 | 
27 | <image-loop>
28 |   - Use `mcp__replicate__create_models_predictions` with the MODEL specified above
29 |   - Pass image prompt as the prompt input
30 |   - Use ASPECT_RATIO for the image dimensions
31 |   - Wait for completion by polling `mcp__replicate__get_predictions`
32 |   - Save the executed prompts to `IMAGE_OUTPUT_DIR/<date_time>/image_prompt_<concise_name_based_on_prompt>.txt`
33 |     - Use the exact prompt that was executed in the `mcp__replicate__create_models_predictions` call
34 |   - Download the image: `IMAGE_OUTPUT_DIR/<date_time>/<MODEL_NAME_underscore_separated>_<concise_name_based_on_prompt>.jpg`
35 |   - Display:
36 |     - Generation time
37 |     - File size
38 |     - Full path to saved image
39 | </image-loop>
40 | - After all images are generated, open the output directory: `open IMAGE_OUTPUT_DIR/<date_time>/`
41 | - When you finish generating images, move the `DROPPED_FILE_PATH` into a `DROPPED_FILE_PATH_ARCHIVE` directory


--------------------------------------------------------------------------------
/.claude/commands/echo.md:
--------------------------------------------------------------------------------
 1 | # Echo Command
 2 | 
 3 | Echo the contents of the file at DROPPED_FILE_PATH and provide a brief summary.
 4 | 
 5 | ## Variables
 6 | 
 7 | DROPPED_FILE_PATH: [[FILE_PATH]]
 8 | DROPPED_FILE_PATH_ARCHIVE: agentic_drop_zone/echo_zone/drop_zone_file_archive/
 9 | 
10 | ## Workflow
11 | 1. Read the file contents at DROPPED_FILE_PATH
12 | 2. Write out the file in between a markdown code block
13 | 3. Below log the total number of characters in the file and the file name
14 | 4. Move the file to the archive: `mv DROPPED_FILE_PATH DROPPED_FILE_PATH_ARCHIVE/`
15 | 
16 | ## Example Output Format
17 | 
18 | ```
19 | <file_contents>
20 | 
21 | total characters: <number_of_characters>
22 | file name: <file_name>
23 | ```
24 | 


--------------------------------------------------------------------------------
/.claude/commands/edit_image.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | name: Edit Image
 3 | allowed-tools: Bash, Read
 4 | description: Edit existing images via Replicate using direct curl API calls
 5 | ---
 6 | 
 7 | # Edit Image
 8 | 
 9 | This command edits existing images based on provided edit prompts using Replicate's API directly via curl.
10 | 
11 | ## Prerequisites
12 | 
13 | - REPLICATE_API_TOKEN must be exported in the environment
14 | - Requires base64 command for inline image encoding
15 | 
16 | ## Variables
17 | 
18 | DROPPED_FILE_PATH: [[FILE_PATH]]
19 | DROPPED_FILE_PATH_ARCHIVE: agentic_drop_zone/edit_images_zone/drop_zone_file_archive/
20 | IMAGE_OUTPUT_DIR: agentic_drop_zone/edit_images_zone/image_output/<date_time>/
21 |     - This is the directory where all images will be saved
22 |     - The date_time is the current date and time in the format YYYY-MM-DD_HH-MM-SS
23 | MODEL: google/nano-banana
24 | API_ENDPOINT: https://api.replicate.com/v1/models/google/nano-banana/predictions
25 | 
26 | ## Workflow
27 | 
28 | - Note: REPLICATE_API_TOKEN will be available, don't search for it and NEVER read the .env file directly.   
29 |   - IMPORTANT: If for some reason you run into issues with authentication, abort immediately - do not continue with any image processing. Mention that the REPLICATE_API_TOKEN might be missing.
30 | - First, read `DROPPED_FILE_PATH`.
31 | - Create output directory: `IMAGE_OUTPUT_DIR/<date_time>/`
32 | - IMPORTANT: For every image edit detailed in the `DROPPED_FILE_PATH` do the following:
33 | 
34 | <image-loop>
35 |   - Extract the source image path and edit prompt from the dropped file
36 |   - Use curl with inline base64 encoding to send image directly to Replicate API:
37 |     ```bash
38 |     curl -s -X POST \
39 |       -H "Authorization: Bearer $REPLICATE_API_TOKEN" \
40 |       -H "Content-Type: application/json" \
41 |       -H "Prefer: wait" \
42 |       -d '{
43 |         "input": {
44 |           "prompt": "YOUR_EDIT_PROMPT_HERE",
45 |           "image_input": ["data:image/jpeg;base64,'$(base64 -i /path/to/source/image.jpg)'"],
46 |           "output_format": "jpg"
47 |         }
48 |       }' \
49 |       https://api.replicate.com/v1/models/google/nano-banana/predictions
50 |     ```
51 |   - IMPORTANT: Replace `YOUR_EDIT_PROMPT_HERE` with the actual edit instruction
52 |   - IMPORTANT: Replace `/path/to/source/image.jpg` with the actual source image path which should be detailed in the `DROPPED_FILE_PATH`
53 |   - IMPORTANT: The base64 encoding happens inline using `$(base64 -i /path/to/image.jpg)`
54 |   - Parse JSON response to extract the `output` URL field for the generated image
55 |     - Response format: `{"id":"...", "output":"https://replicate.delivery/...jpg", "status":"succeeded"}`
56 |     - Extract URL with `jq -r '.output'`
57 |   - Save the executed edit prompts to `IMAGE_OUTPUT_DIR/<date_time>/edit_prompt_<concise_name_based_on_prompt>.txt`
58 |     - Include both the source image path and the exact edit prompt that was executed
59 |   - Download the edited image from the output URL: `curl -o IMAGE_OUTPUT_DIR/<date_time>/<MODEL_NAME_underscore_separated>_edited_<concise_name_based_on_prompt>.jpg "OUTPUT_URL"`
60 |   - Display:
61 |     - Source image path
62 |     - Edit prompt used
63 |     - Generation time (if available in response)
64 |     - File size of downloaded image
65 |     - Full path to saved edited image
66 |     - Replicate output URL for reference
67 | </image-loop>
68 | 
69 | - After all images are edited, copy all original source images to the output directory for reference:
70 |   - For each source image that was processed, copy it with "original_" prefix
71 |   - Example: `cp /path/to/cat.jpg IMAGE_OUTPUT_DIR/<date_time>/original_cat.jpg`
72 |   - This allows easy before/after comparison in the same directory
73 | - After copying originals, open the output directory: `open IMAGE_OUTPUT_DIR/<date_time>/`
74 | - When you finish editing images, move the `DROPPED_FILE_PATH` into a `DROPPED_FILE_PATH_ARCHIVE` directory
75 | 
76 | ## Example Usage
77 | 
78 | ```bash
79 | # The REPLICATE_API_TOKEN is sourced from the .env file
80 | 
81 | 
82 | # Execute image edit with inline base64 encoding
83 | RESPONSE=$(curl -s -X POST \
84 |   -H "Authorization: Bearer $REPLICATE_API_TOKEN" \
85 |   -H "Content-Type: application/json" \
86 |   -H "Prefer: wait" \
87 |   -d '{
88 |     "input": {
89 |       "prompt": "Make the cat blue",
90 |       "image_input": ["data:image/jpeg;base64,'$(base64 -i ./source_image.jpg)'"],
91 |       "output_format": "jpg"
92 |     }
93 |   }' \
94 |   https://api.replicate.com/v1/models/google/nano-banana/predictions)
95 | 
96 | # Extract output URL and download
97 | OUTPUT_URL=$(echo "$RESPONSE" | jq -r '.output')
98 | curl -o edited_image.jpg "$OUTPUT_URL"
99 | ```


--------------------------------------------------------------------------------
/.claude/commands/finance_categorizer.md:
--------------------------------------------------------------------------------
  1 | # Finance Categorizer
  2 | 
  3 | This command analyzes bank statement CSV files, corrects missing or incorrect categorizations, and generates comprehensive spending reports with visual indicators for high spending areas.
  4 | 
  5 | ## Instructions
  6 | 
  7 | - IMPORTANT: Use inline astral uv python code (with any libraries you need) to calculate the totals and percentages. Use `uv run python --with pandas --with <whatever library you need> -c "import pandas as pd; print(\"whatever you want here\")"` to test your code.
  8 |   - Example: `uv run --with rich python -c "from rich.console import Console; Console().print('Hello', style='bold red')"`
  9 | - IMPORTANT: Think hard about your calculations ALWAYS double check your work as you go along.
 10 | - IMPORTANT: After you generate your report, review your numbers comprehensively with python. Also, make sure you write emojis and not unicode characters.
 11 | - In your finance_report.yaml file, do not use yaml anchors or aliases and do not use !!python tags. Write everything out as primitive types even if it means duplicating data.
 12 | 
 13 | ## Variables
 14 | 
 15 | DROPPED_FILE_PATH: [[FILE_PATH]]
 16 | DROPPED_FILE_PATH_ARCHIVE: agentic_drop_zone/finance_zone/drop_zone_file_archive/
 17 | FINANCE_OUTPUT_DIR: agentic_drop_zone/finance_zone/finance_output/<date_time>/
 18 |     - This is the directory where all processed files and reports will be saved
 19 |     - The date_time is the current date and time in the format YYYY-MM-DD_HH-MM-SS
 20 | 
 21 | ### Output File Paths
 22 | CATEGORIZED_STATEMENT: FINANCE_OUTPUT_DIR/<date_time>/categorized_statement.csv
 23 |     - The cleaned and properly categorized bank statement
 24 | FINANCE_REPORT: FINANCE_OUTPUT_DIR/<date_time>/finance_report.yaml
 25 |     - The comprehensive financial analysis report in YAML format
 26 | SPENDING_PIE_CHART: FINANCE_OUTPUT_DIR/<date_time>/spending_by_category.png
 27 |     - Pie chart visualization of spending by category
 28 | BALANCE_LINE_CHART: FINANCE_OUTPUT_DIR/<date_time>/balance_over_time.png
 29 |     - Line chart showing account balance progression over time
 30 | 
 31 | ### Spending Thresholds (per category monthly spending)
 32 | LOW_SPENDING_THRESHOLD: 500
 33 |     - Categories under this amount get 💰 emoji
 34 | MODERATE_SPENDING_THRESHOLD: 1000  
 35 |     - Categories between LOW and MODERATE get 🔥 emoji
 36 | HIGH_SPENDING_THRESHOLD: 2000
 37 |     - Categories between MODERATE and HIGH get 🔥🔥 emoji
 38 |     - Categories over HIGH get 🔥🔥🔥 emoji
 39 | 
 40 | ### Individual Transaction Alerts
 41 | LARGE_TRANSACTION: 500
 42 |     - Single transactions over this get 🚨 flag
 43 | UNUSUAL_TRANSACTION: 1000
 44 |     - Single transactions over this get ⚠️ flag
 45 | MAJOR_PURCHASE: 2500
 46 |     - Single transactions over this get 🔴 flag
 47 | 
 48 | ### Budget Warning Percentages
 49 | HOUSING_WARNING_PCT: 30
 50 |     - Alert if housing > this % of monthly income
 51 | DINING_ENTERTAINMENT_WARNING_PCT: 20
 52 |     - Alert if dining/entertainment > this % of total expenses
 53 | SHOPPING_WARNING_PCT: 15
 54 |     - Alert if shopping > this % of total expenses
 55 | TRANSPORTATION_WARNING_PCT: 20
 56 |     - Alert if transportation > this % of total expenses
 57 | SUBSCRIPTION_WARNING_PCT: 10
 58 |     - Alert if subscriptions > this % of total expenses
 59 | 
 60 | ## Workflow
 61 | 
 62 | ### Setup Phase
 63 | - Create output directory: `mkdir -p FINANCE_OUTPUT_DIR/<date_time>/`
 64 | - Copy original file to preserve it: `cp DROPPED_FILE_PATH FINANCE_OUTPUT_DIR/<date_time>/original_statement.csv`
 65 | - Create working copy: `cp FINANCE_OUTPUT_DIR/<date_time>/original_statement.csv FINANCE_OUTPUT_DIR/<date_time>/categorized_statement.csv`
 66 | 
 67 | ### Analysis & Categorization Phase
 68 | - Read the working copy: `FINANCE_OUTPUT_DIR/<date_time>/categorized_statement.csv`
 69 | - For each transaction row:
 70 |   - Check if category is missing or incorrect
 71 |   - Apply categorization rules from "How to Categorize" section
 72 |   - Track which categories need updating
 73 | - Use MultiEdit to update all categories at once in the working copy
 74 | - Verify all transactions now have appropriate categories
 75 | 
 76 | ### Calculation Phase
 77 | - Calculate totals:
 78 |   - Total income = sum of all deposits
 79 |   - Total expenses = sum of all withdrawals
 80 |   - Net cash flow = income - expenses
 81 | - Group expenses by category and calculate:
 82 |   - Total spending per category
 83 |   - Number of transactions per category
 84 |   - Percentage of total expenses per category
 85 | - Identify top 5 spending categories
 86 | - Identify top 5 largest individual transactions
 87 | - Count transactions exceeding alert thresholds
 88 | 
 89 | ### Report Generation Phase
 90 | - Create report file: `FINANCE_OUTPUT_DIR/<date_time>/finance_report.yaml`
 91 | - Generate visualization charts as PNG files (use matplotlib with optional seaborn for styling):
 92 |   1. **Spending Pie Chart** (`FINANCE_OUTPUT_DIR/<date_time>/spending_by_category.png`):
 93 |      - Use matplotlib or plotly to create a pie chart
 94 |      - Show top 10 categories by spending amount
 95 |      - Include percentages and dollar amounts on labels
 96 |      - Use distinct colors for each category
 97 |      - Title: "Monthly Spending by Category - [Month Year]"
 98 |      - Figure size: 12x8 inches
 99 |      - DPI: 150 for high quality
100 |      - Add legend with category names and amounts
101 |      - Explode the largest spending category slightly for emphasis
102 |      - Example command:
103 |        ```bash
104 |        uv run --with pandas --with matplotlib python -c "
105 |        import pandas as pd
106 |        import matplotlib.pyplot as plt
107 |        # Read categorized data
108 |        df = pd.read_csv('categorized_statement.csv')
109 |        # Group by category and sum withdrawals
110 |        # Create pie chart with top 10 categories
111 |        # plt.figure(figsize=(12, 8))
112 |        # plt.savefig('spending_by_category.png', dpi=150, bbox_inches='tight')
113 |        "
114 |        ```
115 |   
116 |   2. **Account Balance Chart** (`FINANCE_OUTPUT_DIR/<date_time>/balance_over_time.png`):
117 |      - Create a line chart showing balance progression through the month
118 |      - X-axis: dates (formatted as MM/DD)
119 |      - Y-axis: running balance (formatted with $ and commas)
120 |      - Mark major transactions (>$1000) with red dots and annotations
121 |      - Add horizontal dashed line for starting balance
122 |      - Add horizontal dotted line for ending balance
123 |      - Include grid for better readability
124 |      - Title: "Account Balance Over Time - [Month Year]"
125 |      - Figure size: 14x7 inches
126 |      - DPI: 150 for high quality
127 |      - Use gradient fill below the line (green for positive, red for negative if applicable)
128 |      - Add min/max balance annotations
129 |      - Example command:
130 |        ```bash
131 |        uv run --with pandas --with matplotlib python -c "
132 |        import pandas as pd
133 |        import matplotlib.pyplot as plt
134 |        import matplotlib.dates as mdates
135 |        # Read categorized data
136 |        df = pd.read_csv('categorized_statement.csv')
137 |        # Convert date column to datetime
138 |        # plt.figure(figsize=(14, 7))
139 |        # Plot balance over time with styling
140 |        # Annotate major transactions
141 |        # plt.savefig('balance_over_time.png', dpi=150, bbox_inches='tight')
142 |        "
143 |        ```
144 | 
145 | - Generate YAML report with the following structure:
146 | 
147 | ```yaml
148 | report_date: YYYY-MM-DD HH:MM:SS
149 | month_analyzed: August 2025
150 | 
151 | financial_summary:
152 |   total_income: 20000.00
153 |   total_expenses: 74567.89
154 |   net_cash_flow: -54567.89
155 |   cash_flow_status: negative  # positive or negative
156 |   transactions_analyzed: 87
157 | 
158 | top_spending_categories:
159 |   - category: "AI Services"
160 |     amount: 45678.90
161 |     emoji: "🔥🔥🔥"  # Based on thresholds
162 |     percentage: 61.2
163 |     transaction_count: 23
164 |   - category: "Technology - Cloud"
165 |     amount: 12345.67
166 |     emoji: "🔥🔥🔥"
167 |     percentage: 16.5
168 |     transaction_count: 15
169 |   # ... top 5
170 | 
171 | largest_transactions:
172 |   - date: "2025-08-29"
173 |     description: "ANTHROPIC CLAUDE-OPUS-4-1-API"
174 |     amount: 6789.01
175 |     category: "AI Services"
176 |     alert: "🔴"  # Based on individual thresholds
177 |   - date: "2025-08-22"
178 |     description: "AWS MONTHLY BILLING 866-216-1072"
179 |     amount: 5678.90
180 |     category: "Technology"
181 |     alert: "🔴"
182 |   # ... top 5
183 | 
184 | all_categories:
185 |   - category: "AI Services"
186 |     amount: 45678.90
187 |     transactions: 23
188 |     percentage: 61.2
189 |   - category: "Amazon"
190 |     amount: 23456.78
191 |     transactions: 18
192 |     percentage: 31.4
193 |   # ... all categories sorted by amount
194 | 
195 | budget_warnings:
196 |   - type: "Housing"
197 |     actual_percentage: 21.0
198 |     recommended_max: 30
199 |     status: "OK"
200 |   - type: "Shopping"
201 |     actual_percentage: 31.4
202 |     recommended_max: 15
203 |     status: "⚠️ EXCEEDED"
204 |   # ... check all warning categories
205 | 
206 | transaction_alerts:
207 |   major_purchases:  # Over MAJOR_PURCHASE threshold
208 |     count: 12
209 |     total: 45678.90
210 |   unusual_transactions:  # Over UNUSUAL_TRANSACTION threshold
211 |     count: 28
212 |     total: 67890.12
213 |   large_transactions:  # Over LARGE_TRANSACTION threshold
214 |     count: 45
215 |     total: 89012.34
216 | 
217 | insights:
218 |   highest_spending_day:
219 |     date: "2025-08-29"
220 |     amount: 9234.56
221 |   most_frequent_merchant:
222 |     name: "AMAZON"
223 |     count: 18
224 |   total_amazon_spending: 23456.78
225 |   subscription_count: 6
226 |   
227 | subscriptions_detected:
228 |   - name: "Netflix"
229 |     amount: 15.99
230 |   - name: "Spotify"
231 |     amount: 9.99
232 |   - name: "AWS"
233 |     amount: 5678.90
234 |   # ... all recurring charges
235 | 
236 | recommendations:
237 |   - "AI Services spending (61.2%) is extremely high - review API usage and consider optimization"
238 |   - "Shopping exceeds budget by 16.4% - consider reducing Amazon purchases"
239 |   - "Multiple AWS charges detected - consolidate billing or review unused services"
240 | 
241 | visualizations:
242 |   spending_pie_chart: "spending_by_category.png"
243 |   balance_line_chart: "balance_over_time.png"
244 | ```
245 | 
246 | ### Completion Phase
247 | - Save the categorized statement and report
248 | - Display summary in console:
249 |   ```
250 |   ✅ Processing Complete
251 |   - Transactions processed: XX
252 |   - Categories fixed: XX
253 |   - Files created:
254 |     - categorized_statement.csv
255 |     - finance_report.yaml
256 |     - spending_by_category.png
257 |     - balance_over_time.png
258 |   ```
259 | - Open output directory: `open FINANCE_OUTPUT_DIR/<date_time>/`
260 | - Archive the original: `mv DROPPED_FILE_PATH DROPPED_FILE_PATH_ARCHIVE/`
261 | 
262 | ## How to Categorize
263 | 
264 | Apply these rules in order of priority:
265 | 
266 | ### Priority 1: Merchant-Specific Mappings
267 | - AMAZON (any mention including AMZN but not AWS) → `Amazon`
268 | - AWS (Amazon Web Services) → `Technology - Cloud`
269 | - ANTHROPIC, CLAUDE → `AI Services`
270 | - OPENAI, GPT, DALL-E → `AI Services`
271 | - GOOGLE NANO-BANANA → `AI Services`
272 | - GOOGLE COMPUTE, COMPUTE ENGINE, EC2, VM, INSTANCE → `Compute`
273 | - TARGET → `Retail Shopping`
274 | - WALMART, COSTCO, SAM'S CLUB → `Wholesale Shopping`
275 | - SAFEWAY, KROGER, WHOLE FOODS, TRADER JOE'S → `Groceries`
276 | - UBER (not UBER EATS), LYFT, TAXI → `Transportation - Rideshare`
277 | - SHELL, CHEVRON, EXXON, GAS STATION → `Transportation - Gas`
278 | - TESLA, CAR PAYMENT → `Transportation - Auto`
279 | - NETFLIX, HULU, SPOTIFY, APPLE MUSIC → `Entertainment - Streaming`
280 | - STARBUCKS, COFFEE, CAFE, BLUE BOTTLE, PHILZ → `Dining - Coffee`
281 | - RESTAURANT, BISTRO, SUSHI, PIZZA → `Dining - Restaurant`
282 | - UBER EATS, DOORDASH, GRUBHUB → `Dining - Delivery`
283 | - CHIPOTLE, MCDONALD'S, SUBWAY → `Dining - Fast Food`
284 | 
285 | ### Priority 2: Keyword-Based Rules
286 | - MORTGAGE, RENT → `Housing - Primary`
287 | - ELECTRIC, PG&E, WATER, UTILITY → `Utilities`
288 | - INSURANCE → `Insurance - [Type]` (Auto/Health/Life based on context)
289 | - GYM, FITNESS, EQUINOX, YOGA → `Health - Fitness`
290 | - DOCTOR, DENTIST, MEDICAL, DR → `Health - Medical`
291 | - PHARMACY, CVS, WALGREENS → `Health - Pharmacy`
292 | - PAYROLL, SALARY, DIRECT DEPOSIT, ACH CREDIT → `Income - Salary`
293 | - TAX, IRS, COUNTY TAX → `Taxes`
294 | - INVESTMENT, SCHWAB, FIDELITY, VANGUARD → `Investment`
295 | - PHONE, VERIZON, AT&T, T-MOBILE → `Utilities - Phone`
296 | - INTERNET, XFINITY, COMCAST → `Utilities - Internet`
297 | - PET, VET, PETCO → `Pet Care`
298 | - HOME DEPOT, LOWE'S → `Home Improvement`
299 | - PARKING METER, PARKING → `Transportation - Parking`
300 | - AIRLINE, HOTEL, AIRBNB → `Travel`
301 | - APPLE STORE, BEST BUY → `Shopping - Electronics`
302 | - NORDSTROM, GAP, H&M → `Shopping - Clothing`
303 | 
304 | ### Priority 3: Default Categories
305 | - Deposits without clear source → `Income - Other`
306 | - Withdrawals without clear purpose → `Cash Withdrawal`
307 | - Any Amazon not categorized → `Amazon`
308 | - Food-related uncategorized → `Groceries`
309 | - Service-related uncategorized → `Services`
310 | - Retail uncategorized → `Shopping - General`
311 | 
312 | ## My Categories
313 | 
314 | - `AI Services`
315 | - `Amazon`
316 | - `Banking Fees`
317 | - `Cash Withdrawal`
318 | - `Cloud Computing`
319 | - `Compute`
320 | - `Dining - Coffee`
321 | - `Dining - Delivery`
322 | - `Dining - Fast Food`
323 | - `Dining - Restaurant`
324 | - `Entertainment - General`
325 | - `Entertainment - Streaming`
326 | - `Groceries`
327 | - `Health - Fitness`
328 | - `Health - Medical`
329 | - `Health - Pharmacy`
330 | - `Home Improvement`
331 | - `Housing - Primary`
332 | - `Income - Other`
333 | - `Income - Salary`
334 | - `Insurance - Auto`
335 | - `Insurance - Health`
336 | - `Insurance - Life`
337 | - `Investment`
338 | - `Miscellaneous`
339 | - `Pet Care`
340 | - `Retail Shopping`
341 | - `Services`
342 | - `Shopping - Clothing`
343 | - `Shopping - Electronics`
344 | - `Shopping - General`
345 | - `Taxes`
346 | - `Technology - Cloud`
347 | - `Technology - Software`
348 | - `Transportation - Auto`
349 | - `Transportation - Gas`
350 | - `Transportation - Parking`
351 | - `Transportation - Rideshare`
352 | - `Travel`
353 | - `Utilities`
354 | - `Utilities - Internet`
355 | - `Utilities - Phone`
356 | - `Wholesale Shopping`


--------------------------------------------------------------------------------
/.claude/commands/more_training_data.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | name: Generate More Training Data
  3 | allowed-tools: Bash, Read, Write
  4 | description: Analyze data patterns and generate additional synthetic training data
  5 | ---
  6 | 
  7 | # Generate More Training Data
  8 | 
  9 | This command analyzes patterns in existing data files (CSV, JSONL) and generates additional synthetic training data based on those patterns. Uses bash commands or inline uv python to append data efficiently without loading large files into memory.
 10 | 
 11 | ## Instructions
 12 | 
 13 | - IMPORTANT: You can use inline astral uv python code (with any libraries you need) for data processing. Use `uv run python --with pandas --with <whatever library you need> -c "import pandas as pd; print(\"whatever you want here\")"` 
 14 |   - Example: `uv run --with pandas --with faker python -c "import pandas as pd; from faker import Faker; fake = Faker(); print(fake.name())"`
 15 | - IMPORTANT: Both bash commands and uv python are acceptable - choose the most efficient approach for each task
 16 | - IMPORTANT: When generating synthetic data, ensure variety and realistic patterns
 17 | 
 18 | ## Variables
 19 | 
 20 | DROPPED_FILE_PATH: [[FILE_PATH]]
 21 | DROPPED_FILE_PATH_ARCHIVE: agentic_drop_zone/training_data_zone/drop_zone_file_archive/
 22 | DATA_OUTPUT_DIR: agentic_drop_zone/training_data_zone/data_output/<date_time>/
 23 |     - This is the directory where all generated data will be saved
 24 |     - The date_time is the current date and time in the format YYYY-MM-DD_HH-MM-SS
 25 | NUM_NEW_ROWS: 25
 26 |     - Default number of new data rows to generate
 27 |     - Can be overridden if specified in the dropped file
 28 | SAMPLE_SIZE: 50
 29 |     - Number of rows to sample for pattern analysis (keeps context window small)
 30 |     - Use Read with only a specific number of rows to keep the context window small
 31 | 
 32 | ## Workflow
 33 | 
 34 | - Create output directory: `DATA_OUTPUT_DIR/<date_time>/`
 35 | - Determine file format by extension (.csv or .jsonl)
 36 | - Copy the original file to output directory: `cp DROPPED_FILE_PATH DATA_OUTPUT_DIR/<date_time>/original_<filename>`
 37 | 
 38 | ### Pattern Analysis Phase
 39 | 
 40 | - Extract a sample for analysis (to keep context window small):
 41 |   
 42 |   **Option 1: Using bash commands**
 43 |   - For CSV: `head -n SAMPLE_SIZE DROPPED_FILE_PATH > DATA_OUTPUT_DIR/<date_time>/sample.csv`
 44 |   - For JSONL: `head -n SAMPLE_SIZE DROPPED_FILE_PATH > DATA_OUTPUT_DIR/<date_time>/sample.jsonl`
 45 |   
 46 |   **Option 2: Using uv python**
 47 |   ```bash
 48 |   # For CSV
 49 |   uv run --with pandas python -c "
 50 |   import pandas as pd
 51 |   df = pd.read_csv('DROPPED_FILE_PATH', nrows=100)
 52 |   df.to_csv('DATA_OUTPUT_DIR/<date_time>/sample.csv', index=False)
 53 |   print(f'Sampled {len(df)} rows for analysis')
 54 |   "
 55 |   
 56 |   # For JSONL
 57 |   uv run --with pandas python -c "
 58 |   import pandas as pd
 59 |   df = pd.read_json('DROPPED_FILE_PATH', lines=True, nrows=100)
 60 |   df.to_json('DATA_OUTPUT_DIR/<date_time>/sample.jsonl', orient='records', lines=True)
 61 |   print(f'Sampled {len(df)} rows for analysis')
 62 |   "
 63 |   ```
 64 | 
 65 | - Read and analyze ONLY the sample file to determine:
 66 |   - Data schema/structure
 67 |   - Field types and patterns
 68 |   - Value distributions and constraints
 69 |   - Any relationships between fields
 70 | 
 71 | **For CSV files:**
 72 | - Identify column headers from first line
 73 | - Detect data types for each column (numeric, text, date, boolean, etc.)
 74 | - Analyze value ranges for numeric columns
 75 | - Identify patterns in text fields (emails, phone numbers, IDs, etc.)
 76 | - Check for categorical values and their distributions
 77 | 
 78 | **For JSONL files:**
 79 | - Parse each line as a separate JSON object
 80 | - Identify all keys and their data types
 81 | - Detect enumerated values and their frequencies
 82 | - Identify any ID patterns or sequences
 83 | - Note: Each line must be a complete, valid JSON object
 84 | 
 85 | ### Data Generation Phase
 86 | 
 87 | - Based on the pattern analysis, generate `NUM_NEW_ROWS` new data entries
 88 | - Write the new data to a separate file:
 89 |   - For CSV: `DATA_OUTPUT_DIR/<date_time>/new_rows.csv` (without headers)
 90 |   - For JSONL: `DATA_OUTPUT_DIR/<date_time>/new_rows.jsonl`
 91 | 
 92 |   **Example using uv python with faker:**
 93 |   ```bash
 94 |   # Generate synthetic CSV data
 95 |   uv run --with pandas --with faker python -c "
 96 |   import pandas as pd
 97 |   from faker import Faker
 98 |   import random
 99 |   fake = Faker()
100 |   
101 |   # Generate 25 rows of synthetic data based on analyzed patterns
102 |   data = []
103 |   for i in range(25):
104 |       row = {
105 |           'id': i + 1000,  # Continue from existing IDs
106 |           'name': fake.name(),
107 |           'email': fake.email(),
108 |           'age': random.randint(22, 65),
109 |           'department': random.choice(['Engineering', 'Marketing', 'Sales', 'Support'])
110 |       }
111 |       data.append(row)
112 |   
113 |   df = pd.DataFrame(data)
114 |   df.to_csv('DATA_OUTPUT_DIR/<date_time>/new_rows.csv', index=False, header=False)
115 |   print(f'Generated {len(df)} new rows')
116 |   "
117 |   ```
118 | 
119 | - Generated data should:
120 |   - Follow the same structure as the original
121 |   - Maintain realistic value distributions
122 |   - Preserve relationships between fields
123 |   - Use similar patterns for IDs, dates, etc.
124 |   - Include variation to avoid exact duplicates
125 |   - Maintain data integrity constraints observed in original
126 | 
127 | ### Append Phase
128 | 
129 | - Create the extended dataset by appending new rows to a copy of the original:
130 | 
131 |   **Option 1: Using bash commands**
132 |   
133 |   For CSV:
134 |   ```bash
135 |   # Copy original to extended file
136 |   cp DATA_OUTPUT_DIR/<date_time>/original_<filename> DATA_OUTPUT_DIR/<date_time>/extended_data.csv
137 |   
138 |   # Append new rows (skip header if present in new_rows.csv)
139 |   tail -n +2 DATA_OUTPUT_DIR/<date_time>/new_rows.csv >> DATA_OUTPUT_DIR/<date_time>/extended_data.csv
140 |   ```
141 |   
142 |   For JSONL:
143 |   ```bash
144 |   # Copy original to extended file
145 |   cp DATA_OUTPUT_DIR/<date_time>/original_<filename> DATA_OUTPUT_DIR/<date_time>/extended_data.jsonl
146 |   
147 |   # Append new rows
148 |   cat DATA_OUTPUT_DIR/<date_time>/new_rows.jsonl >> DATA_OUTPUT_DIR/<date_time>/extended_data.jsonl
149 |   ```
150 | 
151 |   **Option 2: Using uv python**
152 |   
153 |   For CSV:
154 |   ```bash
155 |   uv run --with pandas python -c "
156 |   import pandas as pd
157 |   
158 |   # Read original and new data
159 |   original = pd.read_csv('DATA_OUTPUT_DIR/<date_time>/original_<filename>')
160 |   new_rows = pd.read_csv('DATA_OUTPUT_DIR/<date_time>/new_rows.csv', header=None, names=original.columns)
161 |   
162 |   # Combine and save
163 |   extended = pd.concat([original, new_rows], ignore_index=True)
164 |   extended.to_csv('DATA_OUTPUT_DIR/<date_time>/extended_data.csv', index=False)
165 |   print(f'Extended dataset: {len(original)} -> {len(extended)} rows')
166 |   "
167 |   ```
168 |   
169 |   For JSONL:
170 |   ```bash
171 |   uv run --with pandas python -c "
172 |   import pandas as pd
173 |   
174 |   # Read original and new data
175 |   original = pd.read_json('DATA_OUTPUT_DIR/<date_time>/original_<filename>', lines=True)
176 |   new_rows = pd.read_json('DATA_OUTPUT_DIR/<date_time>/new_rows.jsonl', lines=True)
177 |   
178 |   # Combine and save
179 |   extended = pd.concat([original, new_rows], ignore_index=True)
180 |   extended.to_json('DATA_OUTPUT_DIR/<date_time>/extended_data.jsonl', orient='records', lines=True)
181 |   print(f'Extended dataset: {len(original)} -> {len(extended)} rows')
182 |   "
183 |   ```
184 | 
185 | ### Reporting Phase
186 | 
187 | - Count rows in original and extended files:
188 |   ```bash
189 |   # For CSV (subtract 1 for header)
190 |   ORIGINAL_COUNT=$(($(wc -l < DATA_OUTPUT_DIR/<date_time>/original_<filename>) - 1))
191 |   EXTENDED_COUNT=$(($(wc -l < DATA_OUTPUT_DIR/<date_time>/extended_data.csv) - 1))
192 |   
193 |   # For JSONL
194 |   ORIGINAL_COUNT=$(wc -l < DATA_OUTPUT_DIR/<date_time>/original_<filename>)
195 |   EXTENDED_COUNT=$(wc -l < DATA_OUTPUT_DIR/<date_time>/extended_data.jsonl)
196 |   ```
197 | 
198 | - Create analysis report `DATA_OUTPUT_DIR/<date_time>/data_analysis_report.md`:
199 |   - Original file name and format
200 |   - Sample size analyzed
201 |   - Detected schema/structure
202 |   - Field types and patterns identified
203 |   - Value distributions observed
204 |   - Generation strategy used
205 |   - Number of rows: original vs extended
206 | 
207 | - Create metadata file `DATA_OUTPUT_DIR/<date_time>/generation_metadata.json`:
208 |   ```json
209 |   {
210 |     "source_file": "path/to/original",
211 |     "generation_timestamp": "ISO-8601 timestamp",
212 |     "rows_generated": 25,
213 |     "original_row_count": X,
214 |     "extended_row_count": Y,
215 |     "file_format": "csv|jsonl",
216 |     "sample_size_analyzed": 100,
217 |     "fields_analyzed": ["field1", "field2", ...]
218 |   }
219 |   ```
220 | 
221 | - Display summary:
222 |   - Original file analyzed
223 |   - Number of rows in original
224 |   - Number of new rows generated
225 |   - Total rows in extended file
226 |   - Output files created
227 |   - Processing time
228 | 
229 | - Open the output directory: `open DATA_OUTPUT_DIR/<date_time>/`
230 | - When finished, move the `DROPPED_FILE_PATH` into `DROPPED_FILE_PATH_ARCHIVE` directory
231 | 
232 | ## Important Notes
233 | 
234 | - **CSV Format:** Must have headers in first row, data starts from row 2
235 | - **JSONL Format:** Each line is a complete JSON object, not a JSON array
236 | - **Large Files:** This approach keeps large files out of the agent's context window by:
237 |   - Only reading a sample for analysis
238 |   - Generating to separate files
239 |   - Using bash commands for appending
240 | - **Performance:** Bash append operations are fast and memory-efficient
241 | - **Data Integrity:** The extended file preserves all original data unchanged
242 | 
243 | ## Example Patterns to Recognize
244 | 
245 | **CSV Example:**
246 | ```csv
247 | id,name,email,age,department
248 | 1,John Doe,john@example.com,28,Engineering
249 | 2,Jane Smith,jane@example.com,32,Marketing
250 | ```
251 | → Generate: Sequential IDs, realistic names, email patterns, age ranges, department categories
252 | 
253 | **JSONL Example:**
254 | ```jsonl
255 | {"user_id": "USR001", "score": 85.5, "tags": ["python", "ml"], "active": true}
256 | {"user_id": "USR002", "score": 92.0, "tags": ["javascript"], "active": false}
257 | ```
258 | → Generate: USR-prefixed IDs, scores in similar range, relevant tags, boolean values
259 | 
260 | ## Special Handling
261 | 
262 | - **Look for override instructions:** Check if the dropped file contains a comment like `# generate_rows: 50` or `"generate_rows": 50` to override NUM_NEW_ROWS
263 | - **Preserve formatting:** Maintain consistent decimal places, date formats, etc.
264 | - **Handle edge cases:** Empty files, malformed data should be reported gracefully
265 | - **Memory efficiency:** Never load the full extended dataset into memory


--------------------------------------------------------------------------------
/.claude/commands/morning_debrief.md:
--------------------------------------------------------------------------------
 1 | ---
 2 | name: Morning Debrief
 3 | allowed-tools: Bash, Read, Write
 4 | description: Transcribe morning debrief audio and analyze for engineering ideas and priorities
 5 | ---
 6 | 
 7 | # Morning Debrief Analyzer
 8 | 
 9 | This prompt transcribes morning debrief audio recordings using OpenAI Whisper and analyzes the transcript to extract and organize key engineering ideas discussed. It creates a structured summary with the current date and quarter, identifies the top 3 priorities, lists all key ideas from the debrief, and generates novel extensions based on those ideas, and generates leading questions that can guide our work today with ideas for potential answers and next steps. Then it creates a transcript section with the full transcript of the debrief with every sentence as an individual item in a bulleted list. The output follows a clear hierarchical structure that makes it easy to reference during the workday. See the `Instructions` section for the detailed process. Output your results in a new markdown file with an alphanumeric + underscore name based on the original transcript file name.
10 | 
11 | ## Prerequisites
12 | 
13 | - OpenAI Whisper must be installed
14 | - If you encounter installation errors, STOP and notify the user:
15 |   ```
16 |   Whisper is not installed. Please run:
17 |   uv tool install openai-whisper
18 |   ```
19 | 
20 | ## Variables
21 | 
22 | AUDIO_FILE_PATH: [[FILE_PATH]]
23 | DEBRIEF_OUTPUT_DIR: agentic_drop_zone/morning_debrief_zone/debrief_output/<date_time>/
24 | DEBRIEF_ARCHIVE_DIR: DEBRIEF_OUTPUT_DIR/drop_zone_file_archive/
25 | 
26 | ## Instructions
27 | - First, check if whisper is available by running: `which whisper`
28 | - If whisper is not found, notify the user to install it with: `uv tool install openai-whisper`
29 | - Create output directory: `DEBRIEF_OUTPUT_DIR/<date_time>/`
30 |   - `date_time` is the current date and time in the format YYYY-MM-DD_HH-MM-SS
31 | - Transcribe the audio file using: `whisper "[[FILE_PATH]]" --model tiny --language en --output_format txt --output_dir DEBRIEF_OUTPUT_DIR/`
32 |   - The `--model tiny` is fast and suitable for English transcription
33 |   - You can use `--model base` or `--model small` for better accuracy if needed
34 |   - The transcription will generate a .txt file in the output directory
35 |   - IMPORTANT: Run this command with a 5 minute timeout. If it doesn't finish, notify the user and stop.
36 | - Read the generated transcript file (it will have the same base name as the audio file but with .txt extension)
37 | - Read the generated transcript file
38 | - Determine the current date and quarter (Q1: Jan-Mar, Q2: Apr-Jun, Q3: Jul-Sep, Q4: Oct-Dec)
39 | - Analyze the transcript to identify all engineering ideas and priorities mentioned
40 | - Extract the top 3 most important priorities from the discussion
41 | - List all key ideas concisely, focusing on actionable engineering concepts
42 | - Generate novel extensions by:
43 |   - Combining related ideas in new ways
44 |   - Identifying potential optimizations or improvements
45 |   - Suggesting complementary features or approaches
46 |   - Proposing innovative solutions based on the discussed concepts
47 |   - Extrapolate from the key ideas to add your own tasteful extensions
48 |   - Push the ideas further based on your own experience and knowledge
49 | - Structure the output with clear sections and bullet points for readability
50 | - Keep descriptions concise but informative
51 | - Focus on actionable aspects
52 | - IMPORTANT: Output your results in a new markdown file in the output directory: `DEBRIEF_OUTPUT_DIR/<date_time>/debrief_<QN>_<3 letter month>_<2 digit day>_<4 digit year>.md`
53 | - Copy the original audio file to the output directory for reference: `cp AUDIO_FILE_PATH DEBRIEF_OUTPUT_DIR/<date_time>/original_audio.<ext>`
54 | - IMPORTANT: Once you finish, open the new file with `code DEBRIEF_OUTPUT_DIR/<date_time>/debrief_<QN>_<3 letter month>_<2 digit day>_<4 digit year>.md`
55 | - Ultra Think as you work through this process.
56 | - When finished, move the original audio file to the archive: `mv AUDIO_FILE_PATH DEBRIEF_ARCHIVE_DIR/`
57 | 
58 | ## Output Structure
59 | The analysis should be formatted as follows:
60 | 1. **Title** - A descriptive title based on the debrief content
61 | 2. **Date** - Current date with quarter (e.g., "2025-01-29 (Q1 2025)")
62 | 3. **Top 3 Priorities** - Numbered list of the most important items
63 | 4. **Key Ideas** - Bulleted list of all ideas from the transcript
64 | 5. **Extensions** - Novel ideas derived from the key ideas
65 | 6. **Leading Questions** - Questions to guide today's work with potential answers
66 | 7. **Transcript** - Full transcript with each sentence as a bullet point
67 | 
68 | 


--------------------------------------------------------------------------------
/.claude/commands/prime.md:
--------------------------------------------------------------------------------
 1 | # Prime
 2 | 
 3 | Understand the files in the `Read` section, and execute the `Run` commands then `Report` your findings.
 4 | 
 5 | ## Read
 6 | 
 7 | - README.md
 8 | - sfs_agentic_drop_zone.py
 9 | - drops.yaml
10 | - .claude/commands/
11 | 
12 | ## Execute
13 | 
14 | git ls-files
15 | 
16 | ## Report
17 | 
18 | Report your understanding of this codebase in this format:
19 | 
20 | For each file, report the following:
21 | `<File Name> - <File Description>`
22 | 
23 | Then provide an overall summary of the codebase.


--------------------------------------------------------------------------------
/.env.sample:
--------------------------------------------------------------------------------
 1 | ANTHROPIC_API_KEY=
 2 | OPENAI_API_KEY=
 3 | GEMINI_API_KEY=
 4 | # Claude Code CLI path (defaults to 'claude')
 5 | # If already installed locally, try:
 6 | # export PATH="$HOME/node_modules/.bin:$PATH"
 7 | # If installed locally, set to: /path/to/node_modules/.bin/claude
 8 | CLAUDE_CODE_PATH=claude
 9 | REPLICATE_API_TOKEN=
10 | 


--------------------------------------------------------------------------------
/.gemini/settings.json.sample:
--------------------------------------------------------------------------------
 1 | {
 2 |   "mcpServers": {
 3 |     "replicate": {
 4 |       "command": "npx",
 5 |       "args": [
 6 |         "-y",
 7 |         "replicate-mcp"
 8 |       ],
 9 |       "env": {
10 |         "REPLICATE_API_TOKEN": "<REPLICATE_API_TOKEN>"
11 |       }
12 |     }
13 |   }
14 | }
15 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | adw/
 2 | *zone/
 3 | *.pyc
 4 | *.pyo
 5 | *.pyd
 6 | *.pyw
 7 | *.pyz
 8 | *.pywz
 9 | *.pyzw
10 | .env
11 | .mcp.json
12 | !sfs_agentic_drop_zone.py
13 | output/
14 | .DS_Store
15 | 
16 | **private/
17 | .gemini/settings.json
18 | .codex/settings.json


--------------------------------------------------------------------------------
/.mcp.json.sample:
--------------------------------------------------------------------------------
 1 | {
 2 |   "mcpServers": {
 3 |     "replicate": {
 4 |       "command": "npx",
 5 |       "args": ["-y", "replicate-mcp"],
 6 |       "env": {
 7 |         "REPLICATE_API_TOKEN": "<your-replicate-api-token>"
 8 |       }
 9 |     }
10 |   }
11 | }
12 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Agentic Drop Zone
  2 | > See what you can do with the Agentic Drop Zone [in this video](https://youtu.be/gyjoXC8lzIw).
  3 | 
  4 | Automated file processing system that monitors directories and triggers agents (Claude Code, Gemini CLI, Codex CLI) when files are dropped.
  5 | 
  6 | ## Features
  7 | 
  8 | - 📝 Simple single file script: `sfs_agentic_drop_zone.py`
  9 | - ⚙️ Configurable drop zones in `drops.yaml`
 10 | - 🤖 Agent agnostic implementation: Claude Code, Gemini CLI, Codex CLI (unimplemented)
 11 | - 🧩 Run multiple agents in parallel
 12 | - 🚀 Run arbitrary agentic workflows: Do 'anything' your agent can do
 13 | 
 14 | <img src="./images/arch.png" alt="System Architecture Diagram" style="max-width: 800px;">
 15 | 
 16 | ## System Architecture
 17 | 
 18 | ```mermaid
 19 | graph LR
 20 |     subgraph "Agentic Drop Zone System"
 21 |         A[File Dropped] --> B[Watchdog Detects Event]
 22 |         B --> C{Matches Pattern?}
 23 |         C -->|Yes| D[Load Prompt Template]
 24 |         C -->|No| E[Ignore]
 25 |         D --> F[Replace FILE_PATH Variable]
 26 |         F --> G{Select Agent}
 27 |         G -->|claude_code| H[Claude Code<br/>Full tool access<br/>MCP servers]
 28 |         G -->|gemini_cli| I[Gemini CLI<br/>Google AI<br/>]
 29 |         G -->|codex_cli| J[Codex CLI<br/>OpenAI<br/>unimplemented]
 30 |         H --> K[Stream Response]
 31 |         I --> K
 32 |         J --> K
 33 |         K --> L[Display in Console]
 34 |         L --> B
 35 |     end
 36 | ```
 37 | 
 38 | 
 39 | ## How It Works
 40 | 
 41 | 1. **Watch** - Monitors configured directories for file events (create/modify/delete/move)
 42 | 2. **Match** - Checks if dropped files match configured patterns (*.txt, *.json, etc.)
 43 | 3. **Process** - Executes Claude Code with custom prompts to process the files
 44 | 4. **Output** - Rich console display with streaming responses in styled panels
 45 | 
 46 | ## Quick Start
 47 | 
 48 | ```bash
 49 | # Install uv (if not already installed)
 50 | curl -LsSf https://astral.sh/uv/install.sh | sh
 51 | 
 52 | # Setup environment variables (at least Claude Code API key)
 53 | export ANTHROPIC_API_KEY="your-claude-api-key"
 54 | export CLAUDE_CODE_PATH="path-to-claude-cli" # default to claude, may need to run which claude to find the path
 55 | 
 56 | # Run with uv
 57 | uv run sfs_agentic_drop_zone.py
 58 | 
 59 | # Drag and drop (copy to reuse) files from example_input_files folder into the drop zone directories
 60 | cp example_input_files/echo.txt agentic_drop_zone/echo_zone/
 61 | ```
 62 | 
 63 | ## MCP Support
 64 | 
 65 | - Claude Code supports MCP servers, run `cp .mcp.json.sample .mcp.json` and edit the file with your API keys
 66 | - Gemini CLI supports MCP servers, run `cp .gemini/settings.json.sample .gemini/settings.json` and edit the file with your API keys
 67 | - Codex CLI does not support MCP servers without modifying root level `~/.codex/config.toml` (untested)
 68 | 
 69 | ## ⚠️ Dangerous Agent Execution
 70 | 
 71 | **IMPORTANT:** Agents are given complete control over your system with dangerous execution capabilities. Agent permissions are as follows:
 72 | 
 73 | - Claude Code runs with `bypassPermissions` mode, which allows all tools without prompting
 74 | - Gemini CLI runs with `yolo` flag with the `--sandbox` flag, which auto-approves all actions but prevents moving outside of the sandbox directory
 75 | - Codex CLI (not implemented)
 76 | 
 77 | **By using this system, you acknowledge the risks and take full responsibility for any actions performed by the agents.**
 78 | 
 79 | ## Configuration (drops.yaml)
 80 | 
 81 | ```yaml
 82 | drop_zones:
 83 |   - name: "Image Generation Drop Zone"
 84 |     file_patterns: ["*.txt", "*.md"]           # File types to watch
 85 |     reusable_prompt: ".claude/commands/create_image.md"  # Prompt template
 86 |     zone_dirs: ["generate_images_zone"]        # Directories to monitor
 87 |     events: ["created"]                        # Trigger on file creation
 88 |     agent: "claude_code"                       # Agent type
 89 |     model: "sonnet"                           # Claude model
 90 |     mcp_server_file: ".mcp.json"              # MCP tools config (optional)
 91 |     create_zone_dir_if_not_exists: true       # Auto-create directories
 92 | ```
 93 | 
 94 | ## Agents
 95 | 
 96 | The system supports multiple AI agents with different capabilities:
 97 | 
 98 | ### Claude Code (Most Capable)
 99 | - 
100 | - **Status**: ✅ Fully implemented
101 | - **SDK**: Native Python, Typescript, and CLI SDK with streaming support
102 | - **Output**: Clean, formatted panels with real-time streaming
103 | - **Models**: `sonnet`, `opus`, `haiku`
104 | - **MCP Support**: Full MCP tool integration
105 | - **Best For**: Complex tasks requiring tool use, SOTA performance
106 | - [Documentation](https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-overview)
107 | 
108 | ### Gemini CLI
109 | - **Status**: 🟡 Implemented with subprocess streaming
110 | - **SDK**: No SDK - uses CLI via subprocess
111 | - **Output**: Line-by-line streaming in panels (due to CLI limitations)
112 | - **Models**: `gemini-2.5-pro` (default), `gemini-2.5-flash`
113 | - **Flags**: `--yolo` (auto-approve), `--sandbox` (sandboxing)
114 | - **Best For**: Quick tasks, alternative models outside of Anthropic models
115 | - [Documentation](https://github.com/google-gemini/gemini-cli)
116 | 
117 | ### Codex CLI
118 | - **Status**: ❌ Not yet implemented
119 | - **SDK**: Would use CLI via subprocess
120 | - **Output**: TBD
121 | - **Models**: `gpt-5`
122 | - **Best For**: Future implementation (Up for a challenge?)
123 | - [Documentation](https://github.com/openai/codex)
124 | 
125 | ### Configuration Example
126 | See `drops.yaml` for agent setup:
127 | 
128 | ```yaml
129 | - name: "Claude Zone"
130 |   agent: "claude_code"
131 |   model: "sonnet"
132 |   mcp_server_file: ".mcp.json" # specify this or it won't use MCP tools
133 | 
134 | - name: "Gemini Zone"  
135 |   agent: "gemini_cli"
136 |   model: "gemini-2.5-pro"
137 | ```
138 | 
139 | ## Claude Code SDK Integration
140 | 
141 | Uses `ClaudeSDKClient` with streaming responses:
142 | 
143 | ```python
144 | async with ClaudeSDKClient(options=ClaudeCodeOptions(
145 |     permission_mode="bypassPermissions",
146 |     model="sonnet",
147 |     mcp_servers=".mcp.json"  # Optional MCP tools
148 | )) as client:
149 |     await client.query(prompt)
150 |     async for message in client.receive_response():
151 |         # Stream responses in Rich panels
152 | ```
153 | 
154 | ## Agentic Workflows
155 | 
156 | The system comes with several pre-configured workflows. Each requires specific setup and environment variables:
157 | 
158 | ### 🎨 Image Generation Drop Zone
159 | **Directory:** `generate_images_zone/`  
160 | **File Types:** `*.txt`, `*.md`  
161 | **Purpose:** Generate images from text prompts using Replicate AI models
162 | 
163 | **Requirements:**
164 | - Environment variable: `REPLICATE_API_TOKEN` (required)
165 | - MCP server configuration: `.mcp.json` (copy from `.mcp.json.sample`)
166 | - Claude Code with Replicate MCP tools
167 | 
168 | **Usage:** Drop a text file containing image prompts. The system will:
169 | - Read each prompt from the file
170 | - Generate images using Replicate's models (default: google/nano-banana)
171 | - Save images with descriptive names and metadata
172 | - Archive the original prompt file
173 | - Open the output directory automatically
174 | 
175 | ### 🖼️ Image Edit Drop Zone  
176 | **Directory:** `edit_images_zone/`  
177 | **File Types:** `*.txt`, `*.md`, `*.json`  
178 | **Purpose:** Edit existing images using AI models
179 | 
180 | **Requirements:**
181 | - Environment variable: `REPLICATE_API_TOKEN` (required)
182 | - MCP server configuration: `.mcp.json`
183 | - Image URLs or paths in the dropped files
184 | 
185 | **Usage:** Drop files containing image paths/URLs and editing instructions.
186 | 
187 | ### 📊 Training Data Generation Zone
188 | **Directory:** `training_data_zone/`  
189 | **File Types:** `*.csv`, `*.jsonl` (JSON Lines format)  
190 | **Purpose:** Analyze data patterns and generate synthetic training data
191 | 
192 | **Requirements:**
193 | - No external API keys required
194 | - Uses Claude Code's built-in analysis capabilities
195 | 
196 | **Usage:** Drop data files to:
197 | - Analyze a sample (100 rows) to understand patterns
198 | - Generate 25 additional rows (configurable)
199 | - Append new data using efficient bash commands
200 | - Create extended datasets without loading into memory
201 | - Preserve all original data unchanged
202 | 
203 | **Optimization:** Uses bash append operations to handle large files efficiently
204 | 
205 | ### 🎙️ Morning Debrief Zone
206 | **Directory:** `morning_debrief_zone/`  
207 | **File Types:** `*.mp3`, `*.wav`, `*.m4a`, `*.flac`, `*.ogg`, `*.aac`, `*.mp4`  
208 | **Purpose:** Transcribe morning debrief audio recordings and analyze content for engineering ideas and priorities
209 | 
210 | **Requirements:**
211 | - OpenAI Whisper installed: `uv tool install openai-whisper`
212 | - No API keys required (runs locally)
213 | 
214 | **Usage:** Drop audio files to:
215 | - Transcribe using Whisper's tiny model (fast, English)
216 | - Extract top 3 priorities from discussions
217 | - Identify key engineering ideas
218 | - Generate novel extensions and leading questions
219 | - Create structured debrief documents with:
220 |   - Date and quarter tracking
221 |   - Formatted transcript with bulleted sentences
222 |   - Direct commands extracted from transcript
223 | - Archive original audio files after processing
224 | 
225 | **Output:** Generates markdown debrief files with comprehensive analysis in `morning_debrief_zone/debrief_output/<date_time>/`
226 | 
227 | ## Improvements
228 | 
229 | - The `zone_dirs` should be a single directory (`zone_dir`), and this should be passed into each prompt as a prompt variable (## Variables) and used to create the output directory. Right now it's static in the respective prompts.
230 | - Get Codex CLI working (they don't have support for local .codex/config.toml at the time of writing)
231 | - Improve `Gemini CLI` streaming output to be more readable and less line by line based. They don't have an SDK, so we're using the CLI.
232 | 
233 | ## Master AI Coding 
234 | 
235 | Learn to code with AI with foundational [Principles of AI Coding](https://agenticengineer.com/principled-ai-coding?y=adrzone)
236 | 
237 | Follow the [IndyDevDan youtube channel](https://www.youtube.com/@indydevdan) for more Agentic Coding tips and tricks.


--------------------------------------------------------------------------------
/ai_docs/ai_docs.md:
--------------------------------------------------------------------------------
 1 | # Agentic Drop Zone Documentation
 2 | 
 3 | ## Reference Links
 4 | - https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-python
 5 | - https://github.com/gorakhargosh/watchdog?tab=readme-ov-file#example-api-usage
 6 | - https://pythonhosted.org/watchdog/api.html
 7 | - https://docs.astral.sh/uv/guides/scripts/#next-steps
 8 | - https://replicate.com/docs/reference/mcp
 9 | - https://docs.astral.sh/uv/guides/scripts/#running-a-script-with-dependencies
10 | - https://docs.astral.sh/uv
11 | - https://github.com/openai/whisper
12 | - https://github.com/openai/openai-python
13 | 
14 | ## Recent Updates
15 | 
16 | ### Rich Console Output
17 | Integrated Rich library for beautiful console output:
18 | - Claude Code responses displayed in individual styled panels as content streams in
19 | - Each response block appears in its own panel with title and subtitle
20 | - Color-coded file system events (create, modify, delete, move)
21 | - Structured logging with icons and color formatting
22 | - Clean, segmented display of streaming responses
23 | 
24 | ### MCP Server Integration Support
25 | Added support for Model Context Protocol (MCP) servers through the `mcp_server_file` field in drop zone configuration. This allows integration with external tools and services. The file path is passed directly to ClaudeCodeOptions, which handles loading the configuration.
26 | 
27 | ### PromptArgs Type System
28 | Introduced a structured `PromptArgs` Pydantic model to manage prompt-related arguments cleanly:
29 | - `reusable_prompt`: Path to the reusable prompt file
30 | - `file_path`: Path to the file being processed  
31 | - `model`: Optional model specification
32 | - `mcp_server_file`: Optional path to MCP server configuration file
33 | 
34 | ### Configuration Schema Updates
35 | The `DropZone` model now includes:
36 | - `mcp_server_file`: Optional path to MCP server configuration file (JSON or YAML)
37 | 
38 | Example configuration:
39 | ```yaml
40 | drop_zones:
41 |   - name: "Advanced Zone"
42 |     file_patterns: ["*.py"]
43 |     reusable_prompt: ".claude/commands/analyze.md"
44 |     zone_dirs: ["src/"]
45 |     events: ["created", "modified"]
46 |     agent: "claude_code"
47 |     model: "sonnet"
48 |     mcp_server_file: ".mcp/servers.json"  # New field for MCP integration
49 | ```
50 | 
51 | ### MCP Server File Format
52 | MCP server files can be in JSON or YAML format. The ClaudeCodeOptions class handles loading these files automatically:
53 | 
54 | ```json
55 | {
56 |   "database": {
57 |     "command": "npx",
58 |     "args": ["-y", "@modelcontextprotocol/server-postgres"],
59 |     "env": {"DATABASE_URL": "postgresql://localhost:5432/mydb"}
60 |   }
61 | }
62 | ```
63 | 
64 | ### Implementation Notes
65 | - The `mcp_server_file` path is passed directly to `ClaudeCodeOptions` as the `mcp_servers` parameter
66 | - ClaudeCodeOptions natively supports file paths (`dict | str | Path`) for MCP configurations
67 | - No manual file parsing is required - the SDK handles JSON/YAML loading internally
68 | 
69 | ### Visual Output Features
70 | The application now uses Rich console for enhanced visual feedback:
71 | 
72 | #### File System Events
73 | - ✨ Green for file creation
74 | - 📝 Yellow for file modification  
75 | - 🗑️ Red for file deletion
76 | - 📦 Blue for file moves
77 | 
78 | #### Claude Code Response Panel
79 | - Displays responses in a styled panel with cyan border
80 | - Shows "🤖 Claude Code" as the title
81 | - Includes the processing file name as subtitle
82 | - Live streaming updates as the response arrives
83 | - Clean padding and formatting for readability
84 | 
85 | #### Status Messages
86 | - 🚀 Startup banner with application name
87 | - ✅ Green confirmation for started monitors
88 | - 🎯 Cyan summary of active observers
89 | - 🛑 Yellow stop notifications
90 | - ⚡ Keyboard interrupt handling


--------------------------------------------------------------------------------
/ai_docs/astral-uv-single-file-scripts.md:
--------------------------------------------------------------------------------
  1 | Guides
  2 | Running scripts
  3 | A Python script is a file intended for standalone execution, e.g., with python <script>.py. Using uv to execute scripts ensures that script dependencies are managed without manually managing environments.
  4 | 
  5 | Note
  6 | 
  7 | If you are not familiar with Python environments: every Python installation has an environment that packages can be installed in. Typically, creating virtual environments is recommended to isolate packages required by each script. uv automatically manages virtual environments for you and prefers a declarative approach to dependencies.
  8 | 
  9 | Running a script without dependencies
 10 | If your script has no dependencies, you can execute it with uv run:
 11 | 
 12 | example.py
 13 | 
 14 | print("Hello world")
 15 | 
 16 | uv run example.py
 17 | 
 18 | Similarly, if your script depends on a module in the standard library, there's nothing more to do:
 19 | 
 20 | example.py
 21 | 
 22 | import os
 23 | 
 24 | print(os.path.expanduser("~"))
 25 | 
 26 | uv run example.py
 27 | 
 28 | Arguments may be provided to the script:
 29 | 
 30 | example.py
 31 | 
 32 | import sys
 33 | 
 34 | print(" ".join(sys.argv[1:]))
 35 | 
 36 | uv run example.py test
 37 | 
 38 | 
 39 | uv run example.py hello world!
 40 | 
 41 | Additionally, your script can be read directly from stdin:
 42 | 
 43 | 
 44 | echo 'print("hello world!")' | uv run -
 45 | Or, if your shell supports here-documents:
 46 | 
 47 | 
 48 | uv run - <<EOF
 49 | print("hello world!")
 50 | EOF
 51 | Note that if you use uv run in a project, i.e., a directory with a pyproject.toml, it will install the current project before running the script. If your script does not depend on the project, use the --no-project flag to skip this:
 52 | 
 53 | 
 54 | # Note: the `--no-project` flag must be provided _before_ the script name.
 55 | uv run --no-project example.py
 56 | See the projects guide for more details on working in projects.
 57 | 
 58 | Running a script with dependencies
 59 | When your script requires other packages, they must be installed into the environment that the script runs in. uv prefers to create these environments on-demand instead of using a long-lived virtual environment with manually managed dependencies. This requires explicit declaration of dependencies that are required for the script. Generally, it's recommended to use a project or inline metadata to declare dependencies, but uv supports requesting dependencies per invocation as well.
 60 | 
 61 | For example, the following script requires rich.
 62 | 
 63 | example.py
 64 | 
 65 | import time
 66 | from rich.progress import track
 67 | 
 68 | for i in track(range(20), description="For example:"):
 69 |     time.sleep(0.05)
 70 | If executed without specifying a dependency, this script will fail:
 71 | 
 72 | 
 73 | uv run --no-project example.py
 74 | 
 75 | 
 76 | 
 77 | 
 78 | Request the dependency using the --with option:
 79 | 
 80 | 
 81 | uv run --with rich example.py
 82 | 
 83 | Constraints can be added to the requested dependency if specific versions are needed:
 84 | 
 85 | 
 86 | uv run --with 'rich>12,<13' example.py
 87 | Multiple dependencies can be requested by repeating with --with option.
 88 | 
 89 | Note that if uv run is used in a project, these dependencies will be included in addition to the project's dependencies. To opt-out of this behavior, use the --no-project flag.
 90 | 
 91 | Creating a Python script
 92 | Python recently added a standard format for inline script metadata. It allows for selecting Python versions and defining dependencies. Use uv init --script to initialize scripts with the inline metadata:
 93 | 
 94 | 
 95 | uv init --script example.py --python 3.12
 96 | Declaring script dependencies
 97 | The inline metadata format allows the dependencies for a script to be declared in the script itself.
 98 | 
 99 | uv supports adding and updating inline script metadata for you. Use uv add --script to declare the dependencies for the script:
100 | 
101 | 
102 | uv add --script example.py 'requests<3' 'rich'
103 | This will add a script section at the top of the script declaring the dependencies using TOML:
104 | 
105 | example.py
106 | 
107 | # /// script
108 | # dependencies = [
109 | #   "requests<3",
110 | #   "rich",
111 | # ]
112 | # ///
113 | 
114 | import requests
115 | from rich.pretty import pprint
116 | 
117 | resp = requests.get("https://peps.python.org/api/peps.json")
118 | data = resp.json()
119 | pprint([(k, v["title"]) for k, v in data.items()][:10])
120 | uv will automatically create an environment with the dependencies necessary to run the script, e.g.:
121 | 
122 | 
123 | uv run example.py
124 | 
125 | 
126 | 
127 | 
128 | 
129 | 
130 | 
131 | 
132 | 
133 | 
134 | 
135 | 
136 | Important
137 | 
138 | When using inline script metadata, even if uv run is used in a project, the project's dependencies will be ignored. The --no-project flag is not required.
139 | 
140 | uv also respects Python version requirements:
141 | 
142 | example.py
143 | 
144 | # /// script
145 | # requires-python = ">=3.12"
146 | # dependencies = []
147 | # ///
148 | 
149 | # Use some syntax added in Python 3.12
150 | type Point = tuple[float, float]
151 | print(Point)
152 | Note
153 | 
154 | The dependencies field must be provided even if empty.
155 | 
156 | uv run will search for and use the required Python version. The Python version will download if it is not installed — see the documentation on Python versions for more details.
157 | 
158 | Using a shebang to create an executable file
159 | A shebang can be added to make a script executable without using uv run — this makes it easy to run scripts that are on your PATH or in the current folder.
160 | 
161 | For example, create a file called greet with the following contents
162 | 
163 | greet
164 | 
165 | #!/usr/bin/env -S uv run --script
166 | 
167 | print("Hello, world!")
168 | Ensure that your script is executable, e.g., with chmod +x greet, then run the script:
169 | 
170 | 
171 | ./greet
172 | 
173 | Declaration of dependencies is also supported in this context, for example:
174 | 
175 | example
176 | 
177 | #!/usr/bin/env -S uv run --script
178 | #
179 | # /// script
180 | # requires-python = ">=3.12"
181 | # dependencies = ["httpx"]
182 | # ///
183 | 
184 | import httpx
185 | 
186 | print(httpx.get("https://example.com"))
187 | Using alternative package indexes
188 | If you wish to use an alternative package index to resolve dependencies, you can provide the index with the --index option:
189 | 
190 | 
191 | uv add --index "https://example.com/simple" --script example.py 'requests<3' 'rich'
192 | This will include the package data in the inline metadata:
193 | 
194 | 
195 | # [[tool.uv.index]]
196 | # url = "https://example.com/simple"
197 | If you require authentication to access the package index, then please refer to the package index documentation.
198 | 
199 | Locking dependencies
200 | uv supports locking dependencies for PEP 723 scripts using the uv.lock file format. Unlike with projects, scripts must be explicitly locked using uv lock:
201 | 
202 | 
203 | uv lock --script example.py
204 | Running uv lock --script will create a .lock file adjacent to the script (e.g., example.py.lock).
205 | 
206 | Once locked, subsequent operations like uv run --script, uv add --script, uv export --script, and uv tree --script will reuse the locked dependencies, updating the lockfile if necessary.
207 | 
208 | If no such lockfile is present, commands like uv export --script will still function as expected, but will not create a lockfile.
209 | 
210 | Improving reproducibility
211 | In addition to locking dependencies, uv supports an exclude-newer field in the tool.uv section of inline script metadata to limit uv to only considering distributions released before a specific date. This is useful for improving the reproducibility of your script when run at a later point in time.
212 | 
213 | The date must be specified as an RFC 3339 timestamp (e.g., 2006-12-02T02:07:43Z).
214 | 
215 | example.py
216 | 
217 | # /// script
218 | # dependencies = [
219 | #   "requests",
220 | # ]
221 | # [tool.uv]
222 | # exclude-newer = "2023-10-16T00:00:00Z"
223 | # ///
224 | 
225 | import requests
226 | 
227 | print(requests.__version__)
228 | Using different Python versions
229 | uv allows arbitrary Python versions to be requested on each script invocation, for example:
230 | 
231 | example.py
232 | 
233 | import sys
234 | 
235 | print(".".join(map(str, sys.version_info[:3])))
236 | 
237 | # Use the default Python version, may differ on your machine
238 | uv run example.py
239 | 
240 | 
241 | # Use a specific Python version
242 | uv run --python 3.10 example.py
243 | 
244 | See the Python version request documentation for more details on requesting Python versions.
245 | 
246 | Using GUI scripts
247 | On Windows uv will run your script ending with .pyw extension using pythonw:
248 | 
249 | example.pyw
250 | 
251 | from tkinter import Tk, ttk
252 | 
253 | root = Tk()
254 | root.title("uv")
255 | frm = ttk.Frame(root, padding=10)
256 | frm.grid()
257 | ttk.Label(frm, text="Hello World").grid(column=0, row=0)
258 | root.mainloop()
259 | 
260 | 
261 | Run Result
262 | 
263 | Similarly, it works with dependencies as well:
264 | 
265 | example_pyqt.pyw
266 | 
267 | import sys
268 | from PyQt5.QtWidgets import QApplication, QWidget, QLabel, QGridLayout
269 | 
270 | app = QApplication(sys.argv)
271 | widget = QWidget()
272 | grid = QGridLayout()
273 | 
274 | text_label = QLabel()
275 | text_label.setText("Hello World!")
276 | grid.addWidget(text_label)
277 | 
278 | widget.setLayout(grid)
279 | widget.setGeometry(100, 100, 200, 50)
280 | widget.setWindowTitle("uv")
281 | widget.show()
282 | sys.exit(app.exec_())
283 | 
284 | 
285 | Run Result
286 | 
287 | Next steps
288 | To learn more about uv run, see the command reference.
289 | 
290 | Or, read on to learn how to run and install tools with uv.


--------------------------------------------------------------------------------
/ai_docs/claude-code-python-sdk.md:
--------------------------------------------------------------------------------
  1 | # Python
  2 | 
  3 | > Build custom AI agents with the Claude Code Python SDK
  4 | 
  5 | ## Prerequisites
  6 | 
  7 | * Python 3.10+
  8 | * `claude-code-sdk` from PyPI
  9 | * Node.js 18+
 10 | * `@anthropic-ai/claude-code` from NPM
 11 | 
 12 | <Note>
 13 |   To view the Python SDK source code, see the [`claude-code-sdk`](https://github.com/anthropics/claude-code-sdk-python) repo.
 14 | </Note>
 15 | 
 16 | <Tip>
 17 |   For interactive development, use [IPython](https://ipython.org/): `pip install ipython`
 18 | </Tip>
 19 | 
 20 | ## Installation
 21 | 
 22 | Install `claude-code-sdk` from PyPI and `@anthropic-ai/claude-code` from NPM:
 23 | 
 24 | ```bash
 25 | pip install claude-code-sdk
 26 | npm install -g @anthropic-ai/claude-code  # Required dependency
 27 | ```
 28 | 
 29 | (Optional) Install IPython for interactive development:
 30 | 
 31 | ```bash
 32 | pip install ipython
 33 | ```
 34 | 
 35 | ## Quick start
 36 | 
 37 | Create your first agent:
 38 | 
 39 | ```python
 40 | # legal-agent.py
 41 | import asyncio
 42 | from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions
 43 | 
 44 | async def main():
 45 |     async with ClaudeSDKClient(
 46 |         options=ClaudeCodeOptions(
 47 |             system_prompt="You are a legal assistant. Identify risks and suggest improvements.",
 48 |             max_turns=2
 49 |         )
 50 |     ) as client:
 51 |         # Send the query
 52 |         await client.query(
 53 |             "Review this contract clause for potential issues: 'The party agrees to unlimited liability...'"
 54 |         )
 55 | 
 56 |         # Stream the response
 57 |         async for message in client.receive_response():
 58 |             if hasattr(message, 'content'):
 59 |                 # Print streaming content as it arrives
 60 |                 for block in message.content:
 61 |                     if hasattr(block, 'text'):
 62 |                         print(block.text, end='', flush=True)
 63 | 
 64 | if __name__ == "__main__":
 65 |     asyncio.run(main())
 66 | ```
 67 | 
 68 | Save the code above as `legal-agent.py`, then run:
 69 | 
 70 | ```bash
 71 | python legal-agent.py
 72 | ```
 73 | 
 74 | For [IPython](https://ipython.org/)/Jupyter notebooks, you can run the code directly in a cell:
 75 | 
 76 | ```python
 77 | await main()
 78 | ```
 79 | 
 80 | <Note>
 81 |   The Python examples on this page use `asyncio`, but you can also use `anyio`.
 82 | </Note>
 83 | 
 84 | ## Basic usage
 85 | 
 86 | The Python SDK provides two primary interfaces:
 87 | 
 88 | ### 1. The `ClaudeSDKClient` class (recommended)
 89 | 
 90 | Best for streaming responses, multi-turn conversations, and interactive applications:
 91 | 
 92 | ```python
 93 | import asyncio
 94 | from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions
 95 | 
 96 | async def main():
 97 |     async with ClaudeSDKClient(
 98 |         options=ClaudeCodeOptions(
 99 |             system_prompt="You are a performance engineer",
100 |             allowed_tools=["Bash", "Read", "WebSearch"],
101 |             max_turns=5
102 |         )
103 |     ) as client:
104 |         await client.query("Analyze system performance")
105 | 
106 |         # Stream responses
107 |         async for message in client.receive_response():
108 |             if hasattr(message, 'content'):
109 |                 for block in message.content:
110 |                     if hasattr(block, 'text'):
111 |                         print(block.text, end='', flush=True)
112 | 
113 | # Run as script
114 | asyncio.run(main())
115 | 
116 | # Or in IPython/Jupyter: await main()
117 | ```
118 | 
119 | ### 2. The `query` function
120 | 
121 | For simple, one-shot queries:
122 | 
123 | ```python
124 | from claude_code_sdk import query, ClaudeCodeOptions
125 | 
126 | async for message in query(
127 |     prompt="Analyze system performance",
128 |     options=ClaudeCodeOptions(system_prompt="You are a performance engineer")
129 | ):
130 |     if type(message).__name__ == "ResultMessage":
131 |         print(message.result)
132 | ```
133 | 
134 | ## Configuration options
135 | 
136 | The Python SDK accepts all arguments supported by the [command line](/en/docs/claude-code/cli-reference) through the `ClaudeCodeOptions` class.
137 | 
138 | ### ClaudeCodeOptions parameters
139 | 
140 | ```python
141 | from claude_code_sdk import ClaudeCodeOptions
142 | 
143 | options = ClaudeCodeOptions(
144 |     # Core configuration
145 |     system_prompt="You are a helpful assistant",
146 |     append_system_prompt="Additional system instructions",
147 |     max_turns=5,
148 |     model="claude-3-5-sonnet-20241022",
149 |     max_thinking_tokens=8000,
150 |     
151 |     # Tool management
152 |     allowed_tools=["Bash", "Read", "Write"],
153 |     disallowed_tools=["WebSearch"],
154 |     
155 |     # Session management
156 |     continue_conversation=False,
157 |     resume="session-uuid",
158 |     
159 |     # Environment
160 |     cwd="/path/to/working/directory",
161 |     add_dirs=["/additional/context/dir"],
162 |     settings="/path/to/settings.json",
163 |     
164 |     # Permissions
165 |     permission_mode="acceptEdits",  # "default", "acceptEdits", "plan", "bypassPermissions"
166 |     permission_prompt_tool_name="mcp__approval_tool",
167 |     
168 |     # MCP integration
169 |     mcp_servers={
170 |         "my_server": {
171 |             "command": "npx",
172 |             "args": ["-y", "@modelcontextprotocol/server-example"],
173 |             "env": {"API_KEY": "your-key"}
174 |         }
175 |     },
176 |     
177 |     # Advanced
178 |     extra_args={"--verbose": None, "--custom-flag": "value"}
179 | )
180 | ```
181 | 
182 | #### Parameter details
183 | 
184 | * **`system_prompt`**: `str | None` - Custom system prompt defining the agent's role
185 | * **`append_system_prompt`**: `str | None` - Additional text appended to system prompt
186 | * **`max_turns`**: `int | None` - Maximum conversation turns (unlimited if None)
187 | * **`model`**: `str | None` - Specific Claude model to use
188 | * **`max_thinking_tokens`**: `int` - Maximum tokens for Claude's thinking process (default: 8000)
189 | * **`allowed_tools`**: `list[str]` - Tools specifically allowed for use
190 | * **`disallowed_tools`**: `list[str]` - Tools that should not be used
191 | * **`continue_conversation`**: `bool` - Continue most recent conversation (default: False)
192 | * **`resume`**: `str | None` - Session UUID to resume specific conversation
193 | * **`cwd`**: `str | Path | None` - Working directory for the session
194 | * **`add_dirs`**: `list[str | Path]` - Additional directories to include in context
195 | * **`settings`**: `str | None` - Path to settings file or settings JSON string
196 | * **`permission_mode`**: `str | None` - Permission handling mode
197 | * **`permission_prompt_tool_name`**: `str | None` - Custom permission prompt tool name
198 | * **`mcp_servers`**: `dict | str | Path` - MCP server configurations
199 | * **`extra_args`**: `dict[str, str | None]` - Pass arbitrary CLI flags to underlying Claude Code CLI
200 | 
201 | #### Permission modes
202 | 
203 | * **`"default"`**: CLI prompts for dangerous tools (default behavior)
204 | * **`"acceptEdits"`**: Automatically accept file edits without prompting
205 | * **`"plan"`**: Plan Mode - analyze without making changes
206 | * **`"bypassPermissions"`**: Allow all tools without prompting (use with caution)
207 | 
208 | ### Advanced configuration example
209 | 
210 | ```python
211 | import asyncio
212 | from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions
213 | 
214 | async def advanced_agent():
215 |     """Example showcasing advanced configuration options"""
216 |     
217 |     async with ClaudeSDKClient(
218 |         options=ClaudeCodeOptions(
219 |             # Custom working directory and additional context
220 |             cwd="/project/root",
221 |             add_dirs=["/shared/libs", "/common/utils"],
222 |             
223 |             # Model and thinking configuration
224 |             model="claude-3-5-sonnet-20241022",
225 |             max_thinking_tokens=12000,
226 |             
227 |             # Advanced tool control
228 |             allowed_tools=["Read", "Write", "Bash", "Grep"],
229 |             disallowed_tools=["WebSearch", "Bash(rm*)"],
230 |             
231 |             # Custom settings and CLI args
232 |             settings='{"editor": "vim", "theme": "dark"}',
233 |             extra_args={
234 |                 "--verbose": None,
235 |                 "--timeout": "300"
236 |             }
237 |         )
238 |     ) as client:
239 |         await client.query("Analyze the codebase structure")
240 |         
241 |         async for message in client.receive_response():
242 |             if hasattr(message, 'content'):
243 |                 for block in message.content:
244 |                     if hasattr(block, 'text'):
245 |                         print(block.text, end='', flush=True)
246 | 
247 | asyncio.run(advanced_agent())
248 | ```
249 | 
250 | ## Structured messages and image inputs
251 | 
252 | The SDK supports passing structured messages and image inputs:
253 | 
254 | ```python
255 | from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions
256 | 
257 | async with ClaudeSDKClient() as client:
258 |     # Text message
259 |     await client.query("Analyze this code for security issues")
260 | 
261 |     # Message with image reference (image will be read by Claude's Read tool)
262 |     await client.query("Explain what's shown in screenshot.png")
263 | 
264 |     # Multiple messages in sequence
265 |     messages = [
266 |         "First, analyze the architecture diagram in diagram.png",
267 |         "Now suggest improvements based on the diagram",
268 |         "Finally, generate implementation code"
269 |     ]
270 | 
271 |     for msg in messages:
272 |         await client.query(msg)
273 |         async for response in client.receive_response():
274 |             # Process each response
275 |             pass
276 | 
277 | # The SDK handles image files through Claude's built-in Read tool
278 | # Supported formats: PNG, JPG, PDF, and other common formats
279 | ```
280 | 
281 | ## Multi-turn conversations
282 | 
283 | ### Method 1: Using ClaudeSDKClient for persistent conversations
284 | 
285 | ```python
286 | import asyncio
287 | from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions, query
288 | 
289 | # Method 1: Using ClaudeSDKClient for persistent conversations
290 | async def multi_turn_conversation():
291 |     async with ClaudeSDKClient() as client:
292 |         # First query
293 |         await client.query("Let's refactor the payment module")
294 |         async for msg in client.receive_response():
295 |             # Process first response
296 |             pass
297 | 
298 |         # Continue in same session
299 |         await client.query("Now add comprehensive error handling")
300 |         async for msg in client.receive_response():
301 |             # Process continuation
302 |             pass
303 | 
304 |         # The conversation context is maintained throughout
305 | 
306 | # Method 2: Using query function with session management
307 | async def resume_session():
308 |     # Continue most recent conversation
309 |     async for message in query(
310 |         prompt="Now refactor this for better performance",
311 |         options=ClaudeCodeOptions(continue_conversation=True)
312 |     ):
313 |         if type(message).__name__ == "ResultMessage":
314 |             print(message.result)
315 | 
316 |     # Resume specific session
317 |     async for message in query(
318 |         prompt="Update the tests",
319 |         options=ClaudeCodeOptions(
320 |             resume="550e8400-e29b-41d4-a716-446655440000",
321 |             max_turns=3
322 |         )
323 |     ):
324 |         if type(message).__name__ == "ResultMessage":
325 |             print(message.result)
326 | 
327 | # Run the examples
328 | asyncio.run(multi_turn_conversation())
329 | ```
330 | 
331 | ## Custom system prompts
332 | 
333 | System prompts define your agent's role, expertise, and behavior:
334 | 
335 | ```python
336 | import asyncio
337 | from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions
338 | 
339 | async def specialized_agents():
340 |     # SRE incident response agent with streaming
341 |     async with ClaudeSDKClient(
342 |         options=ClaudeCodeOptions(
343 |             system_prompt="You are an SRE expert. Diagnose issues systematically and provide actionable solutions.",
344 |             max_turns=3
345 |         )
346 |     ) as sre_agent:
347 |         await sre_agent.query("API is down, investigate")
348 | 
349 |         # Stream the diagnostic process
350 |         async for message in sre_agent.receive_response():
351 |             if hasattr(message, 'content'):
352 |                 for block in message.content:
353 |                     if hasattr(block, 'text'):
354 |                         print(block.text, end='', flush=True)
355 | 
356 |     # Legal review agent with custom prompt
357 |     async with ClaudeSDKClient(
358 |         options=ClaudeCodeOptions(
359 |             append_system_prompt="Always include comprehensive error handling and unit tests.",
360 |             max_turns=2
361 |         )
362 |     ) as dev_agent:
363 |         await dev_agent.query("Refactor this function")
364 | 
365 |         # Collect full response
366 |         full_response = []
367 |         async for message in dev_agent.receive_response():
368 |             if type(message).__name__ == "ResultMessage":
369 |                 print(message.result)
370 | 
371 | asyncio.run(specialized_agents())
372 | ```
373 | 
374 | ## Custom tools via MCP
375 | 
376 | The Model Context Protocol (MCP) lets you give your agents custom tools and capabilities:
377 | 
378 | ```python
379 | import asyncio
380 | from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions
381 | 
382 | async def mcp_enabled_agent():
383 |     # Legal agent with document access and streaming
384 |     # Note: Configure your MCP servers as needed
385 |     mcp_servers = {
386 |         # Example configuration - uncomment and configure as needed:
387 |         # "docusign": {
388 |         #     "command": "npx",
389 |         #     "args": ["-y", "@modelcontextprotocol/server-docusign"],
390 |         #     "env": {"API_KEY": "your-key"}
391 |         # }
392 |     }
393 | 
394 |     async with ClaudeSDKClient(
395 |         options=ClaudeCodeOptions(
396 |             mcp_servers=mcp_servers,
397 |             allowed_tools=["mcp__docusign", "mcp__compliance_db"],
398 |             system_prompt="You are a corporate lawyer specializing in contract review.",
399 |             max_turns=4
400 |         )
401 |     ) as client:
402 |         await client.query("Review this contract for compliance risks")
403 | 
404 |         # Monitor tool usage and responses
405 |         async for message in client.receive_response():
406 |             if hasattr(message, 'content'):
407 |                 for block in message.content:
408 |                     if hasattr(block, 'type'):
409 |                         if block.type == 'tool_use':
410 |                             print(f"\n[Using tool: {block.name}]\n")
411 |                         elif hasattr(block, 'text'):
412 |                             print(block.text, end='', flush=True)
413 |                     elif hasattr(block, 'text'):
414 |                         print(block.text, end='', flush=True)
415 | 
416 |             if type(message).__name__ == "ResultMessage":
417 |                 print(f"\n\nReview complete. Total cost: ${message.total_cost_usd:.4f}")
418 | 
419 | asyncio.run(mcp_enabled_agent())
420 | ```
421 | 
422 | ## Custom permission prompt tool
423 | 
424 | Implement custom permission handling for tool calls:
425 | 
426 | ```python
427 | import asyncio
428 | from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions
429 | 
430 | async def use_permission_prompt():
431 |     """Example using custom permission prompt tool"""
432 | 
433 |     # MCP server configuration
434 |     mcp_servers = {
435 |         # Example configuration - uncomment and configure as needed:
436 |         # "security": {
437 |         #     "command": "npx",
438 |         #     "args": ["-y", "@modelcontextprotocol/server-security"],
439 |         #     "env": {"API_KEY": "your-key"}
440 |         # }
441 |     }
442 | 
443 |     async with ClaudeSDKClient(
444 |         options=ClaudeCodeOptions(
445 |             permission_prompt_tool_name="mcp__security__approval_prompt",  # Changed from permission_prompt_tool
446 |             mcp_servers=mcp_servers,
447 |             allowed_tools=["Read", "Grep"],
448 |             disallowed_tools=["Bash(rm*)", "Write"],
449 |             system_prompt="You are a security auditor"
450 |         )
451 |     ) as client:
452 |         await client.query("Analyze and fix the security issues")
453 | 
454 |         # Monitor tool usage and permissions
455 |         async for message in client.receive_response():
456 |             if hasattr(message, 'content'):
457 |                 for block in message.content:
458 |                     if hasattr(block, 'type'):  # Added check for 'type' attribute
459 |                         if block.type == 'tool_use':
460 |                             print(f"[Tool: {block.name}] ", end='')
461 |                     if hasattr(block, 'text'):
462 |                         print(block.text, end='', flush=True)
463 | 
464 |             # Check for permission denials in error messages
465 |             if type(message).__name__ == "ErrorMessage":
466 |                 if hasattr(message, 'error') and "Permission denied" in str(message.error):
467 |                     print(f"\n⚠️ Permission denied: {message.error}")
468 | 
469 | # Example MCP server implementation (Python)
470 | # This would be in your MCP server code
471 | async def approval_prompt(tool_name: str, input: dict, tool_use_id: str = None):
472 |     """Custom permission prompt handler"""
473 |     # Your custom logic here
474 |     if "allow" in str(input):
475 |         return json.dumps({
476 |             "behavior": "allow",
477 |             "updatedInput": input
478 |         })
479 |     else:
480 |         return json.dumps({
481 |             "behavior": "deny",
482 |             "message": f"Permission denied for {tool_name}"
483 |         })
484 | 
485 | asyncio.run(use_permission_prompt())
486 | ```
487 | 
488 | ## Output formats
489 | 
490 | ### Text output with streaming
491 | 
492 | ```python
493 | # Default text output with streaming
494 | async with ClaudeSDKClient() as client:
495 |     await client.query("Explain file src/components/Header.tsx")
496 | 
497 |     # Stream text as it arrives
498 |     async for message in client.receive_response():
499 |         if hasattr(message, 'content'):
500 |             for block in message.content:
501 |                 if hasattr(block, 'text'):
502 |                     print(block.text, end='', flush=True)
503 |                     # Output streams in real-time: This is a React component showing...
504 | ```
505 | 
506 | ### JSON output with metadata
507 | 
508 | ```python
509 | # Collect all messages with metadata
510 | async with ClaudeSDKClient() as client:
511 |     await client.query("How does the data layer work?")
512 | 
513 |     messages = []
514 |     result_data = None
515 | 
516 |     async for message in client.receive_messages():
517 |         messages.append(message)
518 | 
519 |         # Capture result message with metadata
520 |         if type(message).__name__ == "ResultMessage":
521 |             result_data = {
522 |                 "result": message.result,
523 |                 "cost": message.total_cost_usd,
524 |                 "duration": message.duration_ms,
525 |                 "num_turns": message.num_turns,
526 |                 "session_id": message.session_id
527 |             }
528 |             break
529 | 
530 |     print(result_data)
531 | ```
532 | 
533 | ## Input formats
534 | 
535 | ```python
536 | import asyncio
537 | from claude_code_sdk import ClaudeSDKClient
538 | 
539 | async def process_inputs():
540 |     async with ClaudeSDKClient() as client:
541 |         # Text input
542 |         await client.query("Explain this code")
543 |         async for message in client.receive_response():
544 |             # Process streaming response
545 |             pass
546 | 
547 |         # Image input (Claude will use Read tool automatically)
548 |         await client.query("What's in this diagram? screenshot.png")
549 |         async for message in client.receive_response():
550 |             # Process image analysis
551 |             pass
552 | 
553 |         # Multiple inputs with mixed content
554 |         inputs = [
555 |             "Analyze the architecture in diagram.png",
556 |             "Compare it with best practices",
557 |             "Generate improved version"
558 |         ]
559 | 
560 |         for prompt in inputs:
561 |             await client.query(prompt)
562 |             async for message in client.receive_response():
563 |                 # Process each response
564 |                 pass
565 | 
566 | asyncio.run(process_inputs())
567 | ```
568 | 
569 | ## Agent integration examples
570 | 
571 | ### SRE incident response agent
572 | 
573 | ```python
574 | import asyncio
575 | from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions
576 | 
577 | async def investigate_incident(incident_description: str, severity: str = "medium"):
578 |     """Automated incident response agent with real-time streaming"""
579 | 
580 |     # MCP server configuration for monitoring tools
581 |     mcp_servers = {
582 |         # Example configuration - uncomment and configure as needed:
583 |         # "datadog": {
584 |         #     "command": "npx",
585 |         #     "args": ["-y", "@modelcontextprotocol/server-datadog"],
586 |         #     "env": {"API_KEY": "your-datadog-key", "APP_KEY": "your-app-key"}
587 |         # }
588 |     }
589 | 
590 |     async with ClaudeSDKClient(
591 |         options=ClaudeCodeOptions(
592 |             system_prompt="You are an SRE expert. Diagnose issues systematically and provide actionable solutions.",
593 |             max_turns=6,
594 |             allowed_tools=["Bash", "Read", "WebSearch", "mcp__datadog"],
595 |             mcp_servers=mcp_servers
596 |         )
597 |     ) as client:
598 |         # Send the incident details
599 |         prompt = f"Incident: {incident_description} (Severity: {severity})"
600 |         print(f"🚨 Investigating: {prompt}\n")
601 |         await client.query(prompt)
602 | 
603 |         # Stream the investigation process
604 |         investigation_log = []
605 |         async for message in client.receive_response():
606 |             if hasattr(message, 'content'):
607 |                 for block in message.content:
608 |                     if hasattr(block, 'type'):
609 |                         if block.type == 'tool_use':
610 |                             print(f"[{block.name}] ", end='')
611 |                     if hasattr(block, 'text'):
612 |                         text = block.text
613 |                         print(text, end='', flush=True)
614 |                         investigation_log.append(text)
615 | 
616 |             # Capture final result
617 |             if type(message).__name__ == "ResultMessage":
618 |                 return {
619 |                     'analysis': ''.join(investigation_log),
620 |                     'cost': message.total_cost_usd,
621 |                     'duration_ms': message.duration_ms
622 |                 }
623 | 
624 | # Usage
625 | result = await investigate_incident("Payment API returning 500 errors", "high")
626 | print(f"\n\nInvestigation complete. Cost: ${result['cost']:.4f}")
627 | ```
628 | 
629 | ### Automated security review
630 | 
631 | ```python
632 | import subprocess
633 | import asyncio
634 | import json
635 | from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions
636 | 
637 | async def audit_pr(pr_number: int):
638 |     """Security audit agent for pull requests with streaming feedback"""
639 |     # Get PR diff
640 |     pr_diff = subprocess.check_output(
641 |         ["gh", "pr", "diff", str(pr_number)],
642 |         text=True
643 |     )
644 | 
645 |     async with ClaudeSDKClient(
646 |         options=ClaudeCodeOptions(
647 |             system_prompt="You are a security engineer. Review this PR for vulnerabilities, insecure patterns, and compliance issues.",
648 |             max_turns=3,
649 |             allowed_tools=["Read", "Grep", "WebSearch"]
650 |         )
651 |     ) as client:
652 |         print(f"🔍 Auditing PR #{pr_number}\n")
653 |         await client.query(pr_diff)
654 | 
655 |         findings = []
656 |         async for message in client.receive_response():
657 |             if hasattr(message, 'content'):
658 |                 for block in message.content:
659 |                     if hasattr(block, 'text'):
660 |                         # Stream findings as they're discovered
661 |                         print(block.text, end='', flush=True)
662 |                         findings.append(block.text)
663 | 
664 |             if type(message).__name__ == "ResultMessage":
665 |                 return {
666 |                     'pr_number': pr_number,
667 |                     'findings': ''.join(findings),
668 |                     'metadata': {
669 |                         'cost': message.total_cost_usd,
670 |                         'duration': message.duration_ms,
671 |                         'severity': 'high' if 'vulnerability' in ''.join(findings).lower() else 'medium'
672 |                     }
673 |                 }
674 | 
675 | # Usage
676 | report = await audit_pr(123)
677 | print(f"\n\nAudit complete. Severity: {report['metadata']['severity']}")
678 | print(json.dumps(report, indent=2))
679 | ```
680 | 
681 | ### Multi-turn legal assistant
682 | 
683 | ```python
684 | import asyncio
685 | from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions
686 | 
687 | async def legal_review():
688 |     """Legal document review with persistent session and streaming"""
689 | 
690 |     async with ClaudeSDKClient(
691 |         options=ClaudeCodeOptions(
692 |             system_prompt="You are a corporate lawyer. Provide detailed legal analysis.",
693 |             max_turns=2
694 |         )
695 |     ) as client:
696 |         # Multi-step review in same session
697 |         steps = [
698 |             "Review contract.pdf for liability clauses",
699 |             "Check compliance with GDPR requirements",
700 |             "Generate executive summary of risks"
701 |         ]
702 | 
703 |         review_results = []
704 | 
705 |         for step in steps:
706 |             print(f"\n📋 {step}\n")
707 |             await client.query(step)
708 | 
709 |             step_result = []
710 |             async for message in client.receive_response():
711 |                 if hasattr(message, 'content'):
712 |                     for block in message.content:
713 |                         if hasattr(block, 'text'):
714 |                             text = block.text
715 |                             print(text, end='', flush=True)
716 |                             step_result.append(text)
717 | 
718 |                 if type(message).__name__ == "ResultMessage":
719 |                     review_results.append({
720 |                         'step': step,
721 |                         'analysis': ''.join(step_result),
722 |                         'cost': message.total_cost_usd
723 |                     })
724 | 
725 |         # Summary
726 |         total_cost = sum(r['cost'] for r in review_results)
727 |         print(f"\n\n✅ Legal review complete. Total cost: ${total_cost:.4f}")
728 |         return review_results
729 | 
730 | # Usage
731 | results = await legal_review()
732 | ```
733 | 
734 | ## Python-specific best practices
735 | 
736 | ### Key patterns
737 | 
738 | ```python
739 | import asyncio
740 | from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions
741 | 
742 | # Always use context managers
743 | async with ClaudeSDKClient() as client:
744 |     await client.query("Analyze this code")
745 |     async for msg in client.receive_response():
746 |         # Process streaming messages
747 |         pass
748 | 
749 | # Run multiple agents concurrently
750 | async with ClaudeSDKClient() as reviewer, ClaudeSDKClient() as tester:
751 |     await asyncio.gather(
752 |         reviewer.query("Review main.py"),
753 |         tester.query("Write tests for main.py")
754 |     )
755 | 
756 | # Error handling
757 | from claude_code_sdk import CLINotFoundError, ProcessError
758 | 
759 | try:
760 |     async with ClaudeSDKClient() as client:
761 |         # Your code here
762 |         pass
763 | except CLINotFoundError:
764 |     print("Install CLI: npm install -g @anthropic-ai/claude-code")
765 | except ProcessError as e:
766 |     print(f"Process error: {e}")
767 | 
768 | # Collect full response with metadata
769 | async def get_response(client, prompt):
770 |     await client.query(prompt)
771 |     text = []
772 |     async for msg in client.receive_response():
773 |         if hasattr(msg, 'content'):
774 |             for block in msg.content:
775 |                 if hasattr(block, 'text'):
776 |                     text.append(block.text)
777 |         if type(msg).__name__ == "ResultMessage":
778 |             return {'text': ''.join(text), 'cost': msg.total_cost_usd}
779 | ```
780 | 
781 | ### IPython/Jupyter tips
782 | 
783 | ```python
784 | # In Jupyter, use await directly in cells
785 | client = ClaudeSDKClient()
786 | await client.connect()
787 | await client.query("Analyze data.csv")
788 | async for msg in client.receive_response():
789 |     print(msg)
790 | await client.disconnect()
791 | 
792 | # Create reusable helper functions
793 | async def stream_print(client, prompt):
794 |     await client.query(prompt)
795 |     async for msg in client.receive_response():
796 |         if hasattr(msg, 'content'):
797 |             for block in msg.content:
798 |                 if hasattr(block, 'text'):
799 |                     print(block.text, end='', flush=True)
800 | ```
801 | 
802 | ## Related resources
803 | 
804 | * [CLI usage and controls](/en/docs/claude-code/cli-reference) - Complete CLI documentation
805 | * [GitHub Actions integration](/en/docs/claude-code/github-actions) - Automate your GitHub workflow with Claude
806 | * [Common workflows](/en/docs/claude-code/common-workflows) - Step-by-step guides for common use cases
807 | 


--------------------------------------------------------------------------------
/ai_docs/watch-dog-python-docs.md:
--------------------------------------------------------------------------------
  1 | 
  2 | Example API Usage
  3 | A simple program that uses watchdog to monitor directories specified as command-line arguments and logs events generated:
  4 | 
  5 | import time
  6 | 
  7 | from watchdog.events import FileSystemEvent, FileSystemEventHandler
  8 | from watchdog.observers import Observer
  9 | 
 10 | 
 11 | class MyEventHandler(FileSystemEventHandler):
 12 |     def on_any_event(self, event: FileSystemEvent) -> None:
 13 |         print(event)
 14 | 
 15 | 
 16 | event_handler = MyEventHandler()
 17 | observer = Observer()
 18 | observer.schedule(event_handler, ".", recursive=True)
 19 | observer.start()
 20 | try:
 21 |     while True:
 22 |         time.sleep(1)
 23 | finally:
 24 |     observer.stop()
 25 |     observer.join()
 26 | 
 27 | 
 28 | API Reference
 29 | watchdog.events
 30 | module:	watchdog.events
 31 | synopsis:	File system events and event handlers.
 32 | author:	yesudeep@google.com (Yesudeep Mangalapilly)
 33 | Event Classes
 34 | class watchdog.events.FileSystemEvent(src_path)[source]
 35 | Bases: object
 36 | 
 37 | Immutable type that represents a file system event that is triggered when a change occurs on the monitored file system.
 38 | 
 39 | All FileSystemEvent objects are required to be immutable and hence can be used as keys in dictionaries or be added to sets.
 40 | 
 41 | event_type = None
 42 | The type of the event as a string.
 43 | 
 44 | is_directory = False
 45 | True if event was emitted for a directory; False otherwise.
 46 | 
 47 | src_path[source]
 48 | Source path of the file system object that triggered this event.
 49 | 
 50 | class watchdog.events.FileSystemMovedEvent(src_path, dest_path)[source]
 51 | Bases: watchdog.events.FileSystemEvent
 52 | 
 53 | File system event representing any kind of file system movement.
 54 | 
 55 | dest_path[source]
 56 | The destination path of the move event.
 57 | 
 58 | class watchdog.events.FileMovedEvent(src_path, dest_path)[source]
 59 | Bases: watchdog.events.FileSystemMovedEvent
 60 | 
 61 | File system event representing file movement on the file system.
 62 | 
 63 | class watchdog.events.DirMovedEvent(src_path, dest_path)[source]
 64 | Bases: watchdog.events.FileSystemMovedEvent
 65 | 
 66 | File system event representing directory movement on the file system.
 67 | 
 68 | class watchdog.events.FileModifiedEvent(src_path)[source]
 69 | Bases: watchdog.events.FileSystemEvent
 70 | 
 71 | File system event representing file modification on the file system.
 72 | 
 73 | class watchdog.events.DirModifiedEvent(src_path)[source]
 74 | Bases: watchdog.events.FileSystemEvent
 75 | 
 76 | File system event representing directory modification on the file system.
 77 | 
 78 | class watchdog.events.FileCreatedEvent(src_path)[source]
 79 | Bases: watchdog.events.FileSystemEvent
 80 | 
 81 | File system event representing file creation on the file system.
 82 | 
 83 | class watchdog.events.DirCreatedEvent(src_path)[source]
 84 | Bases: watchdog.events.FileSystemEvent
 85 | 
 86 | File system event representing directory creation on the file system.
 87 | 
 88 | class watchdog.events.FileDeletedEvent(src_path)[source]
 89 | Bases: watchdog.events.FileSystemEvent
 90 | 
 91 | File system event representing file deletion on the file system.
 92 | 
 93 | class watchdog.events.DirDeletedEvent(src_path)[source]
 94 | Bases: watchdog.events.FileSystemEvent
 95 | 
 96 | File system event representing directory deletion on the file system.
 97 | 
 98 | Event Handler Classes
 99 | class watchdog.events.FileSystemEventHandler[source]
100 | Bases: object
101 | 
102 | Base file system event handler that you can override methods from.
103 | 
104 | dispatch(event)[source]
105 | Dispatches events to the appropriate methods.
106 | 
107 | Parameters:	event (FileSystemEvent) – The event object representing the file system event.
108 | on_any_event(event)[source]
109 | Catch-all event handler.
110 | 
111 | Parameters:	event (FileSystemEvent) – The event object representing the file system event.
112 | on_created(event)[source]
113 | Called when a file or directory is created.
114 | 
115 | Parameters:	event (DirCreatedEvent or FileCreatedEvent) – Event representing file/directory creation.
116 | on_deleted(event)[source]
117 | Called when a file or directory is deleted.
118 | 
119 | Parameters:	event (DirDeletedEvent or FileDeletedEvent) – Event representing file/directory deletion.
120 | on_modified(event)[source]
121 | Called when a file or directory is modified.
122 | 
123 | Parameters:	event (DirModifiedEvent or FileModifiedEvent) – Event representing file/directory modification.
124 | on_moved(event)[source]
125 | Called when a file or a directory is moved or renamed.
126 | 
127 | Parameters:	event (DirMovedEvent or FileMovedEvent) – Event representing file/directory movement.
128 | class watchdog.events.PatternMatchingEventHandler(patterns=None, ignore_patterns=None, ignore_directories=False, case_sensitive=False)[source]
129 | Bases: watchdog.events.FileSystemEventHandler
130 | 
131 | Matches given patterns with file paths associated with occurring events.
132 | 
133 | case_sensitive[source]
134 | (Read-only) True if path names should be matched sensitive to case; False otherwise.
135 | 
136 | dispatch(event)[source]
137 | Dispatches events to the appropriate methods.
138 | 
139 | Parameters:	event (FileSystemEvent) – The event object representing the file system event.
140 | ignore_directories[source]
141 | (Read-only) True if directories should be ignored; False otherwise.
142 | 
143 | ignore_patterns[source]
144 | (Read-only) Patterns to ignore matching event paths.
145 | 
146 | patterns[source]
147 | (Read-only) Patterns to allow matching event paths.
148 | 
149 | class watchdog.events.RegexMatchingEventHandler(regexes=['.*'], ignore_regexes=[], ignore_directories=False, case_sensitive=False)[source]
150 | Bases: watchdog.events.FileSystemEventHandler
151 | 
152 | Matches given regexes with file paths associated with occurring events.
153 | 
154 | case_sensitive[source]
155 | (Read-only) True if path names should be matched sensitive to case; False otherwise.
156 | 
157 | dispatch(event)[source]
158 | Dispatches events to the appropriate methods.
159 | 
160 | Parameters:	event (FileSystemEvent) – The event object representing the file system event.
161 | ignore_directories[source]
162 | (Read-only) True if directories should be ignored; False otherwise.
163 | 
164 | ignore_regexes[source]
165 | (Read-only) Regexes to ignore matching event paths.
166 | 
167 | regexes[source]
168 | (Read-only) Regexes to allow matching event paths.
169 | 
170 | class watchdog.events.LoggingEventHandler[source]
171 | Bases: watchdog.events.FileSystemEventHandler
172 | 
173 | Logs all the events captured.
174 | 
175 | watchdog.observers.api
176 | Immutables
177 | class watchdog.observers.api.ObservedWatch(path, recursive)[source]
178 | Bases: object
179 | 
180 | An scheduled watch.
181 | 
182 | Parameters:	
183 | path – Path string.
184 | recursive – True if watch is recursive; False otherwise.
185 | is_recursive[source]
186 | Determines whether subdirectories are watched for the path.
187 | 
188 | path[source]
189 | The path that this watch monitors.
190 | 
191 | Collections
192 | class watchdog.observers.api.EventQueue(maxsize=0)[source]
193 | Bases: watchdog.utils.bricks.SkipRepeatsQueue
194 | 
195 | Thread-safe event queue based on a special queue that skips adding the same event (FileSystemEvent) multiple times consecutively. Thus avoiding dispatching multiple event handling calls when multiple identical events are produced quicker than an observer can consume them.
196 | 
197 | Classes
198 | class watchdog.observers.api.EventEmitter(event_queue, watch, timeout=1)[source]
199 | Bases: watchdog.utils.BaseThread
200 | 
201 | Producer thread base class subclassed by event emitters that generate events and populate a queue with them.
202 | 
203 | Parameters:	
204 | event_queue (watchdog.events.EventQueue) – The event queue to populate with generated events.
205 | watch (ObservedWatch) – The watch to observe and produce events for.
206 | timeout (float) – Timeout (in seconds) between successive attempts at reading events.
207 | queue_event(event)[source]
208 | Queues a single event.
209 | 
210 | Parameters:	event (An instance of watchdog.events.FileSystemEvent or a subclass.) – Event to be queued.
211 | queue_events(timeout)[source]
212 | Override this method to populate the event queue with events per interval period.
213 | 
214 | Parameters:	timeout (float) – Timeout (in seconds) between successive attempts at reading events.
215 | timeout[source]
216 | Blocking timeout for reading events.
217 | 
218 | watch[source]
219 | The watch associated with this emitter.
220 | 
221 | class watchdog.observers.api.EventDispatcher(timeout=1)[source]
222 | Bases: watchdog.utils.BaseThread
223 | 
224 | Consumer thread base class subclassed by event observer threads that dispatch events from an event queue to appropriate event handlers.
225 | 
226 | Parameters:	timeout (float) – Event queue blocking timeout (in seconds).
227 | dispatch_events(event_queue, timeout)[source]
228 | Override this method to consume events from an event queue, blocking on the queue for the specified timeout before raising queue.Empty.
229 | 
230 | Parameters:	
231 | event_queue (EventQueue) – Event queue to populate with one set of events.
232 | timeout (float) – Interval period (in seconds) to wait before timing out on the event queue.
233 | Raises:	
234 | queue.Empty
235 | 
236 | event_queue[source]
237 | The event queue which is populated with file system events by emitters and from which events are dispatched by a dispatcher thread.
238 | 
239 | timeout[source]
240 | Event queue block timeout.
241 | 
242 | class watchdog.observers.api.BaseObserver(emitter_class, timeout=1)[source]
243 | Bases: watchdog.observers.api.EventDispatcher
244 | 
245 | Base observer.
246 | 
247 | add_handler_for_watch(event_handler, watch)[source]
248 | Adds a handler for the given watch.
249 | 
250 | Parameters:	
251 | event_handler (watchdog.events.FileSystemEventHandler or a subclass) – An event handler instance that has appropriate event handling methods which will be called by the observer in response to file system events.
252 | watch (An instance of ObservedWatch or a subclass of ObservedWatch) – The watch to add a handler for.
253 | emitters[source]
254 | Returns event emitter created by this observer.
255 | 
256 | remove_handler_for_watch(event_handler, watch)[source]
257 | Removes a handler for the given watch.
258 | 
259 | Parameters:	
260 | event_handler (watchdog.events.FileSystemEventHandler or a subclass) – An event handler instance that has appropriate event handling methods which will be called by the observer in response to file system events.
261 | watch (An instance of ObservedWatch or a subclass of ObservedWatch) – The watch to remove a handler for.
262 | schedule(event_handler, path, recursive=False)[source]
263 | Schedules watching a path and calls appropriate methods specified in the given event handler in response to file system events.
264 | 
265 | Parameters:	
266 | event_handler (watchdog.events.FileSystemEventHandler or a subclass) – An event handler instance that has appropriate event handling methods which will be called by the observer in response to file system events.
267 | path (str) – Directory path that will be monitored.
268 | recursive (bool) – True if events will be emitted for sub-directories traversed recursively; False otherwise.
269 | Returns:	
270 | An ObservedWatch object instance representing a watch.
271 | 
272 | unschedule(watch)[source]
273 | Unschedules a watch.
274 | 
275 | Parameters:	watch (An instance of ObservedWatch or a subclass of ObservedWatch) – The watch to unschedule.
276 | unschedule_all()[source]
277 | Unschedules all watches and detaches all associated event handlers.
278 | 
279 | watchdog.observers
280 | module:	watchdog.observers
281 | synopsis:	Observer that picks a native implementation if available.
282 | author:	yesudeep@google.com (Yesudeep Mangalapilly)
283 | Classes
284 | watchdog.observers.Observer
285 | alias of InotifyObserver
286 | 
287 | Observer thread that schedules watching directories and dispatches calls to event handlers.
288 | 
289 | You can also import platform specific classes directly and use it instead of Observer. Here is a list of implemented observer classes.:
290 | 
291 | Class	Platforms	Note
292 | inotify.InotifyObserver	Linux 2.6.13+	inotify(7) based observer
293 | fsevents.FSEventsObserver	Mac OS X	FSEvents based observer
294 | kqueue.KqueueObserver	Mac OS X and BSD with kqueue(2)	kqueue(2) based observer
295 | read_directory_changes.WindowsApiObserver	MS Windows	Windows API-based observer
296 | polling.PollingObserver	Any	fallback implementation
297 | watchdog.observers.polling
298 | module:	watchdog.observers.polling
299 | synopsis:	Polling emitter implementation.
300 | author:	yesudeep@google.com (Yesudeep Mangalapilly)
301 | Classes
302 | class watchdog.observers.polling.PollingObserver(timeout=1)[source]
303 | Bases: watchdog.observers.api.BaseObserver
304 | 
305 | Platform-independent observer that polls a directory to detect file system changes.
306 | 
307 | class watchdog.observers.polling.PollingObserverVFS(stat, listdir, polling_interval=1)[source]
308 | Bases: watchdog.observers.api.BaseObserver
309 | 
310 | File system independent observer that polls a directory to detect changes.
311 | 
312 | __init__(stat, listdir, polling_interval=1)[source]
313 | Parameters:	
314 | stat – stat function. See os.stat for details.
315 | listdir – listdir function. See os.listdir for details.
316 | polling_interval (float) – interval in seconds between polling the file system.
317 | watchdog.utils
318 | module:	watchdog.utils
319 | synopsis:	Utility classes and functions.
320 | author:	yesudeep@google.com (Yesudeep Mangalapilly)
321 | Classes
322 | class watchdog.utils.BaseThread[source]
323 | Bases: threading.Thread
324 | 
325 | Convenience class for creating stoppable threads.
326 | 
327 | daemon
328 | A boolean value indicating whether this thread is a daemon thread (True) or not (False).
329 | 
330 | This must be set before start() is called, otherwise RuntimeError is raised. Its initial value is inherited from the creating thread; the main thread is not a daemon thread and therefore all threads created in the main thread default to daemon = False.
331 | 
332 | The entire Python program exits when no alive non-daemon threads are left.
333 | 
334 | ident
335 | Thread identifier of this thread or None if it has not been started.
336 | 
337 | This is a nonzero integer. See the thread.get_ident() function. Thread identifiers may be recycled when a thread exits and another thread is created. The identifier is available even after the thread has exited.
338 | 
339 | isAlive()
340 | Return whether the thread is alive.
341 | 
342 | This method returns True just before the run() method starts until just after the run() method terminates. The module function enumerate() returns a list of all alive threads.
343 | 
344 | is_alive()
345 | Return whether the thread is alive.
346 | 
347 | This method returns True just before the run() method starts until just after the run() method terminates. The module function enumerate() returns a list of all alive threads.
348 | 
349 | join(timeout=None)
350 | Wait until the thread terminates.
351 | 
352 | This blocks the calling thread until the thread whose join() method is called terminates – either normally or through an unhandled exception or until the optional timeout occurs.
353 | 
354 | When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof). As join() always returns None, you must call isAlive() after join() to decide whether a timeout happened – if the thread is still alive, the join() call timed out.
355 | 
356 | When the timeout argument is not present or None, the operation will block until the thread terminates.
357 | 
358 | A thread can be join()ed many times.
359 | 
360 | join() raises a RuntimeError if an attempt is made to join the current thread as that would cause a deadlock. It is also an error to join() a thread before it has been started and attempts to do so raises the same exception.
361 | 
362 | name
363 | A string used for identification purposes only.
364 | 
365 | It has no semantics. Multiple threads may be given the same name. The initial name is set by the constructor.
366 | 
367 | on_thread_start()[source]
368 | Override this method instead of start(). start() calls this method.
369 | 
370 | This method is called right before this thread is started and this object’s run() method is invoked.
371 | 
372 | on_thread_stop()[source]
373 | Override this method instead of stop(). stop() calls this method.
374 | 
375 | This method is called immediately after the thread is signaled to stop.
376 | 
377 | run()
378 | Method representing the thread’s activity.
379 | 
380 | You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.
381 | 
382 | should_keep_running()[source]
383 | Determines whether the thread should continue running.
384 | 
385 | stop()[source]
386 | Signals the thread to stop.
387 | 
388 | watchdog.utils.dirsnapshot
389 | module:	watchdog.utils.dirsnapshot
390 | synopsis:	Directory snapshots and comparison.
391 | author:	yesudeep@google.com (Yesudeep Mangalapilly)
392 | Where are the moved events? They “disappeared”
393 | 
394 | This implementation does not take partition boundaries into consideration. It will only work when the directory tree is entirely on the same file system. More specifically, any part of the code that depends on inode numbers can break if partition boundaries are crossed. In these cases, the snapshot diff will represent file/directory movement as created and deleted events.
395 | Classes
396 | class watchdog.utils.dirsnapshot.DirectorySnapshot(path, recursive=True, walker_callback=<function <lambda> at 0x7f78fbeed500>, stat=<built-in function stat>, listdir=<built-in function listdir>)[source]
397 | Bases: object
398 | 
399 | A snapshot of stat information of files in a directory.
400 | 
401 | Parameters:	
402 | path (str) – The directory path for which a snapshot should be taken.
403 | recursive (bool) – True if the entire directory tree should be included in the snapshot; False otherwise.
404 | walker_callback –
405 | Deprecated since version 0.7.2.
406 | 
407 | stat –
408 | Use custom stat function that returns a stat structure for path. Currently only st_dev, st_ino, st_mode and st_mtime are needed.
409 | 
410 | A function with the signature walker_callback(path, stat_info) which will be called for every entry in the directory tree.
411 | 
412 | listdir – Use custom listdir function. See os.listdir for details.
413 | inode(path)[source]
414 | Returns an id for path.
415 | 
416 | path(id)[source]
417 | Returns path for id. None if id is unknown to this snapshot.
418 | 
419 | paths[source]
420 | Set of file/directory paths in the snapshot.
421 | 
422 | stat_info(path)[source]
423 | Returns a stat information object for the specified path from the snapshot.
424 | 
425 | Attached information is subject to change. Do not use unless you specify stat in constructor. Use inode(), mtime(), isdir() instead.
426 | 
427 | Parameters:	path – The path for which stat information should be obtained from a snapshot.
428 | class watchdog.utils.dirsnapshot.DirectorySnapshotDiff(ref, snapshot)[source]
429 | Bases: object
430 | 
431 | Compares two directory snapshots and creates an object that represents the difference between the two snapshots.
432 | 
433 | Parameters:	
434 | ref (DirectorySnapshot) – The reference directory snapshot.
435 | snapshot (DirectorySnapshot) – The directory snapshot which will be compared with the reference snapshot.
436 | dirs_created[source]
437 | List of directories that were created.
438 | 
439 | dirs_deleted[source]
440 | List of directories that were deleted.
441 | 
442 | dirs_modified[source]
443 | List of directories that were modified.
444 | 
445 | dirs_moved[source]
446 | List of directories that were moved.
447 | 
448 | Each event is a two-tuple the first item of which is the path that has been renamed to the second item in the tuple.
449 | 
450 | files_created[source]
451 | List of files that were created.
452 | 
453 | files_deleted[source]
454 | List of files that were deleted.
455 | 
456 | files_modified[source]
457 | List of files that were modified.
458 | 
459 | files_moved[source]
460 | List of files that were moved.
461 | 
462 | Each event is a two-tuple the first item of which is the path that has been renamed to the second item in the tuple.
463 | 
464 | Table Of Contents
465 | API Reference
466 | watchdog.events
467 | Event Classes
468 | Event Handler Classes
469 | watchdog.observers.api
470 | Immutables
471 | Collections
472 | Classes
473 | watchdog.observers
474 | Classes
475 | watchdog.observers.polling
476 | Classes
477 | watchdog.utils
478 | Classes
479 | watchdog.utils.dirsnapshot
480 | Classes
481 | Previous topic
482 | Quickstart
483 | 
484 | Next topic
485 | Contributing
486 | 
487 | Quick search
488 |  
489 | Enter search terms or a module, class or function name.
490 | 
491 | indexmodules |next |previous |watchdog 0.8.2 documentation »
492 | © Copyright 2010, Yesudeep Mangalapilly. Created using Sphinx 1.2.2.


--------------------------------------------------------------------------------
/drops.yaml:
--------------------------------------------------------------------------------
 1 | drop_zones:
 2 |   - name: "Echo Drop Zone"  # Name displayed in logs
 3 |     file_patterns: ["*.txt"]  # File patterns to watch (supports wildcards)
 4 |     reusable_prompt: ".claude/commands/echo.md"  # Path to the reusable prompt file (required)
 5 |     zone_dirs: ["agentic_drop_zone/echo_zone"]  # Directories to monitor (supports * wildcard)
 6 |     events: ["created", "modified"]  # Event types: created, modified, deleted, moved
 7 |     agent: "claude_code"  # Agent type: claude_code, gemini_cli, codex_cli (default: claude_code)
 8 |     model: "sonnet"  # Model to use for Claude Code (default: sonnet)
 9 |     color: "cyan"  # Color for console output (red, blue, green, cyan, yellow, magenta)
10 |     # mcp_server_file: ".mcp.json" # Uncomment this to use MCP servers - don't bloat your context window if you don't need it
11 |     create_zone_dir_if_not_exists: true  # Auto-create non-glob directories if missing (default: false)
12 |   
13 |   - name: "Gemini Echo Drop Zone"  # Test zone for Gemini CLI
14 |     file_patterns: ["*.txt"]  # File patterns to watch
15 |     reusable_prompt: ".claude/commands/echo.md"  # Same echo prompt
16 |     zone_dirs: ["agentic_drop_zone/gemini_echo_zone"]  # Gemini-specific directory
17 |     events: ["created"]  # Trigger on file creation
18 |     agent: "gemini_cli"  # Use Gemini CLI agent
19 |     model: "gemini-2.5-pro"  # Default Gemini model
20 |     color: "green"  # Green for Gemini
21 |     create_zone_dir_if_not_exists: true  # Auto-create directory
22 |   
23 |   - name: "Image Generation Drop Zone"
24 |     file_patterns: ["*.txt", "*.md"]
25 |     reusable_prompt: ".claude/commands/create_image.md"
26 |     zone_dirs: ["agentic_drop_zone/generate_images_zone"]
27 |     events: ["created"]
28 |     agent: "claude_code"
29 |     model: "sonnet"
30 |     color: "blue"
31 |     mcp_server_file: ".mcp.json"
32 |     create_zone_dir_if_not_exists: true
33 |   
34 |   - name: "Gemini Image Generation Drop Zone"
35 |     file_patterns: ["*.txt", "*.md"]
36 |     reusable_prompt: ".claude/commands/create_image.md"
37 |     zone_dirs: ["agentic_drop_zone/gemini_generate_images_zone"]
38 |     events: ["created"]
39 |     agent: "gemini_cli"
40 |     model: "gemini-2.5-pro"
41 |     color: "green"
42 |     mcp_server_file: ".mcp.json"
43 |     create_zone_dir_if_not_exists: true
44 |   
45 |   - name: "Image Edit Drop Zone"
46 |     file_patterns: ["*.txt", "*.md", "*.json"]
47 |     reusable_prompt: ".claude/commands/edit_image.md"
48 |     zone_dirs: ["agentic_drop_zone/edit_images_zone"]
49 |     events: ["created"]
50 |     agent: "claude_code"
51 |     model: "sonnet"
52 |     color: "red"
53 |     mcp_server_file: ".mcp.json"
54 |     create_zone_dir_if_not_exists: true
55 | 
56 |   - name: "Training Data Generation Zone"
57 |     file_patterns: ["*.csv", "*.jsonl"]
58 |     reusable_prompt: ".claude/commands/more_training_data.md"
59 |     zone_dirs: ["agentic_drop_zone/training_data_zone"]
60 |     events: ["created"]
61 |     agent: "claude_code"
62 |     model: "sonnet"
63 |     color: "magenta"
64 |     create_zone_dir_if_not_exists: true
65 | 
66 |   - name: "Morning Debrief Zone"
67 |     file_patterns: ["*.mp3", "*.wav", "*.m4a", "*.flac", "*.ogg", "*.aac", "*.mp4"]
68 |     reusable_prompt: ".claude/commands/morning_debrief.md"
69 |     zone_dirs: ["agentic_drop_zone/morning_debrief_zone"]
70 |     events: ["created"]
71 |     agent: "claude_code"
72 |     model: "sonnet"
73 |     color: "yellow"
74 |     create_zone_dir_if_not_exists: true
75 | 
76 |   - name: "Finance Categorizer Zone"
77 |     file_patterns: ["*.csv"]
78 |     reusable_prompt: ".claude/commands/finance_categorizer.md"
79 |     zone_dirs: ["agentic_drop_zone/finance_zone"]
80 |     events: ["created"]
81 |     agent: "claude_code"
82 |     model: "sonnet"
83 |     color: "green"
84 |     create_zone_dir_if_not_exists: true
85 | 


--------------------------------------------------------------------------------
/edit_image_input_files/cat_sitting_in_chair.jpg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/disler/agentic-drop-zones/16a347bf60afcb60a1c55893deb5859aaeb18dda/edit_image_input_files/cat_sitting_in_chair.jpg


--------------------------------------------------------------------------------
/example_input_files/bank_statement.csv:
--------------------------------------------------------------------------------
  1 | date,description,deposit,withdrawal,category,balance
  2 | 2025-08-01,ACH CREDIT PAYROLL ADP 847291,10000.00,,Income,160000.00
  3 | 2025-08-01,MORTGAGE PYMNT WF 0001234 REF #45789,,4200.00,Housing,155800.00
  4 | 2025-08-01,TESLA MOTORS 650-681-5100 CA,,649.99,Transportation,155150.01
  5 | 2025-08-01,AMAZON.COM*XY8923 AMZN.COM/BILL,,1249.99,Shopping,153900.02
  6 | 2025-08-01,ANTHROPIC CLAUDE-OPUS-4-1-API,,3456.78,AI Services,150443.24
  7 | 2025-08-02,WHFOODS #0245 SAN FRANCISCOCA,,187.45,Food,150255.79
  8 | 2025-08-02,SHELL OIL 57849600001 SAN JOSE CA,,72.30,Transportation,150183.49
  9 | 2025-08-02,AWS SERVICES 866-216-1072 WA,,3847.50,Technology,146335.99
 10 | 2025-08-02,OPENAI API USAGE GPT-4-TURBO,,1234.56,AI Services,145101.43
 11 | 2025-08-03,NETFLIX.COM 866-579-7172 CA,,15.99,Entertainment,145085.44
 12 | 2025-08-03,SPOTIFY USA 646-517-4579 NY,,9.99,Entertainment,145075.45
 13 | 2025-08-03,AMAZON.COM*RT4567 AMZN.COM/BILL,,789.99,Electronics,144285.46
 14 | 2025-08-03,GOOGLE COMPUTE ENGINE VM-8472,,892.45,Cloud Computing,143393.01
 15 | 2025-08-04,TARGET T-1847 REDWOOD CITY CA,,234.67,Shopping,143158.34
 16 | 2025-08-04,AMAZON PRIME NOW*TMP4 AMZN.COM,,156.78,Groceries,143001.56
 17 | 2025-08-04,GOOGLE NANO-BANANA API MODEL,,456.78,AI Services,142544.78
 18 | 2025-08-05,PG&E ONLINE PMT 8001234567,,285.40,Utilities,142259.38
 19 | 2025-08-05,WATER DEPT CITY OF PALO ALTO,,89.75,Utilities,142169.63
 20 | 2025-08-05,AMAZON.COM*BK8901 AMZN.COM/BILL,,2345.67,Home,139823.96
 21 | 2025-08-05,ANTHROPIC CLAUDE-OPUS-4-1-API,,2890.34,AI Services,136933.62
 22 | 2025-08-06,SQ *STARBUCKS STORE SAN FRANC,,12.45,Dining,136921.17
 23 | 2025-08-06,TRADERJOES #542 QPS MENLOPARK,,156.80,Groceries,136764.37
 24 | 2025-08-06,AWS CLOUDFRONT 866-216-1072 WA,,892.30,Technology,135872.07
 25 | 2025-08-06,OPENAI API DALL-E-3 IMAGE GEN,,567.89,AI Services,135304.18
 26 | 2025-08-07,XFINITY MOBILE 8005934500 PA,,119.99,Utilities,135184.19
 27 | 2025-08-07,AMAZON.COM*HG5678 AMZN.COM/BILL,,567.89,Books,134616.30
 28 | 2025-08-07,GOOGLE CLOUD STORAGE BUCKET-847,,234.56,Cloud Computing,134381.74
 29 | 2025-08-08,EQUINOX 877-935-9555 NY,,189.00,Recreation,134192.74
 30 | 2025-08-08,AMAZON.COM*MK4567 AMZN.COM/BILL,,89.99,Shopping,134102.75
 31 | 2025-08-08,AWS EC2 INSTANCES 866-216-1072,,1567.45,Technology,132535.30
 32 | 2025-08-08,ANTHROPIC CLAUDE-OPUS-4-1-API,,4567.89,AI Services,127967.41
 33 | 2025-08-09,SQ *THE FRENCH LAUNDRY YOUNTV,,342.75,Food,127624.66
 34 | 2025-08-09,AMAZON FRESH*W9012 AMZN.COM/BI,,234.56,Groceries,127390.10
 35 | 2025-08-09,GOOGLE NANO-BANANA BATCH PROC,,789.12,AI Services,126600.98
 36 | 2025-08-10,CHEVRON #9847 SAN MATEO CA,,68.90,Transportation,126532.08
 37 | 2025-08-10,CVS/PHARMACY #03847 PALO ALTO,,45.67,Health,126486.41
 38 | 2025-08-10,AMAZON.COM*OP3456 AMZN.COM/BILL,,3456.78,Electronics,123029.63
 39 | 2025-08-10,OPENAI API FINE-TUNING JOB-847,,2345.67,AI Services,120683.96
 40 | 2025-08-11,FARMERS INS 8009346700 REF1234,,2150.00,Insurance,118533.96
 41 | 2025-08-11,AMAZON SUBSCRIBE SAVE AMZN.COM,,456.90,Household,118077.06
 42 | 2025-08-11,GOOGLE COMPUTE ENGINE GPU-T4,,1567.89,Cloud Computing,116509.17
 43 | 2025-08-12,COSTCO WHSE #0456 REDWOOD CITY,,298.44,Groceries,116210.73
 44 | 2025-08-12,UBER * TRIP JUL27 HELP.UBER.COM,,23.50,Transportation,116187.23
 45 | 2025-08-12,AWS S3 STORAGE 866-216-1072 WA,,678.90,Technology,115508.33
 46 | 2025-08-12,ANTHROPIC CLAUDE-OPUS-4-1-API,,3789.45,AI Services,111718.88
 47 | 2025-08-13,APL* APPLE ONLINE STORE 800-692-7753,,89.99,Technology,111628.89
 48 | 2025-08-13,AMAZON.COM*QW7890 AMZN.COM/BILL,,1234.56,Office,110394.33
 49 | 2025-08-13,GOOGLE NANO-BANANA API PREMIUM,,567.89,AI Services,109826.44
 50 | 2025-08-14,PRESIDIO DRY CLNRS SAN FRANCISC,,38.50,Laundry,109787.94
 51 | 2025-08-14,BLUE BOTTLE COFFEE #45 SF CA,,8.75,Coffee,109779.19
 52 | 2025-08-14,AMAZON PRIME VIDEO RENT/BUY,,19.99,Entertainment,109759.20
 53 | 2025-08-14,OPENAI API WHISPER TRANSCRIBE,,345.67,AI Services,109413.53
 54 | 2025-08-15,ACH CREDIT PAYROLL ADP 847291,10000.00,,Income,119413.53
 55 | 2025-08-15,GEICO AUTO INS 8009876543,,1245.60,Insurance,118167.93
 56 | 2025-08-15,AWS LAMBDA FUNCTIONS 866-216-1072,,234.78,Technology,117933.15
 57 | 2025-08-15,ANTHROPIC CLAUDE-OPUS-4-1-API,,5678.90,AI Services,112254.25
 58 | 2025-08-16,SAFEWAY STORE 1847 MENLO PARK CA,,145.30,Groceries,112108.95
 59 | 2025-08-16,SF PARKING METER 45F7G,,4.50,Parking,112104.45
 60 | 2025-08-16,AMAZON.COM*YU8901 AMZN.COM/BILL,,4567.89,Furniture,107536.56
 61 | 2025-08-16,GOOGLE CLOUD RUN SERVICES-8472,,456.78,Cloud Computing,107079.78
 62 | 2025-08-17,AMC METREON 16 SAN FRANCISCO CA,,32.50,Entertainment,107047.28
 63 | 2025-08-17,PAZZO RISTORANTE PALO ALTO CA,,78.90,Dining,106968.38
 64 | 2025-08-17,AWS RDS DATABASE 866-216-1072 WA,,1890.45,Technology,105077.93
 65 | 2025-08-17,GOOGLE NANO-BANANA HIGH-RES,,890.12,AI Services,104187.81
 66 | 2025-08-18,AMAZON.COM*BK7890 AMZN.COM/BILL,,67.85,Books,104119.96
 67 | 2025-08-18,AMAZON FRESH*TMP9 AMZN.COM/BI,,189.34,Groceries,103930.62
 68 | 2025-08-18,OPENAI API GPT-4-VISION,,1456.78,AI Services,102473.84
 69 | 2025-08-19,VERIZON WRLS*VTIQ 8009220204 NY,,145.99,Phone,102327.85
 70 | 2025-08-19,HOME DEPOT #4571 REDWOOD CITY,,189.75,Home Improvement,102138.10
 71 | 2025-08-19,AMAZON.COM*GH2345 AMZN.COM/BILL,,789.01,Gaming,101349.09
 72 | 2025-08-19,ANTHROPIC CLAUDE-OPUS-4-1-API,,2345.67,AI Services,99003.42
 73 | 2025-08-20,DR JENNIFER SMITH DDS PALO ALT,,250.00,Medical,98753.42
 74 | 2025-08-20,PANERA BREAD #203847 PALO ALTO,,14.85,Food,98738.57
 75 | 2025-08-20,AWS CLOUDWATCH 866-216-1072 WA,,456.78,Technology,98281.79
 76 | 2025-08-20,GOOGLE COMPUTE ENGINE NETWORK,,234.56,Cloud Computing,98047.23
 77 | 2025-08-21,SHELL OIL 57849600089 MOUNTAIN V,,74.20,Transportation,97973.03
 78 | 2025-08-21,BEST BUY 00004571 MOUNTAIN VIEW,,345.99,Electronics,97627.04
 79 | 2025-08-21,AMAZON.COM*ZX4567 AMZN.COM/BILL,,2345.67,Appliances,95281.37
 80 | 2025-08-21,GOOGLE NANO-BANANA BULK PROC,,1234.56,AI Services,94046.81
 81 | 2025-08-22,BLUE CROSS BLUE SHIELD 8457291,,890.50,Insurance,93156.31
 82 | 2025-08-22,KROGER #0847 ATLANTA GA,,167.40,Food,92988.91
 83 | 2025-08-22,AWS MONTHLY BILLING 866-216-1072,,5678.90,Technology,87310.01
 84 | 2025-08-22,ANTHROPIC CLAUDE-OPUS-4-1-API,,4567.89,AI Services,82742.12
 85 | 2025-08-23,HULU 2132057171 CA,,14.99,Entertainment,82727.13
 86 | 2025-08-23,SQ *PHILZ COFFEE SF MISSION,,6.25,Coffee,82720.88
 87 | 2025-08-23,AMAZON.COM*UI8901 AMZN.COM/BILL,,678.90,Clothing,82042.98
 88 | 2025-08-23,OPENAI API EMBEDDINGS ADA-002,,567.89,AI Services,81474.09
 89 | 2025-08-24,SANTA CLARA CNTY TAX COLL,,3456.78,Government,78017.31
 90 | 2025-08-24,AMAZON PRIME NOW*TMP7 AMZN.COM,,234.56,Groceries,77782.75
 91 | 2025-08-24,GOOGLE CLOUD BIGQUERY USAGE,,789.45,Cloud Computing,76993.30
 92 | 2025-08-25,AKIKO'S RESTAURANT SF CA,,134.60,Dining,76858.70
 93 | 2025-08-25,UBER EATS *TEMP AUTH 415-555-1234,,28.75,Food,76829.95
 94 | 2025-08-25,AMAZON.COM*ER3456 AMZN.COM/BILL,,1567.89,Sports,75262.06
 95 | 2025-08-25,ANTHROPIC CLAUDE-OPUS-4-1-API,,3456.78,AI Services,71805.28
 96 | 2025-08-26,TARGET.COM * 800-591-3869 MN,,98.33,Shopping,71706.95
 97 | 2025-08-26,EXXONMOBIL 57849600123 CA,,71.45,Transportation,71635.50
 98 | 2025-08-26,AWS ELASTIC IP 866-216-1072 WA,,123.45,Technology,71512.05
 99 | 2025-08-26,GOOGLE NANO-BANANA API CALLS,,456.78,AI Services,71055.27
100 | 2025-08-27,NEW YORK LIFE INS 8009876543,,234.50,Insurance,70820.77
101 | 2025-08-27,AMAZON FRESH*W847JK AMZN.COM/BI,,87.65,Food,70733.12
102 | 2025-08-27,AMAZON.COM*PO9012 AMZN.COM/BILL,,3456.78,Photography,67276.34
103 | 2025-08-27,OPENAI API FUNCTION CALLING,,890.12,AI Services,66386.22
104 | 2025-08-28,GOLDEN GATE CAR WASH SF CA,,25.00,Auto,66361.22
105 | 2025-08-28,WALGREENS #07841 PALO ALTO CA,,34.99,Pharmacy,66326.23
106 | 2025-08-28,AWS SUPPORT PLAN 866-216-1072 WA,,789.00,Technology,65537.23
107 | 2025-08-28,GOOGLE COMPUTE ENGINE K8S-CLUS,,1234.56,Cloud Computing,64302.67
108 | 2025-08-29,NORDSTROM #121 SAN FRANCISCO CA,,456.80,Clothing,63845.87
109 | 2025-08-29,CHIPOTLE 0847 MOUNTAIN VIEW CA,,12.95,Fast Food,63832.92
110 | 2025-08-29,AMAZON.COM*CV6789 AMZN.COM/BILL,,2789.45,Computer,61043.47
111 | 2025-08-29,ANTHROPIC CLAUDE-OPUS-4-1-API,,6789.01,AI Services,54254.46
112 | 2025-08-30,PGANDE ONLINE PMT REF 8457291,,156.70,Utilities,54097.76
113 | 2025-08-30,PETCO #847 REDWOOD CITY CA,,78.99,Pet Care,54018.77
114 | 2025-08-30,AWS DATA TRANSFER 866-216-1072,,345.67,Technology,53673.10
115 | 2025-08-30,GOOGLE NANO-BANANA ENTERPRISE,,2345.67,AI Services,51327.43
116 | 2025-08-31,SCHWAB MONEYLINK TRANSFER 8457,,5000.00,Savings,46327.43
117 | 2025-08-31,AMAZON.COM*FINAL8 AMZN.COM/BILL,,1234.56,Miscellaneous,45092.87
118 | 2025-08-31,OPENAI MONTHLY INVOICE AUG-2025,,3456.78,AI Services,41636.09


--------------------------------------------------------------------------------
/example_input_files/cats.txt:
--------------------------------------------------------------------------------
1 | Build these three image prompts in parallel using Task:
2 | - "A cat sits on a chair"
3 | - "A cat sits on a chair rule of thirds"
4 | - "A cat sits on a chair rule of thirds, with strong sunlight beaming on from blurry 


--------------------------------------------------------------------------------
/example_input_files/cats_edit.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "edit_image": "./edit_image_input_files/cat_sitting_in_chair.jpg",
 3 |   "prompts": [
 4 |     "Change the fur of the cat to black",
 5 |     "Change the fur of the cat to orange",
 6 |     "Change the fur of the cat to gray",
 7 |     "Change the fur of the cat to yellow",
 8 |     "Change the fur of the cat to blue"
 9 |   ]
10 | }
11 | 


--------------------------------------------------------------------------------
/example_input_files/cats_enhanced.txt:
--------------------------------------------------------------------------------
 1 | Build these ten image prompts in parallel using Task:
 2 | - "A cat sits on a chair"
 3 | - "A cat sits on a chair rule of thirds"
 4 | - "A cat sits on a chair rule of thirds, with strong sunlight beaming on from blurry window"
 5 | - "A fluffy orange cat curled up on a windowsill, sunlight streaming in"
 6 | - "A black cat with green eyes perched on a bookshelf surrounded by plants"
 7 | - "A kitten playing with a ball of yarn on a wooden floor"
 8 | - "A cat looking out a rainy window, reflections on the glass"
 9 | - "A group of cats lounging in a sunbeam on a patterned rug"
10 | - "A white cat with blue eyes sitting in a field of wildflowers"
11 | - "A tabby cat stretching on a cozy blanket near a fireplace"


--------------------------------------------------------------------------------
/example_input_files/echo.txt:
--------------------------------------------------------------------------------
1 | Simple agentic drop zone test
2 | 


--------------------------------------------------------------------------------
/example_input_files/twitter_classification_dataset.csv:
--------------------------------------------------------------------------------
  1 | tweet_id,username,text,created_at,retweets,likes,replies,hashtags,sentiment,category
  2 | 1001,tech_enthusiast,"Just tried the new AI assistant and it's amazing! Revolutionary technology at work #AI #tech",2024-03-15T10:30:00Z,45,234,12,"#AI #tech",positive,technology
  3 | 1002,sports_fan,"Can't believe my team lost again. This season is a disaster #disappointed #sports",2024-03-15T11:15:00Z,8,67,23,"#disappointed #sports",negative,sports
  4 | 1003,foodie_lover,"Perfect morning with fresh coffee and croissants at my favorite cafe ☕",2024-03-15T08:45:00Z,12,156,5,,positive,lifestyle
  5 | 1004,news_reader,"Breaking: New climate policy announced by government officials today",2024-03-15T14:20:00Z,89,445,67,,neutral,politics
  6 | 1005,movie_buff,"Just watched the latest blockbuster. Average plot but great special effects #movies",2024-03-15T21:30:00Z,23,187,34,"#movies",neutral,entertainment
  7 | 1006,travel_explorer,"Missing those sunset views from my vacation in Bali. Can't wait to go back! #travel #bali",2024-03-15T16:45:00Z,34,289,18,"#travel #bali",positive,travel
  8 | 1007,student_life,"Finals week is killing me. Too much stress and not enough sleep #studentlife #stress",2024-03-15T02:15:00Z,156,892,78,"#studentlife #stress",negative,education
  9 | 1008,fitness_guru,"Completed my first marathon today! 26.2 miles of pure determination #marathon #fitness",2024-03-15T17:30:00Z,67,534,89,"#marathon #fitness",positive,sports
 10 | 1009,music_lover,"The concert last night was absolutely incredible. Best performance I've ever seen #music",2024-03-15T09:20:00Z,45,312,45,"#music",positive,entertainment
 11 | 1010,business_news,"Stock markets showing mixed signals today. Investors remain cautious #stocks #finance",2024-03-15T13:45:00Z,78,234,56,"#stocks #finance",neutral,business
 12 | 1011,weather_watcher,"Another rainy day in the city. When will spring finally arrive? #rain #weather",2024-03-15T07:30:00Z,12,89,23,"#rain #weather",negative,weather
 13 | 1012,pet_owner,"My dog learned a new trick today! So proud of my furry friend #dogs #pets",2024-03-15T15:20:00Z,23,178,12,"#dogs #pets",positive,lifestyle
 14 | 1013,game_streamer,"Streaming live on Twitch tonight. Come watch me fail at this new game #gaming #twitch",2024-03-15T19:45:00Z,34,267,45,"#gaming #twitch",neutral,entertainment
 15 | 1014,health_advocate,"Regular exercise and healthy eating are key to a long life #health #wellness",2024-03-15T12:30:00Z,56,389,34,"#health #wellness",positive,health
 16 | 1015,art_collector,"Visited the new art exhibition today. Some pieces were thought-provoking #art #culture",2024-03-15T16:15:00Z,18,145,28,"#art #culture",positive,culture
 17 | 1016,social_critic,"Social media is destroying real human connections. We need to disconnect more often",2024-03-15T20:30:00Z,234,567,123,,negative,technology
 18 | 1017,fashion_blogger,"Love this new sustainable fashion brand. Style and ethics can coexist #fashion #sustainable",2024-03-15T11:45:00Z,45,234,19,"#fashion #sustainable",positive,fashion
 19 | 1018,comedy_fan,"That comedy show had me laughing until my stomach hurt. Pure entertainment #comedy",2024-03-15T22:15:00Z,34,198,12,"#comedy",positive,entertainment
 20 | 1019,environmental_ist,"Climate change is real and we need action now. The planet cannot wait #climatechange",2024-03-15T14:45:00Z,123,678,89,"#climatechange",neutral,environment
 21 | 1020,photographer,"Golden hour photography session was perfect today. Nature never disappoints #photography",2024-03-15T18:30:00Z,67,445,34,"#photography",positive,art
 22 | 1021,chef_amateur,"Cooking disaster tonight. Smoke alarm was my timer again #cooking #fail",2024-03-15T19:20:00Z,89,356,67,"#cooking #fail",negative,lifestyle
 23 | 1022,book_reviewer,"Just finished reading this thriller. Couldn't put it down! #books #reading",2024-03-15T23:45:00Z,23,167,45,"#books #reading",positive,literature
 24 | 1023,crypto_trader,"Bitcoin is showing interesting patterns today. Market volatility continues #crypto #bitcoin",2024-03-15T10:15:00Z,67,234,78,"#crypto #bitcoin",neutral,finance
 25 | 1024,parent_blogger,"Kids said the funniest thing today. Parenthood is full of surprises #parenting #kids",2024-03-15T17:45:00Z,45,289,23,"#parenting #kids",positive,family
 26 | 1025,science_nerd,"New research on quantum computing published today. Fascinating possibilities ahead #science",2024-03-15T13:20:00Z,34,178,56,"#science",positive,science
 27 | 1026,car_enthusiast,"Test drove the new electric vehicle. Impressive acceleration and silent ride #cars #electric",2024-03-15T16:30:00Z,56,323,34,"#cars #electric",positive,automotive
 28 | 1027,gardener_home,"Spring planting season has begun! Excited to see my garden bloom #gardening #spring",2024-03-15T09:15:00Z,23,145,18,"#gardening #spring",positive,lifestyle
 29 | 1028,political_pundit,"Recent policy changes raise important questions about future direction #politics #policy",2024-03-15T15:45:00Z,145,423,234,"#politics #policy",neutral,politics
 30 | 1029,coffee_addict,"Third cup of coffee today and it's only noon. No regrets #coffee #caffeine",2024-03-15T12:00:00Z,78,267,45,"#coffee #caffeine",neutral,lifestyle
 31 | 1030,dance_instructor,"Teaching new choreography to my students today. Movement is pure joy #dance #teaching",2024-03-15T18:15:00Z,34,198,23,"#dance #teaching",positive,arts
 32 | 1031,startup_founder,"Another late night at the office building our dream. Entrepreneurship is tough #startup",2024-03-15T01:30:00Z,67,345,67,"#startup",neutral,business
 33 | 1032,history_buff,"Learning about ancient civilizations never gets old. History repeats itself #history",2024-03-15T14:20:00Z,23,134,34,"#history",positive,education
 34 | 1033,yoga_practitioner,"Morning yoga session brought peace to my chaotic day #yoga #mindfulness",2024-03-15T07:45:00Z,45,234,18,"#yoga #mindfulness",positive,wellness
 35 | 1034,news_anchor,"Reporting on today's breaking news. Stay informed and stay safe everyone",2024-03-15T18:00:00Z,234,567,123,,neutral,news
 36 | 1035,volunteer_worker,"Spent the day helping at the local food bank. Community service fills the heart #volunteer",2024-03-15T16:45:00Z,56,389,45,"#volunteer",positive,community
 37 | 1036,language_learner,"Practicing Spanish every day is paying off. ¡Hablo español mejor ahora! #language #spanish",2024-03-15T20:15:00Z,34,178,28,"#language #spanish",positive,education
 38 | 1037,real_estate_agent,"Housing market showing signs of stabilization after months of volatility #realestate",2024-03-15T11:30:00Z,78,267,56,"#realestate",neutral,business
 39 | 1038,makeup_artist,"Created a stunning look for today's photoshoot. Artistry meets beauty #makeup #beauty",2024-03-15T13:45:00Z,67,345,34,"#makeup #beauty",positive,beauty
 40 | 1039,outdoor_adventurer,"Hiking trail was challenging but the summit view was worth every step #hiking #nature",2024-03-15T17:20:00Z,89,456,67,"#hiking #nature",positive,outdoor
 41 | 1040,mental_health_advocate,"Taking care of your mental health is just as important as physical health #mentalhealth",2024-03-15T10:45:00Z,145,678,89,"#mentalhealth",positive,health
 42 | 1041,tech_reviewer,"Latest smartphone release underwhelming. Innovation seems to be slowing down #tech #smartphone",2024-03-15T14:15:00Z,123,445,178,"#tech #smartphone",negative,technology
 43 | 1042,baker_professional,"Fresh bread aroma filling the bakery this morning. Nothing beats homemade #baking #bread",2024-03-15T06:30:00Z,34,234,23,"#baking #bread",positive,food
 44 | 1043,podcast_host,"Great conversation with today's guest about future of work. Episode drops tomorrow #podcast",2024-03-15T21:45:00Z,67,289,45,"#podcast",positive,media
 45 | 1044,wedding_planner,"Beautiful ceremony today despite the unexpected rain. Love conquers all weather #wedding",2024-03-15T19:30,56,378,34,"#wedding",positive,events
 46 | 1045,economist_analyst,"Inflation rates showing concerning trends. Economic indicators need careful monitoring #economics",2024-03-15T12:45:00Z,89,234,67,"#economics",negative,finance
 47 | 1046,sleep_researcher,"Study shows importance of 8 hours sleep for cognitive function. Rest is productivity #sleep #health",2024-03-15T08:20:00Z,78,345,56,"#sleep #health",positive,health
 48 | 1047,urban_planner,"New city development project aims to create more green spaces for residents #urbanplanning",2024-03-15T15:30:00Z,45,198,67,"#urbanplanning",positive,community
 49 | 1048,wine_sommelier,"Tasting notes from today's vineyard visit. Exceptional vintage with complex flavors #wine #tasting",2024-03-15T18:45,23,167,12,"#wine #tasting",positive,food
 50 | 1049,cybersecurity_expert,"Recent data breach highlights importance of strong password practices #cybersecurity #privacy",2024-03-15T11:15:00Z,156,567,234,"#cybersecurity #privacy",neutral,technology
 51 | 1050,marine_biologist,"Ocean research expedition revealed fascinating deep-sea creatures today #marine #science",2024-03-15T16:20:00Z,67,389,45,"#marine #science",positive,science
 52 | 1051,delivery_driver,"Traffic was brutal today but all packages delivered on time #delivery #work",2024-03-15T17:45:00Z,23,134,18,"#delivery #work",neutral,work
 53 | 1052,interior_designer,"Completed room makeover exceeds client expectations. Design transforms spaces #interior #design",2024-03-15T14:30:00Z,45,267,34,"#interior #design",positive,design
 54 | 1053,stand_up_comedian,"Bombing on stage teaches you more than killing. Every performance is learning #comedy #standup",2024-03-15T23:15:00Z,78,234,56,"#comedy #standup",neutral,entertainment
 55 | 1054,nutrition_coach,"Meal prep Sunday sets the tone for healthy eating all week #nutrition #mealprep",2024-03-15T19:00:00Z,56,323,23,"#nutrition #mealprep",positive,health
 56 | 1055,antique_collector,"Found rare vintage item at estate sale today. Historical treasures still exist #antiques #vintage",2024-03-15T13:15:00Z,34,178,28,"#antiques #vintage",positive,collecting
 57 | 1056,emergency_responder,"Another long shift but grateful to help those in need #emt #firstresponder",2024-03-15T06:45:00Z,89,456,67,"#emt #firstresponder",positive,service
 58 | 1057,drone_operator,"Aerial photography session captured stunning landscape views today #drone #photography",2024-03-15T16:30:00Z,45,234,34,"#drone #photography",positive,technology
 59 | 1058,retirement_planner,"Starting early with retirement savings pays compound interest dividends #retirement #finance",2024-03-15T10:30:00Z,67,289,45,"#retirement #finance",positive,finance
 60 | 1059,theater_director,"Rehearsals are intense but opening night will be magical #theater #drama",2024-03-15T20:45:00Z,23,167,56,"#theater #drama",positive,arts
 61 | 1060,climate_scientist,"New data confirms accelerating ice sheet melting patterns. Urgent action needed #climate #science",2024-03-15T12:20:00Z,234,678,145,"#climate #science",negative,environment
 62 | 1061,bartender_craft,"Created new cocktail recipe tonight. Customers love experimental flavors #cocktails #bartending",2024-03-15T22:30,34,198,23,"#cocktails #bartending",positive,food
 63 | 1062,solar_installer,"Renewable energy adoption growing rapidly. Clean power future looks bright #solar #renewable",2024-03-15T14:45:00Z,78,345,67,"#solar #renewable",positive,environment
 64 | 1063,voice_actor,"Recording session for animation project was challenging but fun #voiceacting #animation",2024-03-15T18:20:00Z,45,234,34,"#voiceacting #animation",positive,entertainment
 65 | 1064,tax_preparer,"Tax season stress levels reaching maximum capacity. April deadline approaches #taxes #accounting",2024-03-15T21:15:00Z,123,367,89,"#taxes #accounting",negative,finance
 66 | 1065,furniture_maker,"Handcrafted dining table completed after weeks of meticulous work #woodworking #craftsmanship",2024-03-15T15:45:00Z,56,289,23,"#woodworking #craftsmanship",positive,crafts
 67 | 1066,sports_journalist,"Championship game analysis reveals strategic coaching decisions #sports #journalism",2024-03-15T11:30:00Z,89,234,78,"#sports #journalism",neutral,sports
 68 | 1067,flight_attendant,"Turbulence made service challenging but passengers remained calm #aviation #travel",2024-03-15T09:45:00Z,34,167,45,"#aviation #travel",neutral,travel
 69 | 1068,insurance_agent,"Helping families protect their financial future through proper coverage #insurance #family",2024-03-15T13:30:00Z,23,134,34,"#insurance #family",positive,finance
 70 | 1069,landscape_architect,"New public park design incorporates native plants and sustainable drainage #landscape #sustainability",2024-03-15T16:15:00Z,67,323,56,"#landscape #sustainability",positive,environment
 71 | 1070,food_critic,"Restaurant review: Exceptional service but disappointing main courses #food #restaurant",2024-03-15T20:00:00Z,78,245,67,"#food #restaurant",negative,food
 72 | 1071,physical_therapist,"Patient progress in recovery brings joy to this challenging profession #physicaltherapy #healthcare",2024-03-15T08:30:00Z,45,234,23,"#physicaltherapy #healthcare",positive,healthcare
 73 | 1072,cryptocurrency_miner,"Mining rig efficiency improved with new cooling system upgrade #crypto #mining",2024-03-15T17:30:00Z,56,178,78,"#crypto #mining",positive,technology
 74 | 1073,event_coordinator,"Wedding planning stress worth it when seeing couple's happiness #wedding #events",2024-03-15T19:15:00Z,67,356,34,"#wedding #events",positive,events
 75 | 1074,mechanical_engineer,"New engine design shows 15% efficiency improvement in testing phase #engineering #innovation",2024-03-15T14:00:00Z,34,167,45,"#engineering #innovation",positive,engineering
 76 | 1075,librarian_public,"Quiet day at library but helped several patrons find perfect books #library #books",2024-03-15T12:15:00Z,23,145,18,"#library #books",positive,education
 77 | 1076,fire_chief,"Fire prevention education program launches in local schools next week #fire #safety",2024-03-15T10:00:00Z,89,367,67,"#fire #safety",positive,safety
 78 | 1077,graphic_designer,"Logo design process requires balancing creativity with client brand vision #design #branding",2024-03-15T15:20:00Z,45,234,56,"#design #branding",neutral,design
 79 | 1078,professional_organizer,"Decluttered home office increases productivity and reduces stress levels #organization #productivity",2024-03-15T11:45:00Z,67,289,34,"#organization #productivity",positive,lifestyle
 80 | 1079,meteorologist_local,"Severe weather warning issued for tomorrow evening. Stay safe everyone #weather #safety",2024-03-15T18:45,123,456,89,"#weather #safety",neutral,weather
 81 | 1080,horse_trainer,"Young horse showing excellent progress in training sessions #horses #training",2024-03-15T07:20:00Z,34,178,23,"#horses #training",positive,animals
 82 | 1081,data_analyst,"Customer behavior patterns reveal interesting seasonal shopping trends #data #analytics",2024-03-15T13:45:00Z,78,234,67,"#data #analytics",neutral,business
 83 | 1082,massage_therapist,"Stress relief through therapeutic massage helps clients find balance #massage #wellness",2024-03-15T16:45:00Z,45,267,34,"#massage #wellness",positive,wellness
 84 | 1083,film_editor,"Post-production magic transforms raw footage into compelling storytelling #film #editing",2024-03-15T22:00:00Z,56,234,45,"#film #editing",positive,entertainment
 85 | 1084,pest_control_technician,"Ant invasion eliminated using environmentally safe treatment methods #pestcontrol #environment",2024-03-15T09:30:00Z,23,134,28,"#pestcontrol #environment",positive,service
 86 | 1085,jewelry_designer,"Custom engagement ring design brings couple's vision to sparkling reality #jewelry #design",2024-03-15T14:20:00Z,67,345,23,"#jewelry #design",positive,crafts
 87 | 1086,truck_driver_long_haul,"Cross-country delivery completed safely despite challenging weather conditions #trucking #delivery",2024-03-15T05:45:00Z,34,167,45,"#trucking #delivery",positive,transportation
 88 | 1087,swim_instructor,"Teaching children water safety while making lessons fun and engaging #swimming #safety",2024-03-15T17:00:00Z,45,234,34,"#swimming #safety",positive,education
 89 | 1088,optometrist_practice,"Regular eye exams detect problems early and preserve precious vision #eyecare #health",2024-03-15T11:20:00Z,56,189,23,"#eyecare #health",positive,healthcare
 90 | 1089,street_performer,"Busking downtown brings music to busy commuters during rush hour #music #street",2024-03-15T18:30,78,267,56,"#music #street",positive,entertainment
 91 | 1090,hvac_technician,"Air conditioning repair completed just before summer heat wave arrives #hvac #repair",2024-03-15T13:15:00Z,23,134,18,"#hvac #repair",positive,service
 92 | 1091,florist_wedding,"Bridal bouquet arrangement combines elegant roses with seasonal wildflowers #flowers #wedding",2024-03-15T10:45:00Z,67,323,45,"#flowers #wedding",positive,events
 93 | 1092,security_guard_night,"Quiet shift at office building but vigilance never wavers #security #safety",2024-03-15T03:30:00Z,12,89,23,"#security #safety",neutral,security
 94 | 1093,dog_groomer_professional,"Pampered poodle transformation from shaggy to fabulous complete #dogs #grooming",2024-03-15T15:30:00Z,89,456,34,"#dogs #grooming",positive,pets
 95 | 1094,electrician_residential,"Home rewiring project enhances safety and increases property value #electrical #home",2024-03-15T12:45:00Z,34,178,56,"#electrical #home",positive,service
 96 | 1095,tattoo_artist_custom,"Memorial tattoo honors client's beloved grandmother with meaningful symbolism #tattoo #memorial",2024-03-15T19:45:00Z,56,289,67,"#tattoo #memorial",positive,art
 97 | 1096,plumber_emergency,"Burst pipe repair prevented major water damage to family home #plumbing #emergency",2024-03-15T07:15:00Z,45,234,23,"#plumbing #emergency",positive,service
 98 | 1097,carpenter_finish,"Custom kitchen cabinets installation transforms cooking space into chef's paradise #carpentry #kitchen",2024-03-15T16:00:00Z,67,345,45,"#carpentry #kitchen",positive,home
 99 | 1098,locksmith_24hour,"Locked out customer grateful for quick response during midnight emergency #locksmith #service",2024-03-15T01:20:00Z,23,134,18,"#locksmith #service",positive,service
100 | 1099,window_cleaner_commercial,"Skyscraper window cleaning requires courage and precision at great heights #windows #cleaning",2024-03-15T08:45:00Z,78,234,34,"#windows #cleaning",neutral,service
101 | 1100,appliance_repair_tech,"Washing machine resurrection saves family from laundromat expenses #appliance #repair",2024-03-15T14:30:00Z,34,167,28,"#appliance #repair",positive,service


--------------------------------------------------------------------------------
/example_input_files/yt_script_5_agent_interaction_patterns_4m.mp4:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/disler/agentic-drop-zones/16a347bf60afcb60a1c55893deb5859aaeb18dda/example_input_files/yt_script_5_agent_interaction_patterns_4m.mp4


--------------------------------------------------------------------------------
/images/arch.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/disler/agentic-drop-zones/16a347bf60afcb60a1c55893deb5859aaeb18dda/images/arch.png


--------------------------------------------------------------------------------
/sfs_agentic_drop_zone.py:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/env python3
  2 | # /// script
  3 | # requires-python = ">=3.11"
  4 | # dependencies = [
  5 | #     "claude-code-sdk",
  6 | #     "pydantic",
  7 | #     "watchdog",
  8 | #     "pyyaml",
  9 | #     "python-dotenv",
 10 | #     "rich",
 11 | # ]
 12 | # ///
 13 | 
 14 | """Agentic Drop Zone - File monitoring and processing system."""
 15 | 
 16 | import asyncio
 17 | import logging
 18 | import os
 19 | import yaml
 20 | from enum import Enum
 21 | from pathlib import Path
 22 | from typing import Any, Optional, Literal
 23 | 
 24 | from dotenv import load_dotenv
 25 | from pydantic import BaseModel, Field, field_validator
 26 | from rich.console import Console
 27 | from rich.live import Live
 28 | from rich.panel import Panel
 29 | from rich.text import Text
 30 | from watchdog.observers import Observer
 31 | from watchdog.events import (
 32 |     FileSystemEventHandler,
 33 |     FileSystemEvent,
 34 |     EVENT_TYPE_CREATED,
 35 |     EVENT_TYPE_MODIFIED,
 36 |     EVENT_TYPE_DELETED,
 37 |     EVENT_TYPE_MOVED,
 38 | )
 39 | from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions
 40 | 
 41 | # Load environment variables
 42 | load_dotenv()
 43 | 
 44 | # Constants
 45 | FILE_PATH_PLACEHOLDER = "[[FILE_PATH]]"
 46 | 
 47 | 
 48 | # Environment variable checks
 49 | def check_environment_variables():
 50 |     """Check for required environment variables at startup."""
 51 |     required_vars = {
 52 |         "ANTHROPIC_API_KEY": "Required for Claude Code SDK authentication",
 53 |         "CLAUDE_CODE_PATH": "Required path to Claude CLI executable",
 54 |     }
 55 | 
 56 |     optional_vars = {
 57 |         "REPLICATE_API_TOKEN": "Optional - needed for image generation/editing (won't be able to generate images without it)"
 58 |     }
 59 | 
 60 |     missing_required = []
 61 | 
 62 |     # Check required variables
 63 |     for var, description in required_vars.items():
 64 |         if not os.getenv(var):
 65 |             missing_required.append(f"  - {var}: {description}")
 66 | 
 67 |     # Display missing required variables
 68 |     if missing_required:
 69 |         console.print("[bold red]❌ Missing required environment variables:[/bold red]")
 70 |         for item in missing_required:
 71 |             console.print(f"[red]{item}[/red]")
 72 |         console.print(
 73 |             "\n[yellow]Please set these in your .env file or environment[/yellow]"
 74 |         )
 75 |         raise EnvironmentError("Missing required environment variables")
 76 | 
 77 |     # Check optional variables and display warnings
 78 |     missing_optional = []
 79 |     for var, description in optional_vars.items():
 80 |         if not os.getenv(var):
 81 |             missing_optional.append(f"  - {var}: {description}")
 82 | 
 83 |     if missing_optional:
 84 |         console.print("[yellow]⚠️  Optional environment variables not set:[/yellow]")
 85 |         for item in missing_optional:
 86 |             console.print(f"[dim]{item}[/dim]")
 87 |         console.print()
 88 | 
 89 |     console.print("[green]✅ All required environment variables are set[/green]")
 90 | 
 91 | 
 92 | # Configure logging
 93 | logging.basicConfig(
 94 |     level=logging.INFO, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
 95 | )
 96 | logger = logging.getLogger(__name__)
 97 | 
 98 | # Initialize Rich console
 99 | console = Console()
100 | 
101 | 
102 | class EventType(str, Enum):
103 |     """Supported file system event types."""
104 | 
105 |     CREATED = "created"
106 |     MODIFIED = "modified"
107 |     DELETED = "deleted"
108 |     MOVED = "moved"
109 | 
110 | 
111 | class AgentType(str, Enum):
112 |     """Supported agent types."""
113 | 
114 |     CLAUDE_CODE = "claude_code"
115 |     GEMINI_CLI = "gemini_cli"
116 |     CODEX_CLI = "codex_cli"
117 | 
118 | 
119 | class PromptArgs(BaseModel):
120 |     """Arguments for prompt processing."""
121 | 
122 |     reusable_prompt: str = Field(description="Path to the reusable prompt file")
123 |     file_path: str = Field(description="Path to the file being processed")
124 |     model: Optional[str] = Field(
125 |         default=None, description="Model to use for processing"
126 |     )
127 |     mcp_server_file: Optional[str] = Field(
128 |         default=None, description="Path to MCP server configuration file (JSON or YAML)"
129 |     )
130 |     zone_name: Optional[str] = Field(default=None, description="Name of the drop zone")
131 |     zone_color: Optional[str] = Field(
132 |         default="cyan", description="Color for the drop zone"
133 |     )
134 | 
135 | 
136 | class DropZone(BaseModel):
137 |     """Configuration for a single drop zone."""
138 | 
139 |     name: str = Field(description="Name of the drop zone")
140 |     file_patterns: list[str] = Field(description="File patterns to watch (e.g., *.txt)")
141 |     reusable_prompt: str = Field(
142 |         description="Path to the reusable prompt file (e.g., .claude/commands/echo.md)"
143 |     )
144 |     zone_dirs: list[str] = Field(
145 |         description="List of directories to monitor (supports * wildcard)"
146 |     )
147 |     events: list[EventType] = Field(
148 |         default=[EventType.CREATED], description="Event types to respond to"
149 |     )
150 |     agent: AgentType = Field(
151 |         default=AgentType.CLAUDE_CODE, description="Agent type to use for processing"
152 |     )
153 |     model: Optional[str] = Field(
154 |         default="sonnet",
155 |         description="Model to use for Claude Code (e.g., 'sonnet', 'opus', 'haiku')",
156 |     )
157 |     mcp_server_file: Optional[str] = Field(
158 |         default=None, description="Path to MCP server configuration file (JSON or YAML)"
159 |     )
160 |     color: Optional[str] = Field(
161 |         default="cyan",
162 |         description="Color for console output (e.g., 'red', 'blue', 'green', 'cyan', 'yellow', 'magenta')",
163 |     )
164 |     create_zone_dir_if_not_exists: bool = Field(
165 |         default=False,
166 |         description="Create zone directory if it doesn't exist (non-glob patterns only)",
167 |     )
168 | 
169 |     @field_validator("zone_dirs")
170 |     @classmethod
171 |     def validate_zone_dirs(cls, v: list[str]) -> list[str]:
172 |         if not v:
173 |             raise ValueError("zone_dirs must contain at least one directory")
174 |         return v
175 | 
176 |     @field_validator("events")
177 |     @classmethod
178 |     def validate_events(cls, v: list[EventType]) -> list[EventType]:
179 |         if not v:
180 |             raise ValueError("events must contain at least one event type")
181 |         return v
182 | 
183 | 
184 | class DropsConfig(BaseModel):
185 |     """Root configuration for all drop zones."""
186 | 
187 |     drop_zones: list[DropZone] = Field(description="List of configured drop zones")
188 | 
189 | 
190 | class Agents:
191 |     """Agent implementations for processing drop zone files."""
192 | 
193 |     @staticmethod
194 |     def build_prompt(reusable_prompt_path: str, file_path: str) -> str:
195 |         """Build the full prompt by loading from file and replacing variables.
196 | 
197 |         Args:
198 |             reusable_prompt_path: Path to the prompt file
199 |             file_path: Path to the dropped file being processed
200 | 
201 |         Returns:
202 |             The constructed prompt with variables replaced
203 | 
204 |         Raises:
205 |             FileNotFoundError: If the prompt file doesn't exist
206 |             Exception: If unable to read the prompt file
207 |         """
208 |         prompt_path = Path(reusable_prompt_path)
209 | 
210 |         # Ensure prompt file exists
211 |         if not prompt_path.exists():
212 |             error_msg = f"Reusable prompt file not found: {reusable_prompt_path}"
213 |             console.print(f"[bold red]❌ {error_msg}[/bold red]")
214 |             raise FileNotFoundError(error_msg)
215 | 
216 |         if not prompt_path.is_file():
217 |             error_msg = f"Reusable prompt path is not a file: {reusable_prompt_path}"
218 |             console.print(f"[bold red]❌ {error_msg}[/bold red]")
219 |             raise ValueError(error_msg)
220 | 
221 |         # Load prompt from file
222 |         console.print(f"[dim]   Loading prompt: {reusable_prompt_path}[/dim]")
223 |         try:
224 |             prompt_content = prompt_path.read_text()
225 |         except Exception as e:
226 |             error_msg = f"Failed to read prompt file {reusable_prompt_path}: {e}"
227 |             console.print(f"[bold red]❌ {error_msg}[/bold red]")
228 |             raise Exception(error_msg) from e
229 | 
230 |         # Replace FILE_PATH_PLACEHOLDER with actual file path
231 |         if FILE_PATH_PLACEHOLDER in prompt_content:
232 |             prompt_content = prompt_content.replace(FILE_PATH_PLACEHOLDER, file_path)
233 | 
234 |         return prompt_content
235 | 
236 |     @staticmethod
237 |     async def prompt_claude_code(args: PromptArgs) -> None:
238 |         """Process a file using Claude Code SDK."""
239 |         # Build full prompt using the build_prompt method
240 |         full_prompt = Agents.build_prompt(args.reusable_prompt, args.file_path)
241 | 
242 |         console.print(f"[cyan]ℹ️  Processing prompt with Claude Code...[/cyan]")
243 |         if args.model:
244 |             console.print(f"[dim]   Model: {args.model}[/dim]")
245 | 
246 |         # Get CLI path from environment or use default
247 |         cli_path = os.getenv("CLAUDE_CODE_PATH", "claude")
248 | 
249 |         # If a custom path is set, update PATH environment variable
250 |         if cli_path != "claude":
251 |             # Extract directory from the CLI path
252 |             cli_dir = os.path.dirname(cli_path) if os.path.dirname(cli_path) else "."
253 |             current_path = os.environ.get("PATH", "")
254 |             if cli_dir not in current_path:
255 |                 os.environ["PATH"] = f"{cli_dir}:{current_path}"
256 | 
257 |         # Create options with bypassPermissions mode and optional model
258 |         options_dict = {
259 |             "permission_mode": "bypassPermissions"  # Bypass all permission prompts
260 |         }
261 | 
262 |         # Add model if specified
263 |         if args.model:
264 |             # Try the model value as-is first, if it fails, try with claude- prefix
265 |             options_dict["model"] = args.model
266 | 
267 |         # Add MCP server file if specified
268 |         if args.mcp_server_file:
269 |             # Claude SDK accepts file paths directly and will handle loading
270 |             options_dict["mcp_servers"] = args.mcp_server_file
271 |             console.print(f"[dim]   MCP config: {args.mcp_server_file}[/dim]")
272 | 
273 |         options = ClaudeCodeOptions(**options_dict)
274 | 
275 |         # Minimal Claude Code setup - let errors propagate
276 |         async with ClaudeSDKClient(options=options) as client:
277 |             await client.query(full_prompt)
278 | 
279 |             # Stream response - output panels as content arrives
280 |             file_name = Path(args.file_path).name
281 |             has_response = False
282 |             zone_workflow = (
283 |                 f"{args.zone_name} Workflow" if args.zone_name else "Workflow"
284 |             )
285 |             panel_color = args.zone_color or "cyan"
286 | 
287 |             async for message in client.receive_response():
288 |                 if hasattr(message, "content"):
289 |                     for block in message.content:
290 |                         if hasattr(block, "text") and block.text.strip():
291 |                             has_response = True
292 |                             # Output each text block in its own panel
293 |                             console.print(
294 |                                 Panel(
295 |                                     Text(block.text),
296 |                                     title=f"[bold {panel_color}]🤖 Claude Code • {zone_workflow}[/bold {panel_color}]",
297 |                                     subtitle=f"[dim]{file_name}[/dim]",
298 |                                     border_style=panel_color,
299 |                                     expand=False,
300 |                                     padding=(1, 2),
301 |                                 )
302 |                             )
303 | 
304 |             # If no response was received
305 |             if not has_response:
306 |                 console.print(
307 |                     Panel(
308 |                         Text("[yellow]No response received[/yellow]"),
309 |                         title=f"[bold yellow]🤖 Claude Code • {zone_workflow}[/bold yellow]",
310 |                         subtitle=f"[dim]{file_name}[/dim]",
311 |                         border_style="yellow",
312 |                         expand=False,
313 |                         padding=(1, 2),
314 |                     )
315 |                 )
316 | 
317 |             console.print()
318 | 
319 |     @staticmethod
320 |     async def prompt_gemini_cli(args: PromptArgs) -> None:
321 |         """Process a file using Gemini CLI."""
322 |         # Build full prompt using the build_prompt method
323 |         full_prompt = Agents.build_prompt(args.reusable_prompt, args.file_path)
324 | 
325 |         console.print(f"[green]ℹ️  Processing prompt with Gemini CLI...[/green]")
326 |         if args.model:
327 |             console.print(f"[dim]   Model: {args.model}[/dim]")
328 | 
329 |         # Get CLI path from environment or use default
330 |         gemini_path = os.getenv("GEMINI_CLI_PATH", "gemini")
331 | 
332 |         # Build command with flags
333 |         cmd = [
334 |             gemini_path,
335 |             "--yolo",      # Auto-approve all tool calls
336 |             "--sandbox",   # Enable sandboxing by default
337 |             "-m", args.model or "gemini-2.5-pro",  # Model
338 |             "-p", full_prompt  # Non-interactive prompt
339 |         ]
340 | 
341 |         console.print(f"[dim]   Command: {' '.join(cmd[:4])}...[/dim]")
342 | 
343 |         try:
344 |             # Create subprocess with asyncio
345 |             process = await asyncio.create_subprocess_exec(
346 |                 *cmd,
347 |                 stdout=asyncio.subprocess.PIPE,
348 |                 stderr=asyncio.subprocess.PIPE,
349 |                 env=os.environ.copy()  # Pass environment variables
350 |             )
351 | 
352 |             # Prepare for streaming display
353 |             file_name = Path(args.file_path).name
354 |             zone_workflow = (
355 |                 f"{args.zone_name} Workflow" if args.zone_name else "Workflow"
356 |             )
357 |             panel_color = args.zone_color or "green"
358 |             has_output = False
359 | 
360 |             async def read_stream(stream, is_stderr=False):
361 |                 """Read and display stream output line by line."""
362 |                 nonlocal has_output
363 |                 while True:
364 |                     line = await stream.readline()
365 |                     if not line:
366 |                         break
367 |                     
368 |                     decoded = line.decode('utf-8', errors='replace').rstrip()
369 |                     if decoded:  # Only process non-empty lines
370 |                         has_output = True
371 |                         # Print each line in its own panel
372 |                         console.print(
373 |                             Panel(
374 |                                 Text(decoded),
375 |                                 title=f"[bold {panel_color}]🤖 Gemini CLI • {zone_workflow}[/bold {panel_color}]",
376 |                                 subtitle=f"[dim]{file_name}[/dim]",
377 |                                 border_style=panel_color,
378 |                                 expand=False,
379 |                                 padding=(1, 2),
380 |                             )
381 |                         )
382 | 
383 |             # Handle both streams concurrently
384 |             await asyncio.gather(
385 |                 read_stream(process.stdout, is_stderr=False),
386 |                 read_stream(process.stderr, is_stderr=True)
387 |             )
388 | 
389 |             # Wait for process to complete
390 |             return_code = await process.wait()
391 |             
392 |             # Print completion status if needed
393 |             if return_code != 0:
394 |                 console.print(
395 |                     f"\n[yellow]⚠️ Process exited with code {return_code}[/yellow]"
396 |                 )
397 |             
398 |             # If no output was received, show a message
399 |             if not has_output:
400 |                 console.print(
401 |                     Panel(
402 |                         "[yellow]No output received[/yellow]",
403 |                         title=f"[bold yellow]🤖 Gemini CLI • {zone_workflow}[/bold yellow]",
404 |                         subtitle=f"[dim]{file_name}[/dim]",
405 |                         border_style="yellow",
406 |                         expand=False,
407 |                         padding=(1, 2),
408 |                     )
409 |                 )
410 | 
411 |         except FileNotFoundError:
412 |             console.print(
413 |                 f"[bold red]❌ Gemini CLI not found at '{gemini_path}'[/bold red]"
414 |             )
415 |             console.print(
416 |                 "[yellow]Please install Gemini CLI: npm install -g @google/gemini-cli[/yellow]"
417 |             )
418 |             console.print(
419 |                 "[dim]Or set GEMINI_CLI_PATH environment variable to the correct path[/dim]"
420 |             )
421 |         except Exception as e:
422 |             console.print(f"[bold red]❌ Error running Gemini CLI: {e}[/bold red]")
423 | 
424 |         console.print()
425 | 
426 |     @staticmethod
427 |     async def prompt_codex_cli(args: PromptArgs) -> None:
428 |         """Process a file using Codex CLI."""
429 |         # Build full prompt using the build_prompt method
430 |         full_prompt = Agents.build_prompt(args.reusable_prompt, args.file_path)
431 | 
432 |         # TODO: Implement Codex CLI integration
433 |         raise NotImplementedError("Codex CLI agent not yet implemented")
434 | 
435 |     @staticmethod
436 |     async def process_with_agent(agent: AgentType, args: PromptArgs) -> None:
437 |         """Route to appropriate agent based on type."""
438 |         try:
439 |             if agent == AgentType.CLAUDE_CODE:
440 |                 await Agents.prompt_claude_code(args)
441 |             elif agent == AgentType.GEMINI_CLI:
442 |                 await Agents.prompt_gemini_cli(args)
443 |             elif agent == AgentType.CODEX_CLI:
444 |                 await Agents.prompt_codex_cli(args)
445 |             else:
446 |                 raise ValueError(f"Unknown agent type: {agent}")
447 |         except Exception as e:
448 |             console.print(f"[bold red]❌ Agent processing failed: {e}[/bold red]")
449 | 
450 | 
451 | class DropZoneHandler(FileSystemEventHandler):
452 |     """Handle file system events in the drop zone."""
453 | 
454 |     def __init__(self, drop_zone: DropZone):
455 |         self.drop_zone = drop_zone
456 |         super().__init__()
457 | 
458 |     def _should_process_event(self, event_type: str) -> bool:
459 |         """Check if this event type should be processed."""
460 |         event_map = {
461 |             EVENT_TYPE_CREATED: EventType.CREATED,
462 |             EVENT_TYPE_MODIFIED: EventType.MODIFIED,
463 |             EVENT_TYPE_DELETED: EventType.DELETED,
464 |             EVENT_TYPE_MOVED: EventType.MOVED,
465 |         }
466 |         return event_map.get(event_type) in self.drop_zone.events
467 | 
468 |     def on_created(self, event: FileSystemEvent) -> None:
469 |         """Handle file creation events."""
470 |         if not event.is_directory and self._should_process_event(EVENT_TYPE_CREATED):
471 |             console.print(f"[green]✨ File created: {event.src_path}[/green]")
472 |             self.process_file(event.src_path)
473 | 
474 |     def on_modified(self, event: FileSystemEvent) -> None:
475 |         """Handle file modification events."""
476 |         if not event.is_directory and self._should_process_event(EVENT_TYPE_MODIFIED):
477 |             console.print(f"[yellow]📝 File modified: {event.src_path}[/yellow]")
478 |             self.process_file(event.src_path)
479 | 
480 |     def on_deleted(self, event: FileSystemEvent) -> None:
481 |         """Handle file deletion events."""
482 |         if not event.is_directory and self._should_process_event(EVENT_TYPE_DELETED):
483 |             console.print(f"[red]🗑️  File deleted: {event.src_path}[/red]")
484 |             self.process_file(event.src_path)
485 | 
486 |     def on_moved(self, event: FileSystemEvent) -> None:
487 |         """Handle file move events."""
488 |         if not event.is_directory and self._should_process_event(EVENT_TYPE_MOVED):
489 |             console.print(
490 |                 f"[blue]📦 File moved: {event.src_path} -> {event.dest_path}[/blue]"
491 |             )
492 |             self.process_file(
493 |                 event.dest_path if hasattr(event, "dest_path") else event.src_path
494 |             )
495 | 
496 |     def process_file(self, file_path: str) -> None:
497 |         """Process a file that has been added or modified."""
498 |         path = Path(file_path)
499 | 
500 |         # Check if file matches any of the configured patterns
501 |         if not any(path.match(pattern) for pattern in self.drop_zone.file_patterns):
502 |             # Silent return - no need to log non-matching files
503 |             return
504 | 
505 |         zone_color = self.drop_zone.color or "green"
506 |         console.print(
507 |             f"\n[bold {zone_color}]📁 Drop Zone: {self.drop_zone.name}[/bold {zone_color}]"
508 |         )
509 |         console.print(f"[yellow]   File: {file_path}[/yellow]")
510 |         console.print(f"[dim]   Agent: {self.drop_zone.agent}[/dim]")
511 |         console.print(f"[dim]   Prompt: {self.drop_zone.reusable_prompt}[/dim]")
512 |         if self.drop_zone.model:
513 |             console.print(f"[dim]   Model: {self.drop_zone.model}[/dim]")
514 |         if self.drop_zone.mcp_server_file:
515 |             console.print(f"[dim]   MCP: {self.drop_zone.mcp_server_file}[/dim]")
516 | 
517 |         # Create PromptArgs
518 |         prompt_args = PromptArgs(
519 |             reusable_prompt=self.drop_zone.reusable_prompt,
520 |             file_path=file_path,
521 |             model=self.drop_zone.model,
522 |             mcp_server_file=self.drop_zone.mcp_server_file,
523 |             zone_name=self.drop_zone.name,
524 |             zone_color=self.drop_zone.color,
525 |         )
526 | 
527 |         # Run the agent in a new event loop since watchdog runs in a different thread
528 |         asyncio.run(Agents.process_with_agent(self.drop_zone.agent, prompt_args))
529 | 
530 | 
531 | class AgenticDropZone:
532 |     """Main application class for the Agentic Drop Zone."""
533 | 
534 |     def __init__(self, config_file: Path = Path("drops.yaml")):
535 |         self.config_file = config_file
536 |         self.config: Optional[DropsConfig] = None
537 |         self.observers: list[Observer] = []
538 |         self.base_path = Path.cwd()
539 | 
540 |     def load_config(self) -> None:
541 |         """Load configuration from YAML file."""
542 |         try:
543 |             if not self.config_file.exists():
544 |                 error_msg = f"Configuration file not found: {self.config_file}"
545 |                 console.print(f"[bold red]❌ {error_msg}[/bold red]")
546 |                 raise FileNotFoundError(error_msg)
547 | 
548 |             with open(self.config_file, "r") as f:
549 |                 data = yaml.safe_load(f)
550 | 
551 |             self.config = DropsConfig(**data)
552 |             console.print(
553 |                 f"[green]✅ Loaded configuration from {self.config_file}[/green]"
554 |             )
555 |             console.print(
556 |                 f"[cyan]   Found {len(self.config.drop_zones)} drop zone(s)[/cyan]"
557 |             )
558 |         except FileNotFoundError:
559 |             raise
560 |         except Exception as e:
561 |             console.print(f"[bold red]❌ Error loading configuration: {e}[/bold red]")
562 |             raise
563 | 
564 |     def _expand_zone_dirs(self, drop_zone: DropZone) -> list[Path]:
565 |         """Expand zone_dirs patterns to actual directories."""
566 |         expanded_dirs = []
567 | 
568 |         for zone_dir in drop_zone.zone_dirs:
569 |             if "*" in zone_dir:
570 |                 # Simple wildcard support - just use the pattern as-is
571 |                 matching_dirs = list(self.base_path.glob(zone_dir))
572 |                 # Filter to only directories
573 |                 matching_dirs = [d for d in matching_dirs if d.is_dir()]
574 |                 if matching_dirs:
575 |                     expanded_dirs.extend(matching_dirs)
576 |                     console.print(
577 |                         f"[dim]   Pattern '{zone_dir}' matched {len(matching_dirs)} directories: {[d.name for d in matching_dirs]}[/dim]"
578 |                     )
579 |                 else:
580 |                     console.print(
581 |                         f"[yellow]⚠️  Pattern '{zone_dir}' matched no directories[/yellow]"
582 |                     )
583 |             else:
584 |                 # Direct directory path (non-glob)
585 |                 dir_path = self.base_path / zone_dir
586 |                 if dir_path.exists() and dir_path.is_dir():
587 |                     expanded_dirs.append(dir_path)
588 |                 elif not dir_path.exists():
589 |                     # Directory doesn't exist
590 |                     if drop_zone.create_zone_dir_if_not_exists:
591 |                         # Create the directory
592 |                         try:
593 |                             dir_path.mkdir(parents=True, exist_ok=True)
594 |                             console.print(
595 |                                 f"[green]✅ Created zone directory: {dir_path}[/green]"
596 |                             )
597 |                             expanded_dirs.append(dir_path)
598 |                         except Exception as e:
599 |                             console.print(
600 |                                 f"[bold red]❌ Failed to create directory {dir_path}: {e}[/bold red]"
601 |                             )
602 |                     else:
603 |                         # Log error and ask user to create it
604 |                         console.print(
605 |                             f"[bold red]❌ Zone directory does not exist: {dir_path}[/bold red]"
606 |                         )
607 |                         console.print(
608 |                             f"[yellow]   Please create the directory manually: mkdir -p {dir_path}[/yellow]"
609 |                         )
610 |                         console.print(
611 |                             f"[dim]   Or set 'create_zone_dir_if_not_exists: true' in drops.yaml for zone '{drop_zone.name}'[/dim]"
612 |                         )
613 |                 else:
614 |                     console.print(
615 |                         f"[yellow]⚠️  Path exists but is not a directory: {dir_path}[/yellow]"
616 |                     )
617 | 
618 |         return expanded_dirs
619 | 
620 |     def start(self) -> None:
621 |         """Start monitoring all configured drop zones."""
622 |         if not self.config:
623 |             raise RuntimeError("Configuration not loaded. Call load_config() first.")
624 | 
625 |         for drop_zone in self.config.drop_zones:
626 |             # Expand zone_dirs patterns
627 |             zone_paths = self._expand_zone_dirs(drop_zone)
628 | 
629 |             if not zone_paths:
630 |                 console.print(
631 |                     f"[yellow]⚠️  No valid directories found for drop zone '{drop_zone.name}'[/yellow]"
632 |                 )
633 |                 continue
634 | 
635 |             # Create observer for each directory
636 |             for zone_path in zone_paths:
637 |                 observer = Observer()
638 |                 handler = DropZoneHandler(drop_zone)
639 | 
640 |                 # Schedule non-recursive watching
641 |                 observer.schedule(handler, str(zone_path), recursive=False)
642 |                 observer.start()
643 |                 self.observers.append(observer)
644 | 
645 |                 zone_color = drop_zone.color or "green"
646 |                 console.print(
647 |                     f"\n[bold {zone_color}]✅ Started monitoring drop zone: {drop_zone.name}[/bold {zone_color}]"
648 |                 )
649 |                 console.print(f"[cyan]   📂 Path: {zone_path}[/cyan]")
650 |                 console.print(f"[dim]   - Patterns: {drop_zone.file_patterns}[/dim]")
651 |                 console.print(
652 |                     f"[dim]   - Events: {[e.value for e in drop_zone.events]}[/dim]"
653 |                 )
654 |                 console.print(f"[dim]   - Prompt: {drop_zone.reusable_prompt}[/dim]")
655 |                 if drop_zone.model:
656 |                     console.print(f"[dim]   - Model: {drop_zone.model}[/dim]")
657 |                 if drop_zone.mcp_server_file:
658 |                     console.print(f"[dim]   - MCP: {drop_zone.mcp_server_file}[/dim]")
659 | 
660 |         if self.observers:
661 |             console.print(
662 |                 f"\n[bold cyan]🎯 Total observers started: {len(self.observers)}[/bold cyan]"
663 |             )
664 |             console.print("[dim]Press Ctrl+C to stop...[/dim]\n")
665 |         else:
666 |             console.print(
667 |                 "[bold red]⚠️ No observers started. Check your configuration.[/bold red]"
668 |             )
669 | 
670 |     def stop(self) -> None:
671 |         """Stop monitoring all drop zones."""
672 |         for observer in self.observers:
673 |             observer.stop()
674 | 
675 |         for observer in self.observers:
676 |             observer.join()
677 | 
678 |         console.print(f"[yellow]🛑 Stopped {len(self.observers)} observer(s)[/yellow]")
679 |         self.observers.clear()
680 | 
681 |     async def run(self) -> None:
682 |         """Run the drop zone monitor."""
683 |         self.load_config()
684 |         self.start()
685 |         try:
686 |             while True:
687 |                 await asyncio.sleep(1)
688 |         except KeyboardInterrupt:
689 |             console.print("\n[yellow]⚡ Received interrupt signal[/yellow]")
690 |         finally:
691 |             self.stop()
692 | 
693 | 
694 | async def main():
695 |     """Main entry point."""
696 |     # Display startup banner
697 |     console.print("\n[bold cyan]═══════════════════════════════════════[/bold cyan]")
698 |     console.print("[bold cyan]      🚀 Agentic Drop Zone 🚀[/bold cyan]")
699 |     console.print("[bold cyan]═══════════════════════════════════════[/bold cyan]\n")
700 | 
701 |     # Check environment variables
702 |     check_environment_variables()
703 | 
704 |     drop_zone = AgenticDropZone(config_file=Path("drops.yaml"))
705 |     await drop_zone.run()
706 | 
707 | 
708 | if __name__ == "__main__":
709 |     asyncio.run(main())
710 | 


--------------------------------------------------------------------------------
/specs/simple_multi_processing_solution.md:
--------------------------------------------------------------------------------
  1 | # Simple Multi-Processing Solution for Agentic Drop Zone
  2 | 
  3 | ## Overview
  4 | Implement a queue-based async worker pool to parallelize Claude Code processing without blocking file detection.
  5 | 
  6 | ## Core Principle
  7 | **Decouple detection from processing** - Observers detect and enqueue, workers process asynchronously.
  8 | 
  9 | ## Architecture
 10 | 
 11 | ```
 12 | File System Events
 13 |        ↓
 14 | [Observer Threads] → [Async Queue] → [Worker Pool] → Claude Code
 15 |                            ↑              ↓
 16 |                       Priority/FIFO    Concurrent
 17 |                                       Processing
 18 | ```
 19 | 
 20 | ## Implementation Plan
 21 | 
 22 | ### Phase 1: Add Queue Infrastructure
 23 | 
 24 | #### 1.1 Create ProcessingQueue Class
 25 | ```python
 26 | class ProcessingQueue:
 27 |     - asyncio.Queue with priority support
 28 |     - Track pending/processing/completed items
 29 |     - Handle backpressure (max queue size)
 30 |     - Simple FIFO with optional priority by zone
 31 | ```
 32 | 
 33 | #### 1.2 Create WorkerPool Class
 34 | ```python
 35 | class WorkerPool:
 36 |     - Fixed number of async workers (default: 3)
 37 |     - Each worker pulls from queue independently
 38 |     - Graceful shutdown on Ctrl+C
 39 |     - Error isolation per worker
 40 | ```
 41 | 
 42 | ### Phase 2: Modify Existing Components
 43 | 
 44 | #### 2.1 Update DropZoneHandler
 45 | - Change `process_file()` to `enqueue_file()`
 46 | - Simply add file + metadata to queue
 47 | - Return immediately (non-blocking)
 48 | - Log queue depth for monitoring
 49 | 
 50 | #### 2.2 Update Agents Class
 51 | - Keep existing methods unchanged
 52 | - Add new `process_from_queue()` method
 53 | - Maintains backward compatibility
 54 | 
 55 | #### 2.3 Update AgenticDropZone
 56 | - Initialize queue and worker pool on start
 57 | - Start workers before observers
 58 | - Cleanup workers on shutdown
 59 | - Add queue stats to status display
 60 | 
 61 | ### Phase 3: Configuration
 62 | 
 63 | Add to `drops.yaml`:
 64 | ```yaml
 65 | processing:
 66 |   max_workers: 3  # Number of concurrent Claude Code instances
 67 |   queue_size: 100  # Max items in queue before blocking
 68 |   timeout: 300  # Seconds before killing stuck process
 69 | ```
 70 | 
 71 | ## Key Design Decisions
 72 | 
 73 | ### Why Async Workers Not Threads?
 74 | - Claude SDK already uses async/await
 75 | - Better resource utilization
 76 | - Easier cancellation and timeout handling
 77 | - Single event loop for all workers
 78 | 
 79 | ### Why Not Subprocesses?
 80 | - Avoid spawning overhead
 81 | - Simpler state management
 82 | - Shared MCP server connections
 83 | - Better error propagation
 84 | 
 85 | ### Queue Strategy
 86 | - **FIFO by default** - Simple and predictable
 87 | - **Optional priority** - By zone or file pattern
 88 | - **Backpressure** - Block new events if queue full
 89 | - **Persistence** - Optional queue state to survive crashes
 90 | 
 91 | ## Benefits
 92 | 
 93 | 1. **True Parallelism** - Process N files simultaneously
 94 | 2. **Non-blocking Detection** - Never miss file events
 95 | 3. **Resource Control** - Limit concurrent CC instances
 96 | 4. **Graceful Degradation** - Queue absorbs bursts
 97 | 5. **Simple to Implement** - ~200 lines of code change
 98 | 
 99 | ## Migration Path
100 | 
101 | ### Step 1: Minimal Change (Quick Win)
102 | - Add queue between detection and processing
103 | - Single worker initially (maintains current behavior)
104 | - Test thoroughly
105 | 
106 | ### Step 2: Enable Concurrency
107 | - Increase workers to 3
108 | - Monitor resource usage
109 | - Tune based on workload
110 | 
111 | ### Step 3: Advanced Features (Optional)
112 | - Priority queues per zone
113 | - Dynamic worker scaling
114 | - Queue persistence
115 | - Retry logic
116 | 
117 | ## Error Handling
118 | 
119 | - **Worker Crash**: Restart worker, requeue item
120 | - **CC Timeout**: Kill process, log error, continue
121 | - **Queue Full**: Log warning, drop oldest item
122 | - **Shutdown**: Drain queue gracefully
123 | 
124 | ## Monitoring
125 | 
126 | Display in console:
127 | ```
128 | 📊 Processing Status:
129 |    Queue: 5 pending | 3 processing
130 |    Workers: 3/3 active
131 |    Completed: 127 files
132 |    Errors: 2
133 | ```
134 | 
135 | ## Testing Strategy
136 | 
137 | 1. **Burst Test**: Drop 20 files simultaneously
138 | 2. **Sustained Load**: 1 file/second for 5 minutes
139 | 3. **Error Recovery**: Kill worker mid-process
140 | 4. **Resource Limits**: Max out queue and workers
141 | 
142 | ## Implementation Effort
143 | 
144 | - **Estimated LOC**: ~200 lines added/modified
145 | - **Risk**: Low (queue pattern is well-understood)
146 | - **Complexity**: Medium (async coordination)
147 | - **Time**: 4-6 hours to implement and test
148 | 
149 | ## Alternative Consideration
150 | 
151 | If this proves too complex, fallback to:
152 | - Simple `asyncio.create_task()` without await
153 | - No queue, just fire-and-forget
154 | - Accept occasional resource exhaustion
155 | - 50 lines of code change
156 | 
157 | ## Success Criteria
158 | 
159 | ✅ Can process 5+ files simultaneously
160 | ✅ File detection never blocked
161 | ✅ Graceful shutdown preserves queue state
162 | ✅ Clear visibility into processing status
163 | ✅ No more than 2x current code complexity


--------------------------------------------------------------------------------