DEV Community: Mozi Mohidien

How to Bulk-Enrich E-commerce Product Listings with AI

Mozi Mohidien — Wed, 29 Jul 2026 08:06:20 +0000

Most e-commerce catalog work is brutal. You have hundreds or thousands of products with descriptions that are either copied from a supplier, machine-translated from Chinese, or just the product name repeated three times. Rewriting them manually doesn't scale. Hiring a copywriter for every SKU isn't viable.

The E-commerce Product AI Enricher solves this. You give it a list of product page URLs. It scrapes each page, extracts all available product data, and runs it through Claude AI to generate: an SEO-optimized title, a 150-word description with natural keyword integration, a structured spec table, competitive positioning, cross-sell angles, and a target customer persona.

This tutorial walks through exactly how to use it.

What You'll Build

A pipeline that takes product page URLs and returns:

SEO title optimized for search intent (not just the product name)
150-word description that reads like a human wrote it
Structured specs extracted from unstructured page content
Competitive positioning: what makes this product worth buying
Cross-sell and upsell angles
Target customer persona

A 10-product run finishes in 90 seconds. A 50-product run costs under $1.00 total.

What You Need

An Apify account — $5 free compute to start
An Anthropic API key — Claude Haiku; fractions of a cent per product
A list of product page URLs to enrich

The URLs can be your own store, competitor pages, or supplier pages — any publicly accessible product URL works.

Step 1: Collect Your Product URLs

For your own store, pull a CSV export from Shopify, WooCommerce, or your platform of choice. The product URL column is what you need.

For competitor research, find their product category pages and collect URLs manually or via a link scraper.

For dropshippers: go to your supplier's catalog pages (AliExpress, CJdropshipping, etc.) and collect the URLs of products you're listing. The actor will turn generic supplier descriptions into differentiated copy.

Step 2: Open the Actor

Go to E-commerce Product AI Enricher on Apify and click Try for free.

Step 3: Configure Your Run

Here's a sample input for enriching ergonomic office furniture:

{
  "productUrls": [
    "https://www.amazon.com/dp/B08N5WRWNW",
    "https://somestore.com/products/ergochair-pro",
    "https://supplier.com/products/mesh-office-chair-lumbar"
  ],
  "anthropicApiKey": "sk-ant-api03-...",
  "targetKeyword": "ergonomic office chair",
  "outputFormat": "full",
  "maxConcurrency": 5
}

productUrls — any publicly accessible product page. Amazon, Shopify, WooCommerce, Magento, custom sites all work.

targetKeyword — optional, but use it. Claude will optimize the title and description to rank for this term. Use your primary keyword — the one your category targets in Google.

outputFormat — full gives you everything. copy-only gives just the title and description if you only need the text.

maxConcurrency — how many pages to scrape in parallel. Default 5 is fine for most runs. Raise to 10 for large batches.

Step 4: Run It

Click Start. The actor visits each URL, extracts the product content, and sends it to Claude AI for enrichment. A 10-product run finishes in 90 seconds.

Step 5: Understand the Output

Here's what a full enrichment record looks like:

{
  "url": "https://www.amazon.com/dp/B08N5WRWNW",
  "originalTitle": "ErgoChair Pro Office Chair",
  "enrichment": {
    "seoTitle": "Ergonomic Office Chair with Lumbar Support — Adjustable Armrests, Mesh Back, 8h Comfort",
    "description": "Built for people who sit 8 hours a day. The ErgoChair Pro combines a breathable mesh back with a 4-way adjustable lumbar support system that actually holds its position. The armrests adjust in height and angle independently — unusual at this price point. Suitable for desks 70–80cm high. Weight capacity 120kg. Available in black and grey.",
    "specs": {
      "Material": "Mesh back, foam seat",
      "Max weight": "120kg",
      "Adjustable height": "42–52cm",
      "Armrests": "4D adjustable",
      "Warranty": "2 years"
    },
    "competitivePositioning": "Priced below Humanscale and Herman Miller alternatives while offering comparable lumbar adjustment. Lacks the build quality of premium options but outperforms generic mesh chairs at this price range.",
    "targetPersona": "Remote workers spending 6+ hours seated daily, prioritizing back support over aesthetics",
    "crossSellAngles": ["monitor arms", "standing desk converters", "desk pads"]
  }
}

seoTitle — leads with the primary keyword, adds specific differentiators ("Adjustable Armrests, Mesh Back") that people actually search for. Better than the original "ErgoChair Pro Office Chair" which doesn't explain what makes it worth buying.

description — specific, not generic. It mentions the 4-way armrest adjustment being unusual at this price point. That's the kind of detail that converts.

specs — structured from whatever was on the page, even if it was buried in paragraph text. Ready to paste into your product spec table.

competitivePositioning — most useful for competitive research. Run a competitor URL and this field tells you where their product is genuinely weaker.

crossSellAngles — use these for your "frequently bought with" recommendations or bundles.

Step 6: Export and Import

Export the Apify dataset as CSV → import into Shopify, WooCommerce, or wherever you manage your catalog. The fields map cleanly to standard product fields.

For large catalogs, use Apify's webhook or API integration to pipe results directly into your catalog management system as each product completes.

Use Cases

Dropshippers — supplier descriptions are almost always generic and keyword-stuffed. This actor turns "High Quality Ergonomic Mesh Chair With Lumbar Support Good For Office Use" into copy that actually explains the product. Differentiation at scale.

Amazon sellers — run your competitor listings through the enricher. The competitive positioning field will tell you where their copy is weak, what they're not saying, and how to write a better listing for the same product.

Agencies — if you manage e-commerce clients, this is a service you can sell. Catalog enrichment at scale is labor-intensive; this makes it fast. Run 100 products, edit the top 10% manually for hero products, ship the rest as-is.

Price comparison sites — if you aggregate product data from multiple retailers, the enricher normalizes it into a consistent schema. Specs, descriptions, and titles are standardized across sources.

Tips

Quality is higher when you provide targetKeyword. Claude generates more focused copy when it knows what term you're optimizing for. Don't skip it.

Run your worst listings first. Sort your catalog by conversion rate ascending and start with the bottom 10%. Those are the products where better copy will have the most immediate revenue impact.

Use the spec output for structured data. Google uses structured product data for rich results in shopping. Clean spec tables are also what customers look for on mobile — the description matters less than the bullet points.

For non-English pages: Claude AI is multilingual and can extract data from French, German, Spanish, Dutch, and other European-language pages reliably. Set targetKeyword in English for the output copy even if the source is in another language.

Pricing

Component	Cost
Apify compute	~$0.01–$0.02 per product URL
Anthropic (Claude Haiku)	~$0.003–$0.005 per product enriched
50 products	Under $1.00 total

A 500-product catalog enrichment costs under $10. Compare that to a copywriter at $5–$15 per product description.

Try It

The actor is live: E-commerce Product AI Enricher on Apify

Start with 10 of your worst-converting product URLs and a target keyword. Review the output — you'll see immediately which fields are ready to publish and which need a quick edit.

Questions or feedback? Drop a comment below.

How to Use Job Postings as B2B Lead Signals (with AI)

Mozi Mohidien — Wed, 29 Jul 2026 08:06:09 +0000

Timing is the part of B2B sales most people get wrong. They reach out to companies that might buy, instead of companies that are buying right now.

A company that just posted three senior data engineer roles has an open headcount budget, an active hiring cycle, and a head of data with approval authority who is already thinking about their stack. They are in motion. That is the moment to reach out — not six months later when the hiring is done and the budget is spent.

The problem is that job postings are scattered across LinkedIn, Greenhouse, Lever, Indeed, and dozens of company career pages. Manually checking them isn't realistic at any scale.

This tutorial shows you how to automate it. The Job Posting AI Analyzer scrapes job posting URLs you feed it and sends each one through Claude AI to extract: tech stack, seniority, what business problem the hire is solving, who likely approved it, and a B2B signal score from 1–10.

What You'll Build

A pipeline that takes a list of job posting URLs and returns:

B2B hiring signal score (1–10) for each posting
Tech stack extracted from the job description
Seniority level and team context
Business problem the hire is solving
Decision-maker title (who probably approved the req)
Outreach timing recommendation

A 50-URL batch runs in under 2 minutes and costs less than $0.75 total.

What You Need

An Apify account — free tier includes $5 compute
An Anthropic API key — Claude Haiku handles the analysis; fractions of a cent per posting
A list of job posting URLs from LinkedIn, Greenhouse, Lever, Indeed, or company career pages

Step 1: Find Job URLs

LinkedIn's job search is the easiest source. Filter by:

Function (e.g., "Engineering", "Data", "Marketing")
Company size (e.g., 51–200, 201–500 employees)
Date posted (past week)

Copy the job URLs from the results. You can also use Apify's LinkedIn Jobs Scraper if you want to automate the URL collection step.

For Greenhouse and Lever boards (common at Series A–C companies), the URL format is consistent: boards.greenhouse.io/[company]/jobs/[id] and jobs.lever.co/[company]/[id]. Both work with this actor.

Step 2: Open the Actor

Go to Job Posting AI Analyzer on Apify and click Try for free.

Step 3: Configure Your Run

Here's a sample input for a data tooling company targeting companies scaling their data teams:

{
  "jobUrls": [
    "https://www.linkedin.com/jobs/view/4253571918",
    "https://boards.greenhouse.io/databricks/jobs/7614285002",
    "https://jobs.lever.co/airbyte/abc123",
    "https://careers.acmecorp.com/jobs/senior-data-engineer"
  ],
  "anthropicApiKey": "sk-ant-api03-...",
  "minScore": 7,
  "extractTechStack": true,
  "maxConcurrency": 5
}

jobUrls — any publicly accessible job posting URL. Boards requiring login won't work; most don't.

minScore — posts scoring below this are dropped. 7+ means the company is hiring in or near the function your product serves. 9–10 means the hire directly implies budget for your category.

extractTechStack — keep this true. Even when tech isn't listed explicitly, Claude infers it from context ("experience with our data warehouse" in a Snowflake shop tells you their stack).

Step 4: Run It

Click Start. A 5-URL batch finishes in under a minute. A 50-URL batch takes 1–2 minutes.

Step 5: Read a High-Score Output

Here's what a score-9 record looks like:

{
  "url": "https://boards.greenhouse.io/somecompany/jobs/4567890",
  "company": "Acme Analytics",
  "jobTitle": "Senior Data Engineer",
  "location": "Remote",
  "analysis": {
    "hiringSignalScore": 9,
    "seniority": "Senior (5+ years)",
    "techStack": ["Python", "dbt", "Snowflake", "Airflow", "AWS"],
    "teamContext": "Third data hire in 60 days — building out platform team, not just backfilling",
    "businessProblem": "Moving from ad-hoc analytics to a self-serve data platform. Engineering is the current bottleneck for reports.",
    "decisionMakerTitle": "Head of Data / VP Engineering",
    "outreachTiming": "Ideal — actively scaling, budget open, buying cycle in progress"
  }
}

Score 9 with "actively scaling, budget open" means reach out this week. The Head of Data is approving headcount — they're also thinking about tooling to make that team productive.

The techStack field tells you exactly what they use. If your product integrates with Snowflake and dbt, lead with that. If they're on a stack you don't support, don't waste their time.

The businessProblem field gives you your opening line: "Saw you're building out your data platform — specifically around self-serve analytics. Worth a 20-minute call to show you how [X companies your size] handled the engineering bottleneck for reporting?"

Step 6: Export and Outreach

Export the dataset as CSV → import into HubSpot, Apollo, or your CRM. Use the decisionMakerTitle to find the right person on LinkedIn. Use businessProblem as your first sentence.

Don't reference that you saw their job posting directly — it can feel intrusive. Use it as intelligence, not as your opening.

Tips

Hiring patterns that signal open budget:

Multiple hires in the same function within 60 days — budget is flowing
Senior-level hires (5+ years) — they're paying above median, budget is real
"Head of" or "Director of" hires — building a new function from scratch

Patterns that signal cost-cutting (avoid):

Backfill postings ("joining our existing team of X")
Junior-heavy postings (they're reducing cost, not scaling)
Postings that have been live for 60+ days (either very hard to fill or frozen)

How often to run it: Weekly. A 7-day cadence catches companies early in their hiring cycle while the budget decision is still fresh. Monthly is too slow — the window closes.

Building your URL list at scale: Use LinkedIn job search with filters for your ICP (company size + function + date posted), export the URLs, run them through this actor. Takes 20 minutes to set up a weekly process that would otherwise take hours.

Pricing

Component	Cost
Apify compute	~$0.01–$0.02 per job URL
Anthropic (Claude Haiku)	~$0.003 per posting analyzed
50 job postings	Under $0.75 total

Weekly runs of 100 postings cost about $1.50. You only need one good lead per week to justify it.

Try It

The actor is live: Job Posting AI Analyzer on Apify

Start with 10 job URLs from LinkedIn for companies in your ICP. See what scores 8+. Use the business problem field to write your first outreach line.

Questions or feedback on the actor? Drop a comment below.

How to Find B2B Leads on Reddit Using AI (No Code Required)

Mozi Mohidien — Wed, 29 Jul 2026 08:03:33 +0000

Most founders and sales teams who try Reddit for lead gen give up within a week. The manual process doesn't scale: you have to know which subreddits to watch, search the right keywords, scroll through noise, and decide whether each post is worth responding to. By the time you've done that for 5 subreddits, an hour is gone and you've found two maybe-leads.

This tutorial shows you how to automate the whole thing. You'll use the Reddit Lead AI Finder actor on Apify — it searches subreddits by keyword, then runs each post through Claude AI to score buying intent, extract the pain point, and suggest how to respond.

What You'll Build

A repeatable pipeline that:

Searches any combination of subreddits and keywords
Scores each post 1–10 for buying intent using Claude AI
Extracts the exact pain point being described
Suggests how to respond to the post authentically
Filters out noise below your score threshold

A typical run of 3 subreddits x 3 keywords x 20 posts takes under 3 minutes and costs less than $0.35.

What You Need

An Apify account — free tier gives you $5 compute credit to start
An Anthropic API key — free to create; Claude Haiku costs fractions of a cent per post
A list of target subreddits and keywords relevant to your product or service

Step 1: Get Your Anthropic API Key

Go to console.anthropic.com, create an account, and generate an API key. It looks like sk-ant-api03-....

The actor uses Claude Haiku — the cheapest Claude model — for lead scoring. At roughly $0.002 per post analyzed, you can process 500 posts for about a dollar.

Step 2: Open the Actor

Go to Reddit Lead AI Finder on Apify and click Try for free.

Step 3: Configure Your Run

Here's a concrete example for a CRM or sales tool:

{
  "subreddits": ["entrepreneur", "saas"],
  "keywords": ["recommend CRM", "looking for tool", "alternative to"],
  "maxPostsPerSearch": 20,
  "minLeadScore": 7,
  "anthropicApiKey": "sk-ant-api03-...",
  "sortBy": "relevance"
}

subreddits — list without the r/ prefix. Start with 2–3 tightly focused communities rather than big general ones.

keywords — search terms Reddit will match against post titles and bodies. "Looking for a tool", "anyone recommend", "alternative to [competitor]", "how do you handle X" are all strong patterns.

minLeadScore — posts scoring below this are dropped from output. 7+ is the right default — it keeps genuinely interested people and drops rants and tangential mentions.

sortBy — relevance for best signal. new if you want to catch posts before anyone else replies.

Step 4: Run It

Click Start. The actor searches Reddit, fetches post content, and sends each post to Claude AI for scoring. A 2-subreddit x 3-keyword x 20-post run finishes in 1–3 minutes.

Step 5: Review Your Results

Here's what a high-scoring output record looks like:

{
  "postId": "abc123",
  "subreddit": "entrepreneur",
  "title": "Best CRM for a 3-person sales team?",
  "author": "u/startupfounder99",
  "upvotes": 47,
  "commentCount": 23,
  "url": "https://reddit.com/r/entrepreneur/comments/abc123",
  "leadAnalysis": {
    "leadScore": 9,
    "buyingSignals": ["actively evaluating tools", "has budget context", "specific use case defined"],
    "painPoint": "Current spreadsheet-based process breaking down as team grows. Needs pipeline visibility without enterprise complexity.",
    "outreachAngle": "Comment with a specific recommendation based on their 3-person constraint. Lead with the problem, not the product."
  }
}

leadScore 9 means active buying intent — this person is making a decision right now, not just exploring. Score 7–8 means serious consideration. Score 6 means problem-aware but not yet shopping.

The painPoint field tells you exactly what to address in your response. The outreachAngle tells you how to frame it. Don't paste your product description — engage with their specific problem first.

Step 6: Export and Act

Click the Dataset tab -> Export -> CSV. You now have a scored lead list with post URLs, pain points, and outreach angles.

For each lead scoring 8+:

Read the actual post and the top comments
Write a reply addressing their specific pain point first
Mention your product as one option among several if it genuinely fits

Reddit punishes obvious promotion. If your reply leads with value, it will get upvoted and convert. If it looks like an ad, it gets removed.

Use Cases by Niche

SaaS tools — r/entrepreneur, r/saas, r/startups, r/webdev. Keywords: "anyone use", "recommend", "looking for alternatives to", "how do you handle".

Agencies and freelancers — r/smallbusiness, r/marketing, r/freelance. Keywords: "looking to hire", "need help with", "should I outsource".

E-commerce — niche subreddits specific to your product category. Someone in r/coffee asking about inventory management is a better lead than the same question in r/entrepreneur.

B2B services — r/msp, r/sysadmin, r/devops. Keywords: "looking for a solution", "recommendation for", "has anyone dealt with".

Tips

Post age matters. Posts under 2 days old are better targets — the person is still checking for replies. A 3-week-old post with 200 comments already has its answer.

Why 7+ is the right threshold. Scores below 7 tend to be: venting with no intent to buy, general curiosity questions, or posts where your product is tangentially relevant at best. Keeping the threshold at 7 means every result is worth reading.

Combine with other signals. If you also run the Job Posting AI Analyzer, you can cross-reference: companies where employees are posting Reddit questions about pain your product solves AND who are hiring in the same function have a genuinely open budget.

Run it on a schedule. Set up a weekly Apify scheduled run on your top subreddits. New posts surface automatically; you review on Monday and respond to whatever scored 8+.

Pricing

Component	Cost
Apify compute	~$0.01 per subreddit/keyword search
Anthropic (Claude Haiku)	~$0.002 per post analyzed
3 subreddits x 3 keywords x 20 posts	Under $0.35 total

You can run this daily for a week for under $3. Compare that to any lead database subscription.

Try It

The actor is live: Reddit Lead AI Finder on Apify

Start with your top 2 subreddits and 3 keywords. See what scores 8+. Reply to 3 of them this week and see what happens.

Questions or issues? Drop a comment below.

How to Find Company Emails and Contacts with AI (No Code Required)

Mozi Mohidien — Tue, 28 Jul 2026 15:17:09 +0000

How to Find Company Emails and Contacts with AI (No Code Required)

Tags: webdev, tutorial, ai, productivity
Canonical URL: https://apify.com/mozimohidien/company-contact-ai-enricher

If you do any B2B sales or outreach, you know the bottleneck: you have a list of target companies but you spend half your time just finding who to contact and what to say.

Tools like Apollo and Hunter help, but they're expensive, they only cover companies already in their database, and they give you raw contacts — not the intelligence you need to make your message land.

This tutorial shows you how to go from a list of company URLs to enriched, ICP-scored leads with personalised outreach openers — using an AI-powered Apify actor, no code, no subscription required.

What You'll Build

A pipeline that takes company website URLs as input and returns:

Publicly available emails, phone numbers, LinkedIn, and Twitter profiles
AI enrichment: industry, estimated team size, tech stack signals, ICP fit score (1–10)
A personalised outreach opener written specifically for each company

Total cost for a 20-company run: under $1. Time: about 3 minutes.

Why Not Just Use a Contact Database?

Contact databases (Apollo, ZoomInfo, Hunter) are great — but they have real gaps:

Coverage: smaller or newer companies often aren't indexed
Freshness: emails go stale; people change roles
Intelligence: they give you a contact, not a reason to reach out
Cost: enterprise plans cost hundreds per month

The actor in this tutorial scrapes directly from company websites, so coverage is whoever has a public web presence — and it adds an AI layer that scores the lead against your specific ICP and writes a first-line that doesn't sound like a template.

What You Need

An Apify account (free tier works)
An Anthropic API key (free to create; Claude Haiku costs ~$0.25 per million tokens — fractions of a cent per company)
A list of company website URLs

That's it. No code, no local setup.

Step 1: Get Your Anthropic API Key

Go to console.anthropic.com, create an account, and generate an API key. It looks like sk-ant-api03-....

The actor uses Claude Haiku — the fastest and cheapest model in the Claude family — for the enrichment step. For a 20-company run, expect to spend $0.01–$0.05 on the AI calls.

Step 2: Open the Actor

Go to: Company Contact Scraper & AI Lead Enricher on Apify

Click Try for free. You don't need a paid plan — Apify gives you $5 of free compute credit when you sign up, which is enough for hundreds of test runs.

Step 3: Configure Your Run

You'll see a simple input form. Here's what each field does:

Company URLs
Paste your target company URLs, one per line. These are the websites you want to scrape and enrich. Example:

https://stripe.com
https://notion.so
https://linear.app
https://figma.com

You can also upload a text file with URLs if you have a long list.

Anthropic API Key
Paste your sk-ant-... key here. It's stored as a secret — never logged or exposed.

Max Companies
How many companies to process in this run. Default is 10; max is 50 per run. For bigger lists, run multiple batches.

Proxy Configuration (optional)
Leave this empty for most websites. If you're targeting companies that have aggressive bot protection, enable Apify Residential Proxy here.

Step 4: Run It

Click Start. The actor will:

Visit each company URL
Extract publicly visible emails, phone numbers, and social links
Send the scraped content to Claude AI for enrichment
Store results in a structured dataset

A 10-company run typically finishes in 60–90 seconds.

Step 5: Review Your Results

When the run completes, click the Dataset tab. You'll see one row per company.

Here's what a single output record looks like:

{
  "url": "https://linear.app",
  "emails": ["hello@linear.app"],
  "phones": [],
  "socials": {
    "linkedin": "https://linkedin.com/company/linear",
    "twitter": "https://twitter.com/linear"
  },
  "enrichment": {
    "industry": "B2B SaaS / Project Management",
    "teamSizeEstimate": "50-200",
    "icpFitScore": 9,
    "techStackHints": ["React", "TypeScript", "Electron"],
    "primaryProduct": "Issue tracking and project management for software teams",
    "decisionMakerTitle": "Head of Engineering / VP Product",
    "outreachHook": "Linear is doing impressive work on keyboard-driven UX — wanted to reach out about how similar dev-tool companies have cut their SDR research time by 60%."
  }
}

The icpFitScore is on a 1–10 scale. Sort your results by score and start with the 8+ leads.

Step 6: Export to Your CRM

Click Export → CSV. The column headers map directly to standard CRM fields. Import into HubSpot, Salesforce, or Apollo with their standard CSV import flow.

If you want to automate this — e.g., run the actor on a schedule and push results straight to your CRM via webhook — Apify has built-in integrations with Zapier, Make, and its own API.

Real-World Use: Cold Email Sequence

Here's how I'd use this for a cold email campaign targeting B2B SaaS tools:

Build a list of 50 company URLs from LinkedIn search, ProductHunt, or a VC portfolio page
Run the actor — 3 minutes, under $2
Filter results: icpFitScore >= 8
Use the outreachHook as the first line of your cold email
Add the lead to Instantly or Apollo with the extracted email
Send

The personalized opener is the part that moves reply rates. Generic openers ("I came across your company and thought...") get ignored. An opener that references what the company actually does ("Linear is doing impressive work on keyboard-driven UX...") gets opened.

Tips

URL quality matters. The actor visits the homepage. If a company's contact info is only on their /contact page, you might miss it. For best results, pass the /contact URL directly when you know it.

Don't over-batch. 20–30 URLs per run gives you fast results and easy debugging if something goes wrong. Scale up once you've validated the output quality.

Combine with job posting signals. Pair this actor with the Job Posting AI Analyzer to time your outreach: companies actively hiring are actively spending. Hit them when their budget is open.

Reddit for warm leads. Use the Reddit Lead AI Finder to surface companies posting about pain your product solves, then run those domains through this actor for contact info.

Pricing Summary

Component	Cost
Apify compute	~$0.01–$0.05 per company
Anthropic (Claude Haiku)	~$0.001–$0.003 per company
Total per company	~$0.02–$0.08

A 50-company run costs $1–$4. Compare that to Apollo Pro at $99/month or ZoomInfo at $15,000/year.

Wrapping Up

You now have a repeatable, code-free pipeline to:

Find publicly available contact details on any company website
Score leads against your ICP automatically
Generate personalised outreach openers at scale

The actor is live on Apify: Company Contact Scraper & AI Lead Enricher

Try it free. The first $5 of Apify compute is on them.

Have questions or want to suggest improvements to the actor? Drop a comment below.

Building an AI Enrichment Pipeline with Airbyte and Claude

Mozi Mohidien — Sat, 25 Jul 2026 09:56:09 +0000

A while back I was working on a client project where GitHub issues needed to be triaged automatically. The team had hundreds of open tickets — bugs, feature requests, questions, random noise — and wanted a dashboard that grouped them by priority before any human touched them.

My first instinct was the obvious one: write a script. Hit the GitHub API, send each issue to Claude, write results to a table. Done in two hours. Worked great until GitHub rate-limited me on the second run, the schema drifted, they added a second repo, and I was suddenly maintaining three separate scripts that all did mostly the same thing.

So I rebuilt it with Airbyte handling the sync and a small Python enrichment layer doing the AI classification. That combination has held up much better, and this is how to set it up.

Working code: github.com/Mozi1185/airbyte-claude-enrichment

What you'll build:

Airbyte connection: GitHub issues → Postgres (incremental sync)
Python enricher: reads unprocessed rows, classifies them with claude-haiku-4-5, writes structured results back
SQL queries you can actually use

Time: ~45 minutes

Prerequisites: Python 3.10+, Docker (for local Postgres), an Airbyte Cloud account (free tier works), an Anthropic API key, a GitHub personal access token

Why not just write one script

You could call the GitHub API and Claude in the same script. Most tutorials show exactly that. The problem is everything that happens after it works the first time.

GitHub rate-limits you. Claude returns something your parser didn't expect. You add a second repo. A colleague wants to add Jira. Now you're maintaining glue code instead of the actual thing you were trying to build.

Splitting the work cleanly: Airbyte handles connector maintenance, auth refresh, pagination, incremental tracking, schema evolution. That's genuinely annoying to implement correctly and I don't want to do it. The enrichment layer stays stateless and portable — run it on a cron, trigger it from a webhook, drop it into Airflow later. Failed enrichments don't block syncs. Sync failures don't corrupt enriched output. When the client adds Zendesk, I add an Airbyte connection and point the same enricher at a different table.

Step 1: Stand up Postgres

If you already have a Postgres instance, skip this. For local development:

docker run -d \
  --name enrichment-db \
  -e POSTGRES_USER=dev \
  -e POSTGRES_PASSWORD=localdev \
  -e POSTGRES_DB=enrichment \
  -p 5432:5432 \
  postgres:16

Verify it started:

docker exec -it enrichment-db psql -U dev -d enrichment -c "SELECT version();"

Step 2: Connect GitHub to Postgres via Airbyte

Log into Airbyte Cloud. Create a new connection.

Source: GitHub

Go to Sources → + New source → GitHub
Enter the repository — e.g. airbytehq/airbyte or your own
Paste your GitHub personal access token (repo scope — generate at github.com/settings/tokens)
Click Set up source

Destination: Postgres

Go to Destinations → + New destination → Postgres
Fill in your connection details:
- Host: localhost
- Port: 5432
- Database: enrichment
- Username: dev
- Password: localdev
- Default Schema: github_raw
Click Set up destination

Heads up: If you're running Postgres locally, Airbyte Cloud can't reach localhost — they're on different networks. I burned an afternoon on this before realizing it. The fix is ngrok: ngrok tcp 5432. Copy the tunnel host and port (something like 0.tcp.ngrok.io:12345) and use those in the destination config instead of localhost.

Connection settings

Under Streams, select issues only — uncheck everything else
Sync mode: Incremental | Append + Deduped
Schedule: every 6 hours (or trigger manually for now)
Click Set up connection, then Sync now

The first sync creates github_raw.issues in Postgres and populates it. Verify:

SELECT id, title, state, created_at
FROM github_raw.issues
LIMIT 5;

The body column is what Claude will read. If it's empty on some rows, that's normal — GitHub allows issues without a body.

Step 3: Create the enrichment table

CREATE TABLE IF NOT EXISTS github_raw.issues_enriched (
    issue_id         BIGINT PRIMARY KEY,
    category         TEXT,
    priority         TEXT,
    one_line_summary TEXT,
    enriched_at      TIMESTAMPTZ DEFAULT now()
);

PRIMARY KEY on issue_id makes re-runs safe — it upserts rather than duplicating rows.

Step 4: Install dependencies

pip install anthropic psycopg2-binary python-dotenv

Create .env:

ANTHROPIC_API_KEY=sk-ant-...
DB_HOST=localhost
DB_PORT=5432
DB_NAME=enrichment
DB_USER=dev
DB_PASSWORD=localdev

Step 5: Write the enricher

# enricher.py
import os
import json
import psycopg2
import anthropic
from dotenv import load_dotenv

load_dotenv()

client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

DB_CONFIG = {
    "host":     os.environ["DB_HOST"],
    "port":     int(os.environ["DB_PORT"]),
    "dbname":   os.environ["DB_NAME"],
    "user":     os.environ["DB_USER"],
    "password": os.environ["DB_PASSWORD"],
}

SYSTEM_PROMPT = """You are a triage assistant for a software project.
Given a GitHub issue title and body, return a JSON object with exactly these fields:
- category: one of "bug", "feature_request", "documentation", "question", "other"
- priority: one of "critical", "high", "medium", "low"
- one_line_summary: a single sentence (max 120 chars) describing the issue

Return only valid JSON. No explanation, no markdown fences."""


def classify_issue(title: str, body: str) -> dict:
    """Send one issue to Claude and return structured classification."""
    content = f"Title: {title}\n\nBody:\n{body or '(no body provided)'}"

    message = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=256,
        system=SYSTEM_PROMPT,
        messages=[{"role": "user", "content": content}],
    )

    raw = message.content[0].text.strip()
    return json.loads(raw)


def get_unenriched_issues(conn, limit: int = 50) -> list[dict]:
    """Fetch issues that haven't been enriched yet."""
    with conn.cursor() as cur:
        cur.execute("""
            SELECT i.id, i.title, i.body
            FROM github_raw.issues i
            LEFT JOIN github_raw.issues_enriched e ON e.issue_id = i.id
            WHERE e.issue_id IS NULL
              AND i.state = 'open'
            ORDER BY i.created_at DESC
            LIMIT %s
        """, (limit,))
        cols = [desc[0] for desc in cur.description]
        return [dict(zip(cols, row)) for row in cur.fetchall()]


def write_enrichment(conn, issue_id: int, result: dict) -> None:
    """Upsert enrichment result for one issue."""
    with conn.cursor() as cur:
        cur.execute("""
            INSERT INTO github_raw.issues_enriched
                (issue_id, category, priority, one_line_summary, enriched_at)
            VALUES (%s, %s, %s, %s, now())
            ON CONFLICT (issue_id) DO UPDATE SET
                category         = EXCLUDED.category,
                priority         = EXCLUDED.priority,
                one_line_summary = EXCLUDED.one_line_summary,
                enriched_at      = now()
        """, (
            issue_id,
            result["category"],
            result["priority"],
            result["one_line_summary"],
        ))
    conn.commit()


def run_enrichment_batch(limit: int = 50) -> None:
    conn = psycopg2.connect(**DB_CONFIG)
    try:
        issues = get_unenriched_issues(conn, limit)
        print(f"Found {len(issues)} unenriched issues")

        for issue in issues:
            issue_id = issue["id"]
            try:
                result = classify_issue(
                    issue["title"] or "",
                    issue["body"] or "",
                )
                write_enrichment(conn, issue_id, result)
                print(f"  #{issue_id} → {result['category']} / {result['priority']}")
            except json.JSONDecodeError as e:
                print(f"  #{issue_id} parse error: {e} — skipping")
            except anthropic.APIError as e:
                print(f"  #{issue_id} API error: {e} — skipping")
    finally:
        conn.close()


if __name__ == "__main__":
    run_enrichment_batch()

Run it:

python enricher.py

Expected output:

Found 47 unenriched issues
  #1823 → bug / high
  #1801 → feature_request / medium
  #1799 → documentation / low
  #1788 → question / low
  ...

Step 6: Query the results

High-priority bugs, newest first:

SELECT
    i.id,
    i.title,
    e.category,
    e.priority,
    e.one_line_summary,
    i.created_at
FROM github_raw.issues i
JOIN github_raw.issues_enriched e ON e.issue_id = i.id
WHERE e.category = 'bug'
  AND e.priority IN ('critical', 'high')
ORDER BY i.created_at DESC
LIMIT 20;

Full breakdown across categories:

SELECT
    e.category,
    e.priority,
    COUNT(*) AS issue_count
FROM github_raw.issues_enriched e
GROUP BY e.category, e.priority
ORDER BY e.category, e.priority;

Step 7: Keep it running

The enricher is stateless — run it on any scheduler. Simplest option:

# Cron: run enrichment 15 minutes after each Airbyte sync (syncs at :00)
15 */6 * * * cd /path/to/project && python enricher.py >> enricher.log 2>&1

If you want tighter coupling, Airbyte has Webhook Notifications under each connection's settings. Point the webhook at an endpoint that calls run_enrichment_batch() and the enricher fires exactly when a sync completes — no delay, no polling.

Eliminating parse errors with tool use

The enricher above parses Claude's JSON from raw text. It works most of the time. But Claude occasionally wraps the output in a markdown code fence, or adds a clarifying sentence before the JSON, and then json.loads blows up. The json.JSONDecodeError catch in the loop handles this by skipping the row — which is fine, but skipped rows means gaps in your enrichment.

The cleaner fix: Claude's tool use API. Instead of asking for JSON in the prompt, you define a tool with the exact schema and force Claude to call it. The response comes back already structured — no parsing step.

CLASSIFY_TOOL = {
    "name": "classify_issue",
    "description": "Classify a GitHub issue by category, priority, and summary.",
    "input_schema": {
        "type": "object",
        "properties": {
            "category": {
                "type": "string",
                "enum": ["bug", "feature_request", "documentation", "question", "other"]
            },
            "priority": {
                "type": "string",
                "enum": ["critical", "high", "medium", "low"]
            },
            "one_line_summary": {
                "type": "string",
                "description": "Single sentence, max 120 characters"
            }
        },
        "required": ["category", "priority", "one_line_summary"]
    }
}


def classify_issue_structured(title: str, body: str) -> dict:
    """Classify using tool use — no JSON parsing, no parse errors."""
    content = f"Title: {title}\n\nBody:\n{body or '(no body provided)'}"

    message = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=256,
        tools=[CLASSIFY_TOOL],
        tool_choice={"type": "tool", "name": "classify_issue"},
        messages=[{"role": "user", "content": content}],
    )

    # content[0] is always a ToolUseBlock when tool_choice forces a specific tool
    return message.content[0].input  # already a dict

Swap classify_issue for classify_issue_structured in run_enrichment_batch and remove the json.JSONDecodeError catch — you won't hit it anymore.

What this costs

claude-haiku-4-5 is $0.80 per million input tokens and $4 per million output tokens. Each issue uses roughly 300–600 input tokens and about 80 output tokens.

At 10,000 issues:

Component	Tokens	Cost
Input (avg 450 × 10k)	4.5M	~$3.60
Output (avg 80 × 10k)	0.8M	~$3.20
Total		~$6.80

That's for the initial backfill. After that, Airbyte only syncs new rows since the last run, so ongoing enrichment costs scale with new volume only — not the full history.

If you want to cut input costs further, use prompt caching. The system prompt is identical across every call, so caching it drops input costs by roughly 90% on repeated runs:

message = client.messages.create(
    model="claude-haiku-4-5",
    max_tokens=256,
    system=[{
        "type": "text",
        "text": SYSTEM_PROMPT,
        "cache_control": {"type": "ephemeral"}
    }],
    messages=[{"role": "user", "content": content}],
)

Worth doing if you're running this on a large repo.

Swapping sources

The enrichment code doesn't know anything about GitHub. It reads from a table Airbyte created. To switch to Jira, add a new Airbyte connection with Jira as the source and the same Postgres destination. Airbyte creates a new schema and table. Write a get_unenriched_jira_issues function pointing at that table. The classify_issue function is reusable as-is.

Airbyte has 300+ connectors — Zendesk, HubSpot, Salesforce, Notion, Linear. The enrichment pattern applies to all of them. That's the point of keeping the sync and enrichment separate.

What you end up with: a Postgres table populated by Airbyte on a schedule, an enrichment layer that classifies each new row after each sync, and structured output queryable by whatever SQL tool your team uses. The sync and enrichment stay independent — neither can break the other, and adding a new source is an Airbyte config change, not a code change.

Mozi Mohidien builds AI automation systems — Claude API, Airbyte, n8n, Telegram. Writing at dev.to/mozimohidien.

How to find company emails and enrich leads with AI

Mozi Mohidien — Sat, 25 Jul 2026 04:44:50 +0000

Cold outreach lives or dies on two things: finding the right contact and saying something worth reading. Most tools handle one of those. This article shows you how to do both in a single automated run.

We'll use an Apify actor — Company Contact Scraper & AI Lead Enricher — as the worked example. By the end you'll have a repeatable pipeline that takes a list of company URLs and returns contact data plus AI-generated sales intelligence for each one.

What the pipeline does

The actor runs in two stages:

Scrape — visits each company URL, crawls key pages (homepage, contact, about, team), and extracts emails, phone numbers, and social profile links.
Enrich — passes each scraped company through Claude (you supply the API key) to generate: detected industry, team size estimate, ICP fit score from 1–10, tech stack hints, and a personalized cold outreach opener.

You end up with a ranked list. The ICP fit score alone changes how you work: instead of writing to 100 companies equally, you write to the 20 that scored 7+.

Prerequisites

An Apify account (free tier works)
An Anthropic API key (for Claude enrichment)
Node.js or any HTTP client to hit the Apify API

Running it via the Apify API

1. Start a run

curl -X POST \
  "https://api.apify.com/v2/acts/reverend_bluebell~company-contact-ai-enricher/runs" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "companyUrls": [
      "https://acmecorp.io",
      "https://example-saas.com",
      "https://another-b2b.co"
    ],
    "anthropicApiKey": "sk-ant-YOUR_KEY_HERE",
    "maxCompanies": 10
  }'

The response includes a runId. Save it — you'll need it to poll for results.

2. Wait for the run to finish

const apifyToken = process.env.APIFY_TOKEN;
const runId = "YOUR_RUN_ID";

async function waitForRun(runId) {
  const url = `https://api.apify.com/v2/actor-runs/${runId}`;

  while (true) {
    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${apifyToken}` },
    });
    const { data } = await res.json();

    if (data.status === "SUCCEEDED") return data;
    if (data.status === "FAILED") throw new Error("Run failed");

    console.log(`Status: ${data.status} — waiting 5s`);
    await new Promise((r) => setTimeout(r, 5000));
  }
}

3. Fetch the results

async function getResults(runId) {
  const url = `https://api.apify.com/v2/actor-runs/${runId}/dataset/items`;

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${apifyToken}` },
  });

  return res.json();
}

const run = await waitForRun(runId);
const leads = await getResults(run.id);

console.log(leads);

4. What comes back

Each item in the results array looks like this:

{
  "url": "https://acmecorp.io",
  "emails": ["hello@acmecorp.io", "sales@acmecorp.io"],
  "phones": ["+1-415-555-0192"],
  "linkedin": "https://linkedin.com/company/acmecorp",
  "twitter": "https://twitter.com/acmecorp",
  "industry": "B2B SaaS / HR Tech",
  "teamSize": "11-50",
  "icpFitScore": 8,
  "techStack": ["HubSpot", "Intercom", "Vercel"],
  "primaryProduct": "Employee onboarding automation platform",
  "targetDecisionMaker": "Head of People or VP HR",
  "outreachHook": "Acme's self-serve onboarding flow suggests you're scaling sales without adding headcount — exactly the scenario where [your product] cuts ramp time by half."
}

Filtering by ICP fit

Once you have results, filter before you touch your CRM:

const qualifiedLeads = leads.filter((lead) => lead.icpFitScore >= 7);

console.log(`${qualifiedLeads.length} qualified leads out of ${leads.length} total`);

You can also sort by score and take the top N:

const top10 = leads
  .sort((a, b) => b.icpFitScore - a.icpFitScore)
  .slice(0, 10);

Pushing results to a CSV

If you're loading into a spreadsheet or CRM that accepts CSV:

import { writeFileSync } from "fs";

const headers = [
  "url", "emails", "phones", "industry",
  "teamSize", "icpFitScore", "techStack", "outreachHook"
];

const rows = leads.map((lead) =>
  headers.map((h) =>
    Array.isArray(lead[h]) ? lead[h].join("; ") : lead[h] ?? ""
  )
);

const csv = [headers, ...rows]
  .map((row) => row.map((v) => `"${String(v).replace(/"/g, '""')}"`).join(","))
  .join("\n");

writeFileSync("leads.csv", csv);
console.log("Saved leads.csv");

What the AI enrichment actually costs

The actor charges $0.01 per 1,000 results — effectively free at the scale most outbound teams run. The Anthropic API usage on top depends on how many companies you process, but a 50-company run typically costs under $0.05 in Claude tokens. You control this because you supply your own key.

How it finds emails

The scraper doesn't rely on a static database. It visits the actual company website — homepage, /contact, /about, /team — and extracts email addresses from page content and mailto: links. This means you're getting current contact data, not year-old exports.

For sites that block scrapers, you can pass Apify Proxy config in the proxyConfig input field.

Other actors in the same series

If you're building a broader lead gen stack, these fit the same pattern — scrape then enrich with Claude:

Job Posting AI Analyzer — extract hiring signals from job posts
Ecommerce Product AI Enricher — enrich product listings with AI-generated descriptions and categories
Reddit Lead AI Finder — find buying intent posts on Reddit and score them

Summary

The pipeline is: list of URLs → scrape contacts → Claude enrichment → ranked leads with outreach copy. You can run it via the Apify UI or trigger it programmatically from any HTTP client. At $0.01/1,000 results, the bottleneck is your Anthropic API quota, not the platform cost.

Actor link: https://apify.com/reverend_bluebell/company-contact-ai-enricher

Bot-to-Bot Messaging Without a Message Broker: Building a Local Inbox Bus for Claude Agents

Mozi Mohidien — Wed, 22 Jul 2026 09:39:01 +0000

Bot-to-Bot Messaging Without a Message Broker: Building a Local Inbox Bus for Claude Agents

by Mozi Mohidien

Telegram's Bot API is one-way. A bot can receive messages from users and reply to them. It cannot send messages to another bot. There is no API call for "bot A sends a message to bot B."

In a multi-bot architecture where bots need to collaborate — one bot asking another for context, one bot routing a task to a specialist — this is a real problem. The usual answer is a message broker: Redis pub/sub, RabbitMQ, something with a queue. That works but adds infrastructure to a system that is already running eight processes on a single machine.

The simpler answer: a file-based inbox per bot, with atomic writes and a watcher that drains it on every poll cycle.

The Design

Each bot has an inbox directory at sessions/[name]/inbox/. A message is a JSON file dropped into that directory. The bot's watcher script scans the inbox on every 30-second poll, checks whether the bot is idle, and injects waiting messages via tmux send-keys.

No broker. No daemon. No network calls. The filesystem is the queue. The watcher is the consumer.

Three properties matter:

Atomic writes. Messages are written to a .tmp file first, then moved into the inbox directory. mv within the same filesystem is atomic. The receiving bot either sees a complete message file or nothing — never a partial write.

Idle injection only. The watcher checks whether the bot's Claude process is at a ready prompt before injecting. If Claude is mid-task, the message stays in the inbox and gets delivered on the next poll cycle. This prevents injecting a new task into an already-running one.

Offline delivery. The inbox persists on disk. If a bot is down when a message arrives, the message sits in the inbox until the bot restarts. The next drain cycle delivers it.

send.sh

send.sh takes four arguments: sender bot name, recipient bot name, message content, and an optional reply_to message ID.

#!/bin/bash
FROM="$1"
TO="$2"
CONTENT="$3"
REPLY_TO="${4:-}"

INBOX="/Users/mozimohidien/mozi/second_brain/sessions/$TO/inbox"
TS="$(date +%s%N)"
ID="${TS}-$$-${RANDOM}"
MSG="$INBOX/${ID}.msg"
TMP="$INBOX/${ID}.tmp"

mkdir -p "$INBOX"

ESC_CONTENT="$(printf '%s' "$CONTENT" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
printf '{ "id": "%s", "from": "%s", "to": "%s", "ts": "%s", "content": %s }\n' \
  "$ID" "$FROM" "$TO" "$TS" "$ESC_CONTENT" > "$TMP"
mv "$TMP" "$MSG"

echo "$ID"

The message filename encodes a timestamp, PID, and random number. This prevents collisions if two bots send to the same recipient simultaneously. The timestamp ensures messages drain in arrival order.

python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))' JSON-encodes the content string, handling quotes, newlines, and special characters. This matters when message content contains multi-line prompts or code.

send.sh prints the message ID to stdout. The sender can capture it for reply routing.

drain.sh

drain.sh is sourced by every bot's watch.sh. It runs on each poll cycle, after the bot's health check.

Pseudocode:

function drain_bot_inbox() {
    INBOX = "sessions/$BOT_NAME/inbox"

    if inbox is empty:
        return

    # Check pane readiness
    PANE_CONTENT = tmux capture-pane -t $SESSION -p

    if PANE_CONTENT matches /(esc to interrupt|working\.\.\.|tokens used|numbered dialog \[1\]|\[y\/n\])/i:
        # Bot is busy — leave messages for next cycle
        return

    # Process messages in order (sorted by filename = arrival order)
    for MSG_FILE in sorted(inbox/*.msg):
        CONTENT = parse JSON content field from MSG_FILE
        FROM = parse JSON from field
        ID = parse JSON id field

        # Build the injected prompt
        PROMPT = "[BOT-BUS] Message from $FROM (id: $ID):\n\n$CONTENT\n\n[Reply via: send.sh $BOT_NAME $FROM \"your reply here\" $ID]"

        # Inject into the tmux session
        tmux send-keys -t $SESSION "$PROMPT" Enter

        # Delete the message file
        rm -f $MSG_FILE

        # Wait for Claude to start processing before injecting the next message
        sleep 3

        # Re-check pane — if Claude started a task, stop draining
        PANE_CONTENT = tmux capture-pane -t $SESSION -p
        if PANE_CONTENT matches /(esc to interrupt|working)/i:
            break
    end
}

The readiness check is the critical piece. Claude's pane shows different text depending on state:

Ready for input: shows the prompt cursor
Mid-task: shows "esc to interrupt" or streaming output
Usage modal: shows numbered options

The drain function only injects when the pane is at a clean prompt. Everything else means Claude is busy. Messages queue and deliver on the next cycle.

Reply Routing

When drain.sh injects a message, it appends instructions for the receiving bot:

[BOT-BUS] Message from oper8 (id: 1720000000000-1234-5678):

I need the learning context for Mozi's current AI module — specifically what he's covered so far and what's next on the path. I'm briefing a client on Mozi's technical background.

[Reply via: send.sh life_tutor oper8 "your reply here" 1720000000000-1234-5678]

The receiving bot sees this as an ordinary prompt. It reads the instructions, forms a response, and calls send.sh as directed. The reply lands in the sender's inbox, with reply_to set to the original message ID so the sender can correlate it.

This requires Claude to follow the reply instruction reliably. In practice it does — the instruction is explicit and the format is consistent. The occasional failure (Claude answers but doesn't send the reply) is handled by the sender timing out and either re-sending or handling the missing reply gracefully.

A Real Usage Example: oper8 → life_tutor

Scenario: the oper8 bot is preparing a client briefing for a prospect interested in Mozi's technical background. It needs to know what Mozi has been studying in AI recently.

Step 1: oper8 sends a message to life_tutor

send.sh oper8 life_tutor "I need Mozi's current learning context — what AI topics has he covered recently and what is he working on next? I'm briefing Nexus Capital on his technical background."

This writes a file to /Users/mozimohidien/mozi/second_brain/sessions/life_tutor/inbox/1720000120000-4521-8833.msg:

{
  "id": "1720000120000-4521-8833",
  "from": "oper8",
  "to": "life_tutor",
  "ts": "1720000120000",
  "content": "I need Mozi's current learning context — what AI topics has he covered recently and what is he working on next? I'm briefing Nexus Capital on his technical background."
}

Step 2: life_tutor's watcher drain detects the message

On the next 30-second poll, drain_bot_inbox runs. The pane check passes (life_tutor is idle). The drain function reads the message and injects:

[BOT-BUS] Message from oper8 (id: 1720000120000-4521-8833):

I need Mozi's current learning context — what AI topics has he covered recently and what is he working on next? I'm briefing Nexus Capital on his technical background.

[Reply via: send.sh life_tutor oper8 "your reply here" 1720000120000-4521-8833]

Step 3: life_tutor processes and replies

Claude (life_tutor session) receives the prompt, reads LEARNING_PATH.md, forms a summary, and executes the reply:

send.sh life_tutor oper8 "Mozi completed the core Claude API module last week — tool use, multi-turn conversations, context management. Currently working through the agent orchestration patterns module. Next up: MCP server design and multi-agent coordination. Strong foundations; actively building production systems on top." 1720000120000-4521-8833

Step 4: oper8's watcher delivers the reply

The reply lands in /Users/mozimohidien/mozi/second_brain/sessions/oper8/inbox/1720000180000-7722-3341.msg. On oper8's next poll, the drain delivers it. The oper8 Claude session receives the context and continues building the client briefing.

Total latency: under 60 seconds (two watcher cycles maximum). No external infrastructure. No broker to maintain or fail.

Idle Safety in Practice

A bot injected mid-task causes immediate problems. Claude is streaming output for one task and suddenly receives a new prompt — the context merges, the outputs collide, both tasks produce garbage.

The readiness regex catches the common cases:

esc to interrupt — Claude is actively working
working... — task in progress indicator
tokens used — post-response summary, Claude may still be settling
Numbered dialog [1] — modal or confirmation prompt, not safe to inject
[y/n] — Claude is asking a yes/no question

If any of these appear in the captured pane content, the drain stops and all messages wait for the next cycle.

The sleep 3 between messages gives Claude time to start processing the first injected message before the next one arrives. Without it, two messages can land in the same prompt buffer and Claude reads them as one.

Failure Modes

Message never delivered. Check if the target bot's inbox directory exists and is writable. Check that drain_bot_inbox is being called in the target's watch.sh. Confirm the pane readiness check is not stuck (e.g., pane permanently showing "esc to interrupt" because Claude froze mid-task).

Duplicate delivery. The rm -f $MSG_FILE after injection handles this — once delivered, the file is gone. If you see duplicates, the delete is failing silently. Add error checking around the rm.

Garbled content. The python3 JSON encoding in send.sh handles most special characters. The failure mode is content that breaks JSON — usually an unescaped backslash or a very long string. Test with echo "$ID" | python3 -m json.tool if messages are arriving malformed.

Reply never received. Claude processed the message and answered but did not call send.sh. This happens when the injected instructions are too buried in a long conversation context. Keep the [Reply via: ...] instruction at the end of the injection, not the beginning — Claude reads to completion before acting.

Scaling the Pattern

Eight bots, any one of which can message any other. The inbox pattern scales without modification. Adding a new bot means creating its inbox directory. Nothing else changes.

The watcher architecture already handles the drain — it is part of every bot's standard watch.sh. The send and drain scripts are utilities shared across all sessions.

The pattern also composes with the screen lock and agent spawning patterns. A bot that needs to do something requiring screen access checks the lock, acquires it, does the work, releases it, and reports back via send.sh — all within the same architecture, no new infrastructure required.

For a system running entirely on a local machine, this is the right level of complexity: just enough to make bots collaborate reliably, nothing more.

The Orchestrator Pattern for Claude Agents: Delegating Everything, Owning Nothing

Mozi Mohidien — Wed, 22 Jul 2026 09:32:25 +0000

The Orchestrator Pattern for Claude Agents: Delegating Everything, Owning Nothing

by Mozi Mohidien

The most common mistake when building multi-agent systems with Claude is turning the orchestrator into a worker. It reads files. It edits code. It calls APIs directly. Within twenty turns, the orchestrator's context is bloated with tool output noise, the session is slow, and every response costs more than it should.

The fix is a strict rule: the orchestrator never acts. It only plans, delegates, and reviews.

The Core Rule

The orchestrator does exactly three things:

Understand the task and break it down
Brief and spawn agents to execute
Review what comes back and surface the result to the user (or re-brief if it's wrong)

Everything else — file edits, terminal commands, API calls, deployments, web searches, browser navigation — goes through a spawned agent. The orchestrator touches nothing directly.

This sounds simple. It requires discipline to maintain, because the temptation to "just do it inline" is constant. One inline file read feels harmless. Ten turns later, the session context contains 40KB of raw file content that gets re-read on every subsequent turn.

Why Context Cost Matters More Than You Think

For Fable (claude-fable-5), cost hits from two directions.

Input: every turn re-reads the entire session context. A conversation that has accumulated tool outputs from twelve previous turns re-reads all of that on turn thirteen. Context does not get cheaper as the session grows — it gets more expensive per turn.

Output: Fable's thinking tokens bill as output. Even a short response with a thinking budget burns output tokens. The longer the session, the more the model thinks to navigate the accumulated context.

This is why the orchestrator rule has financial weight, not just architectural weight. An orchestrator that stays clean — no inline tool calls, no accumulated raw output — keeps per-turn cost low throughout the session. An orchestrator that acts directly starts cheap and gets expensive fast.

Handling Context Overflow

Sessions eventually get long. The right response is not to keep going — it is to hand off cleanly and restart.

The pattern:

Append relevant updates to the brain files (MOZI.md, operate_with_intelligence.md, the relevant brief — whichever apply)
Write HANDOFF.md — the baton pass document
Touch a signal file that the watcher daemon is polling
The watcher sees the signal file, kills the current session, starts a fresh one

# Trigger the restart
touch ~/mozi/second_brain/.restart_laptop

The watcher picks this up within 30 seconds. The new session starts with zero tool noise in context. Brain files carry forward the relevant state.

HANDOFF.md: Baton Pass, Not Log

HANDOFF.md has one job: give the next session exactly what it needs to continue, nothing more.

Hard constraints: under 30 lines, three fields only.

# Handoff

## Done this session
- Rebuilt the oper8 bot start.sh after model env var broke Telegram server mode
- Updated LEARNING_PATH.md with new MCP module completion
- Cleaned stale files from /mozi/university/

## Next step
Deploy the updated general_fable bot and verify it processes messages

## Urgent
None

That is the entire document. No audit lists. No issue inventories. No historical context. No "also worth noting" sections.

The reason for the constraint: HANDOFF.md gets read on every session start. Every line is input tokens. A 200-line HANDOFF becomes a tax on every single turn of the next session. Keep it short.

The next session overwrites it entirely. It is never accumulated. It is never a log of what has happened over time. It tells the next session exactly one thing: where to pick up.

The Quality Gate

The orchestrator is the last reviewer before output reaches the user. If an agent's output is incomplete, wrong, or mediocre, the user should never see it.

When an agent returns:

Read the output critically
Ask: does this fully achieve what was asked?
If yes, surface it
If no: diagnose exactly why it failed, refine the brief, re-spawn

Common failure modes to check for: agent completed the task technically but missed the actual goal; output is correct but needs synthesizing with another agent's output before it's useful; agent hit a blocker and returned a partial result without flagging it clearly.

"I couldn't do it" from an agent is never an acceptable final answer without investigation. The orchestrator probes: what specifically failed? Was it a missing credential? Wrong file path? Tool error? Then it fixes the brief and tries again, or finds a different approach.

Only when all paths are genuinely exhausted does the orchestrator surface to Mozi: here is what was tried, here is the blocker, here is what he needs to do.

Model Selection for Spawned Agents

Not every agent needs the same model. Over-provisioning burns budget. Under-provisioning produces worse results.

The decision matrix:

Haiku — single-file reads, classification, simple lookups, anything with a short deterministic answer
Sonnet — coding, file edits, multi-step execution, most tasks
Opus — complex reasoning, architecture decisions, deep multi-step analysis requiring judgment
Fable — only when the agent itself needs orchestration capability (rare; spawning a Fable agent to orchestrate sub-agents is usually the wrong design)

# Spawning examples

# Quick lookup — haiku
Agent(
    model="haiku",
    description="Look up contact number",
    prompt="Read /Users/mozimohidien/mozi/second_brain/contacts.json and return the phone number for Ayesha Kader."
)

# Code edit — sonnet
Agent(
    model="sonnet",
    description="Edit start.sh model env var",
    prompt="Edit /path/to/sessions/oper8/start.sh. Change ANTHROPIC_MODEL from claude-sonnet-4-6 to claude-fable-5. Test that the file is valid bash syntax after."
)

# Architecture review — opus
Agent(
    model="opus",
    description="Review MCP server design",
    prompt="Review the design of the Telegram bridge MCP server at ~/.claude/plugins/telegram_bridge/server.ts. Identify any race conditions or failure modes in the polling loop."
)

The WhatsApp Flow Example

A concrete example of the full pattern: Mozi says "send a WhatsApp to Bilal saying the meeting is confirmed for Thursday at 3pm."

The orchestrator does not send the message. It does not look up the contact. Here is the flow:

Step 1: Read contacts.json to find Bilal's number. This is a simple lookup — haiku agent.

Agent(haiku): Read contacts.json, return phone number for "Bilal"
Result: +27821234567

Step 2: Brief a sonnet agent with everything it needs. No back-and-forth.

Agent(
    model="sonnet",
    description="Send WhatsApp to Bilal",
    prompt="""
    Send a WhatsApp message to +27821234567 (Bilal).
    Message: "Hey — meeting confirmed for Thursday at 3pm."

    Use this approach:
    osascript -e 'open location "whatsapp://send?phone=27821234567&text=Hey%20%E2%80%94%20meeting%20confirmed%20for%20Thursday%20at%203pm."'

    Run it and confirm it opens WhatsApp. Report back with success or failure and the exact error if it fails.
    """
)

Step 3: Review the result. Did WhatsApp open? Did the message send? If yes, tell Mozi it is done. If no, diagnose and try another approach (Playwright, direct API if configured).

The orchestrator never touched the terminal. It never read the contacts file directly. It planned, delegated both tasks cleanly, reviewed results, and reported.

Screen Lock Pattern

Some agents need to control the screen — browser navigation, clicking, form submission. Only one agent can do this at a time or they race each other.

Lock file: /Users/mozimohidien/mozi/second_brain/.screen_agent_active

Acquire before starting screen work:

# Check if another agent has the lock
if [ -f "/Users/mozimohidien/mozi/second_brain/.screen_agent_active" ]; then
    echo "Screen already locked by another agent. Aborting."
    exit 1
fi

# Acquire
touch /Users/mozimohidien/mozi/second_brain/.screen_agent_active

Release when done (always — even on failure):

# Release
rm -f /Users/mozimohidien/mozi/second_brain/.screen_agent_active

The orchestrator must never spawn two screen-active agents simultaneously. Before spawning an agent that needs screen access, check that no other screen agent is running. If the lock file exists, either wait or queue the task.

Cost Discipline Summary

Keep Fable orchestrators cheap:

CLAUDE_CODE_EFFORT_LEVEL=low in every Fable bot's start.sh. Never remove it.
Restart sessions early — after heavy agent cycles, not just when approaching context limits. A short session with a tight handoff costs less per turn than a long one.
No inline tool calls in the orchestrator — keep its context clean.
Write tight briefs. Every line in a CLAUDE.md or HANDOFF.md is re-read on every turn. Ruthlessly cut anything stale.

The orchestrator's job is thinking, not doing. Keep its context lean so the thinking stays sharp.

Running a Fleet of Telegram Bots on Claude Code: Per-Bot Sessions, MCP, and Auto-Restart

Mozi Mohidien — Wed, 22 Jul 2026 09:31:49 +0000

Running a Fleet of Telegram Bots on Claude Code: Per-Bot Sessions, MCP, and Auto-Restart

by Mozi Mohidien

Running one Telegram bot on Claude Code is straightforward. Running eight simultaneously — each with its own model, context, memory, and capabilities — without them trampling each other is an architecture problem most people hit after the second bot.

This article walks through the full stack: session isolation, the MCP plugin, auto-restart via launchd and tmux, and a subtle confirmation prompt bug that will silently break every bot you start without a workaround.

The Problem

Claude Code is a process. It loads context, runs tools, maintains state. If you run two bots in the same session, they share context. They see each other's messages. One bot's tool calls pollute the other's reasoning.

The solution: one bot per Claude Code session. Full isolation. Each bot is its own process, with its own working directory, its own MCP config, its own Telegram token.

But then you have eight processes to start, monitor, and restart. Manually doing that is not a system — it's a chore.

Architecture Overview

Each bot has its own session directory under second_brain/sessions/[name]/. Inside that directory:

start.sh — launches the Claude Code process with the right environment
watch.sh — runs in a loop, monitors the tmux session, restarts if dead
.mcp.json — tells Claude Code which MCP servers to load (Telegram bridge, others)

The Telegram bridge plugin lives at ~/.claude/plugins/telegram_bridge/server.ts. It is shared across all bots — each bot's .mcp.json points to the same file, but passes different environment variables (token, state dir). That is how one plugin supports eight bots without duplication.

Claude Code runs in a special server mode:

claude --dangerously-skip-permissions --dangerously-load-development-channels server:telegram

This mode keeps Claude running as a long-lived process, receiving Telegram messages via the MCP plugin and responding through it. Without server:telegram, Claude exits after each response.

start.sh

Every bot needs its own start.sh. The critical details: the bot token, the state directory (unique per bot — this is where Telegram session data lives), and the model.

#!/bin/bash
export TELEGRAM_BOT_TOKEN="[BOT_TOKEN]"
export TELEGRAM_STATE_DIR="/Users/you/.claude/channels/telegram_[BOTNAME]"
export ANTHROPIC_MODEL="claude-fable-5"
export CLAUDE_CODE_EFFORT_LEVEL=low
cd "/path/to/sessions/[BOTNAME]"
exec claude --dangerously-skip-permissions --dangerously-load-development-channels server:telegram

Two things worth calling out.

First: the model is set via export ANTHROPIC_MODEL=..., not via a --model flag. The --model flag breaks Telegram server mode. Claude Code's server mode has specific initialization behavior that the flag interferes with. Use the environment variable.

Second: CLAUDE_CODE_EFFORT_LEVEL=low for Fable bots. Fable (claude-fable-5) is the most capable but most expensive model. It bills thinking tokens as output. Setting effort to low reduces the thinking budget per turn, which keeps the weekly allocation from draining on routine bot responses. Do not remove this line.

.mcp.json

Each session directory has its own .mcp.json. Claude Code reads this file when it starts and loads the listed MCP servers.

{
  "mcpServers": {
    "telegram": {
      "command": "bun",
      "args": ["run", "/path/to/.claude/plugins/telegram_bridge/server.ts"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "[BOT_TOKEN]",
        "TELEGRAM_STATE_DIR": "/path/to/.claude/channels/telegram_[name]"
      }
    }
  }
}

The plugin is launched via bun. The env block passes the bot-specific token and state directory to the plugin process. The plugin handles everything: long-polling Telegram for new messages, surfacing them to Claude as tool results, and providing a reply tool Claude uses to respond.

Because each bot's .mcp.json passes a different TELEGRAM_STATE_DIR, their session data never collides. Telegram's polling state, message history cursor, and any plugin-side data are fully isolated per bot.

tmux + launchd: The Auto-Restart Pattern

Each bot runs inside a named tmux session. This matters for two reasons: tmux sessions survive terminal disconnects, and tmux send-keys lets a watcher script inject input into the running Claude process without attaching to it.

Nine launchd plists (com.mozi.[name]-watcher) run continuously on startup. Each one runs watch.sh for its corresponding bot. The watcher polls every 30 seconds.

The core loop in watch.sh:

while true; do
    if [ -f "$SIGNAL_FILE" ]; then
        rm -f "$SIGNAL_FILE"
        sleep 60
        $TMUX kill-session -t "$SESSION" 2>/dev/null
        $TMUX new-session -d -s "$SESSION" "$START_CMD"
        sleep 15
        $TMUX send-keys -t "$SESSION" "1" Enter
        sleep 5
        $TMUX send-keys -t "$SESSION" "" Enter
    fi

    if ! $TMUX has-session -t "$SESSION" 2>/dev/null; then
        sleep 5
        if ! $TMUX has-session -t "$SESSION" 2>/dev/null; then
            $TMUX new-session -d -s "$SESSION" "$START_CMD"
            sleep 15
            $TMUX send-keys -t "$SESSION" "1" Enter
        fi
    else
        detect_and_dismiss_usage_modal "$SESSION" "$LOG_FILE"
        drain_bot_inbox
    fi
    sleep 30
done

Two paths: signal file (intentional restart, triggered by another bot or admin command) and crash detection (tmux session gone). Both paths start a new tmux session running start.sh, then wait 15 seconds and send "1" Enter.

That 15-second wait and keypress is the fix to the most important bug in this setup.

The Confirmation Prompt Bug

When Claude Code starts, it shows a confirmation prompt asking whether to proceed in the current mode. Without user input, it sits there. The bot technically starts but never processes any Telegram messages because Claude is waiting for the human to press a key.

The naive fix is skipDangerousModePermissionPrompt: true in settings.json. This does not reliably suppress the prompt in server mode. Do not rely on it.

The actual fix: after starting the tmux session, wait long enough for the prompt to appear (15 seconds covers even slow startup), then send the keypress:

$TMUX new-session -d -s "$SESSION" "$START_CMD"
sleep 15
$TMUX send-keys -t "$SESSION" "1" Enter

tmux send-keys injects input into the pane as if a user typed it. The bot receives the "1" Enter, dismisses the prompt, and starts processing messages.

Without this, you get a bot that shows as running in tmux list-sessions but never responds. It is a silent failure. The logs look clean. Telegram messages arrive and pile up. Nothing processes them.

Usage Limit Modal Auto-Dismiss

Fable bots can hit usage limits mid-session. Claude Code displays an interactive modal asking what to do: continue with Fable, switch to Sonnet, or stop. Without auto-dismissal, the bot freezes until a human intervenes.

The detect_and_dismiss_usage_modal function in watch.sh handles this. It:

Captures the current tmux pane content
Looks for phrases like "limit", "credits", or numbered-option markers
Prefers "Continue with Fable" — extracts the digit from the option line and sends it
Falls back to "Switch to Sonnet" if Fable continuation is unavailable
Falls back to sending "1" if no specific option is recognized
Logs every auto-dismiss event to usage_modal.log with a timestamp

This runs on every poll cycle (every 30 seconds). A modal that appears between poll cycles goes undetected for at most 30 seconds, then gets auto-dismissed. The bot continues without human intervention.

Access Control

Each bot has an access list at ~/.claude/channels/[name]/access.json. This is an allowlist of Telegram user IDs. Messages from users not on the list are silently ignored by the plugin.

The structure is straightforward — a JSON object with an array of permitted user IDs. The plugin checks each incoming message against this list before surfacing it to Claude.

This matters when a bot's token is compromised or shared accidentally. Without the allowlist, anyone who finds the token can interact with your bots and run arbitrary tool calls.

Setup Checklist

Per bot:

[ ] Create sessions/[name]/ directory
[ ] Write start.sh with unique TELEGRAM_BOT_TOKEN, TELEGRAM_STATE_DIR, and correct ANTHROPIC_MODEL
[ ] Copy watch.sh from the canonical template — do not write it from scratch
[ ] Write .mcp.json pointing to the shared plugin with bot-specific env vars
[ ] Create ~/.claude/channels/[name]/access.json with permitted Telegram user IDs
[ ] Create the TELEGRAM_STATE_DIR directory
[ ] Test start.sh manually in a terminal first — confirm Claude starts and the prompt appears
[ ] Verify the "1" keypress dismisses the prompt and the bot logs message receipt

For the watcher:

[ ] Write a launchd plist com.mozi.[name]-watcher that runs watch.sh at startup
[ ] Load with launchctl load ~/Library/LaunchAgents/com.mozi.[name]-watcher.plist
[ ] Confirm it appears in launchctl list | grep mozi

Verify everything works:

[ ] Send a test message from an allowlisted Telegram account
[ ] Confirm the bot replies
[ ] Kill the tmux session manually — confirm the watcher restarts it within 60 seconds
[ ] Check that the restart sends the "1" keypress automatically

Common Failure Modes

Bot starts but never responds. Almost always the confirmation prompt. Attach to the tmux session (tmux attach -t [name]) and look. If you see a prompt waiting for input, the send-keys timing is off. Increase the sleep before the keypress.

Two bots receiving the same messages. TELEGRAM_STATE_DIR is shared or identical. Each bot must have a unique state directory. Check the env in .mcp.json and the export in start.sh.

Bot crashes repeatedly. Check the launchd logs and the tmux pane output before it exits. Most crashes are MCP server startup failures — usually a missing bun in PATH, wrong plugin path, or malformed .mcp.json.

Watcher not restarting dead sessions. Confirm the launchd plist is loaded and running. Check launchctl list com.mozi.[name]-watcher. If the tmux binary path in watch.sh is wrong (common when tmux is installed via Homebrew and PATH differs in launchd context), set an absolute path.

The architecture scales linearly. Each new bot is the same pattern: a directory, three files, one launchd plist. The shared plugin means there is no per-bot plugin code to maintain. The watcher handles failures automatically. Once the pattern is running, adding bot number nine is twenty minutes of work.