Cocoindex Tutorial: Build a Persistent GitHub Monitor Agent in 10 Minutes

👋 Let's Build a Persistent Agent

I'm going to show you how to set up Cocoindex and build a real agent that maintains state across sessions. This takes about 10 minutes. Grab a coffee.

What We'll Build

A research agent that monitors GitHub repos for new issues, summarizes them, and remembers what it already processed — so it only summarizes new issues, never repeats itself.

🔧 Step 1: Install Cocoindex

I tried two approaches, and here's what worked for me. The pip install route is the smoothest:

pip install cocoindex

If you prefer Docker (and I usually do for isolation):

docker pull cocoindex/cocoindex-code:latest

Wait — this is where I messed up first time: I tried to run the Docker image directly and got confused because it expects a Python script mount. Don't do that. Use pip for development, Docker for production.

📝 Step 2: Define Your Dataflow

Create a file called github_monitor.py. Here's where Cocoindex shines — you define what you want, not how to process it:

import cocoindex
import httpx
from datetime import datetime, timedelta

@cocoindex.flow()
def github_monitor_flow():
    # Define what data we care about
    issues = cocoindex.source(
        "github_issues",
        query="org:cocoindex-io type:issue updated:>2026-01-01"
    )
    
    # Only process new/updated issues (incremental!)
    new_issues = issues.filter(lambda i: i["updated_at"] > last_run)
    
    # Summarize each new issue
    summaries = new_issues.map(summarize_issue)
    
    # Store results persistently
    return summaries.collect("summaries")

def summarize_issue(issue):
    # Your LLM call here
    return {
        "title": issue["title"],
        "summary": f"Issue #{issue['number']}: {issue['title'][:50]}...",
        "url": issue["html_url"],
        "processed_at": datetime.now().isoformat()
    }

Notice: no manual state management, no checkpoint files, no database setup. Cocoindex handles all of that automatically.

🏃 Step 3: Run It Once

python github_monitor.py

It runs, collects issues, processes them. If you see output — it worked. If not, check your GitHub token.

Now here's the magic part. Run it again:

python github_monitor.py

Second run? Near instant. Because Cocoindex remembered what it processed and only looks for new data. No duplicate work. No wasted API calls.

🧪 Step 4: Test Failure Recovery

This is where I accidentally discovered Cocoindex's best feature. I killed the process mid-way (CTRL+C) during a long processing run:

# Kill the process
# ...panic for 5 seconds...
# Run again
python github_monitor.py

It picked up exactly where it left off. The processed issues were saved, the half-processed ones were re-done cleanly. I literally said "wow" out loud.

⚡ Performance Comparison

💡 What I Wish I Knew Earlier

• Use pip, not Docker for dev — Docker adds complexity for local testing. Docker is great for production deployments.
• Name your flows — @cocoindex.flow("my_flow_name") makes debugging much easier
• Cold start is normal — The first run always takes full time. Don't panic. The second run is where you see the magic.
• Check the logs — Cocoindex logs what it skipped, what it processed, and why. Super helpful when something unexpected happens.

🎯 Final Verdict

Cocoindex solves a real pain point that I've been workaround-ing with custom cache layers and database checkpoints for years. It's not flashy — there's no UI, no dashboard, no pretty charts. But it does one thing exceptionally well: make long-running agents actually viable in production.

If you're building agents that run for more than 5 minutes, you need this in your stack.