DEV Community: Anshu Mandal

Building CrossCap (Open-Source Screen Studio Alternative) with GitHub Copilot Workflows

Anshu Mandal — Mon, 16 Feb 2026 05:17:03 +0000

This is a submission for the GitHub Copilot CLI Challenge

What I Built

I built CrossCap, a free and open-source desktop app for screen recording and lightweight video editing.

CrossCap is designed for creators and developers who want to make clean product demos and walkthroughs without paying for expensive subscription software. It records your screen/app, then lets you edit the recording with zooms, crop, annotations, backgrounds, and export presets.

What CrossCap does

Record screen or app windows
Add manual zoom regions with timeline control
Auto-suggest zoom regions from cursor telemetry
Crop recordings
Add text/image/arrow annotations
Apply backgrounds (wallpapers, gradients, solid colors, custom image)
Trim clip sections
Export to MP4 or GIF in multiple aspect ratios/resolutions

Tech stack

Electron 39 (desktop shell)
React 18 + TypeScript + Vite
Zustand (editor state)
PixiJS + GSAP (canvas preview and zoom animation)
WebCodecs + mp4box (MP4 export pipeline)
gif.js (GIF export)
Biome + Vitest

One of the most interesting parts is that the export pipeline is browser-tech based (WebCodecs + mp4box), so the app can render/edit/export without depending on a heavy native FFmpeg workflow for the main path.

Demo

Project links

Project Website : https://crosscap-website.vercel.app

Releases: https://github.com/prime399/CrossCap/releases

prime399 / CrossCap

Warning

This is very much in beta and might be buggy here and there (but hope you have a good experience!).

CrossCap

CrossCap is your free, open-source alternative to Screen Studio (sort of).

If you don't want to pay $29/month for Screen Studio but want a much simpler version that does what most people seem to need, making beautiful product demos and walkthroughs, here's a free-to-use app for you. CrossCap does not offer all Screen Studio features, but covers the basics well!

Screen Studio is an awesome product and this is definitely not a 1:1 clone. CrossCap is a much simpler take, just the basics for folks who want control and don't want to pay. If you need all the fancy features, your best bet is to support Screen Studio (they really do a great job, haha). But if you just want something free (no gotchas) and open, this project…

View on GitHub

prime399/CrossCap | DeepWiki

This page describes what CrossCap is, its key features, the main technologies it uses, and a high-level picture of how its three window types and core workflows fit together. For architectural details

deepwiki.com

My Experience with GitHub Copilot CLI (and Copilot Templates)

GitHub Copilot was most useful for speeding up repetitive implementation work while I stayed focused on architecture and correctness.

For a project like CrossCap (Electron + React + canvas rendering + export pipeline), the biggest productivity gains came from combining:

good repository context/instructions
reusable prompt templates
small, scoped prompts for multi-step tasks
manual validation (lint/tests/runtime checks)

How I used Copilot in this project

1) Repository guidance as a “template” for better output

I kept project-specific guidance in a Copilot-friendly instructions file and repo docs (stack, commands, architecture, coding conventions, validation steps).

That mattered a lot because CrossCap has:

a multi-window Electron architecture
a shared React app with ?windowType= routing pattern
a Zustand store with persisted/non-persisted state rules
an export pipeline split across orchestrator/decoder/renderer/muxer files
security-sensitive IPC handlers in the Electron main process

When Copilot has that context, suggestions are more likely to match the project’s actual patterns instead of generic React/Electron examples.

2) Prompt templates for repeatable tasks

I used a template-style prompting approach for common workflows such as:

Refactor a component without changing behavior
Add a feature to a timeline/editor panel
Generate tests for a pure utility function
Document a subsystem before changing it
Review a diff for regressions and edge cases

This works especially well in large files/components where vague prompts produce noisy output.

3) Breaking complex work into smaller prompts

For export pipeline and playback work, asking Copilot to solve everything at once was less effective than prompting in phases:

inspect current behavior
identify likely failure points
patch one module
add/adjust tests
re-check types/lint

That kept the generated changes smaller and easier to review.

4) Using Copilot for “drafting” and me for “decision-making”

Copilot was great for drafting:

boilerplate types
UI control wiring
repetitive handlers
initial test cases
docs text / checklists

I still made the final calls on:

architecture boundaries
export pipeline behavior
state model changes
IPC security constraints
performance-sensitive logic

GitHub Copilot Templates I Used (Practical Examples)

Below are the kinds of template prompts that worked well for this codebase.

A) Feature implementation template (timeline/editor)

Task: Add/modify a feature in CrossCap's video editor.

Context:
- Stack: Electron + React + TypeScript + Zustand
- State source of truth: useEditorStore (avoid introducing local state for persisted editor settings)
- UI domain: src/components/video-editor/
- Timeline components live under src/components/video-editor/timeline/
- Keep imports using @/ aliases
- Preserve existing behavior unless requested

Steps:
1. Identify the exact file(s) responsible.
2. Explain the current flow briefly.
3. Propose a minimal patch.
4. Implement only the requested change.
5. List validations to run (types/lint/tests if applicable).

Advantage: this reduces “AI wandering” and keeps edits aligned with the project’s state and folder conventions.

B) Export pipeline bugfix template

Investigate a bug in CrossCap export (MP4/GIF).

Constraints:
- Export orchestration is in lib/exporter/exportOrchestrator.ts
- Shared frame rendering logic is in lib/exporter/frameRenderer.ts
- Prefer minimal changes
- Do not change output format behavior unless necessary
- Explain root cause before patching

Output format:
- Root cause
- Patch summary
- Risks / edge cases
- Validation steps

Advantage: this makes Copilot focus on diagnosis first, not speculative rewrites.

C) Test generation template (utility functions)

Write Vitest tests for a pure TypeScript utility in CrossCap.

Requirements:
- Test behavior, not implementation details
- Include edge cases and invalid inputs if the function handles them
- Keep tests colocated and readable
- Do not mock internal logic unnecessarily

First, list test cases. Then write the tests.

Advantage: better test coverage and fewer brittle tests.

Why Copilot Was Useful Here (Research-backed + Practical)

I wanted this write-up to be more than personal opinion, so I checked both GitHub Copilot docs (via Context7) and broader sources via Exa.

What I found in the docs (Context7 + GitHub Docs)

GitHub’s recent Copilot documentation increasingly emphasizes customization, not just autocomplete:

Repository-wide custom instructions (.github/copilot-instructions.md) for persistent project guidance
Path-specific instructions (.instructions.md) for targeted rules
Prompt files (reusable prompts for common tasks)
Custom agents / agent profiles for specialized workflows

That maps directly to what helps in a codebase like CrossCap: encode the architecture and conventions once, then reuse prompt patterns across feature work.

Best Copilot use cases in this project

UI scaffolding for editor controls and settings panels
Refactoring assistance in large React/TS components
Test drafting for pure utility logic in the export subsystem
Documentation and internal notes for subsystems before changes
Small migration chores (types, props, repetitive handlers)

Where human judgment mattered most

performance-sensitive video/export behavior
Electron IPC and security boundaries
state persistence/rehydration logic
avoiding regressions in timeline + playback interactions

What Worked Best (Practical Tips)

1) Give Copilot architecture before asking for code

The better the project context, the better the suggestions. In CrossCap, naming the exact subsystem (timeline, export orchestrator, store, IPC handler) improved results immediately.

2) Ask for a patch plan first on risky changes

For export pipeline or state persistence changes, asking for a brief diagnosis + plan before code avoided over-large patches.

3) Use reusable prompt templates

Prompt templates made my Copilot sessions more consistent, especially when returning to the project after a break.

4) Validate every generated change

Copilot accelerates implementation, but lint/tests/runtime checks are still the source of truth.

Final Thoughts

GitHub Copilot was most valuable on CrossCap when I treated it as a developer accelerator, not an autopilot:

I provided clear project conventions and architecture context
I reused prompt templates for recurring workflows
I kept prompts small and task-specific
I validated everything against the real app behavior

That combination made it much easier to move faster on a complex desktop app with a custom editor and export pipeline while keeping the codebase coherent.

If you’re building a medium-to-large app, my biggest recommendation is simple: invest in instructions + prompt templates first. The quality of Copilot output improves dramatically when the tool understands how your project is supposed to work.

References (researched with Context7 + Exa)

GitHub Docs / Copilot docs

Prompt files: https://docs.github.com/en/copilot/tutorials/customization-library/prompt-files
Prompt engineering for Copilot Chat: https://docs.github.com/en/copilot/concepts/prompting/prompt-engineering
About custom agents: https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-custom-agents
Copilot coding agent customization / instructions (repo-wide instructions guidance): https://docs.github.com/en/copilot/tutorials/coding-agent/get-the-best-results

Research / productivity & quality writeups

GitHub Blog (code quality study): https://github.blog/news-insights/research/does-github-copilot-improve-code-quality-heres-what-the-data-says
GitHub Blog (enterprise/Accenture study): https://github.blog/news-insights/research/research-quantifying-github-copilots-impact-in-the-enterprise-with-accenture
MIT field experiment write-up (Copilot productivity effects): https://mit-genai.pubpub.org/pub/v5iixksv/release/2
ZoomInfo experience report (arXiv HTML): https://arxiv.org/html/2501.13282v1

DevFlow: API testing tool made with UNO.

Anshu Mandal — Mon, 08 Dec 2025 07:13:14 +0000

This is a submission for the AI Challenge for Cross-Platform Apps - AI Acceleration

What I Built

DevFlow is a full-featured cross-platform API client application, similar to Postman or Hoppscotch, built entirely with Uno Platform. It enables developers to test REST APIs, GraphQL endpoints, and real-time connections (WebSocket/SSE) from a single, unified interface that runs everywhere.

The application demonstrates how modern AI tooling combined with Uno Platform's MCP (Model Context Protocol) servers can dramatically accelerate cross-platform development, taking what would traditionally be weeks of work and compressing it into days.

Key Features

Feature	Description
REST Client	Full HTTP method support (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)
GraphQL Testing	Query editor with syntax support
Real-time Connections	WebSocket and Server-Sent Events (SSE)
Authorization	Bearer Token, Basic Auth, API Key support
Response Viewer	JSON formatting, raw view, and headers inspection
Cross-Platform	Single codebase for all platforms

Platform Support

Platform	Architecture	Status
Windows	x64, ARM64	Supported
macOS	ARM64 (Apple Silicon), x64	Supported
Linux	AMD64 (x64)	Supported
WebAssembly	Browser-based	Supported

Demo

GitHub Repository:

prime399 / DevFlow

DevFlow

A cross-platform API client built with Uno Platform

Live Demo (WebAssembly) • Download • Features • Installation

Overview

DevFlow is a full-featured, cross-platform API client application similar to Postman or Hoppscotch. Built entirely with Uno Platform, it runs on Windows, macOS, Linux, and WebAssembly from a single codebase.

Test REST APIs, GraphQL endpoints, and real-time connections (WebSocket/SSE) from a unified, modern interface with a beautiful dark theme.

Live Demo

Try DevFlow instantly in your browser - no installation required:

devflow.primefolio.tech

Downloads

Download the latest release for your platform:

GitHub Releases

Platform	Architecture	Download
Windows	x64, ARM64	Latest Release
macOS	ARM64 (Apple Silicon)	Latest Release
Linux	AMD64 (x64)	`.deb`, `.rpm` packages
WebAssembly	Browser	Live Demo

Features

REST Client

Full HTTP method support: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
Query parameters editor with enable/disable toggles
Custom headers management
Request body editor with…

View on GitHub

You can test it without installing any exe by using WASM version here:

devflow.primefolio.tech

Else you can download supported OS latest release from the Releases page:
Github Release Page

Running DevFlow

# Clone the repository
git clone https://github.com/prime399/DevFlow.git
cd DevFlow

# Run on Desktop (Windows/macOS/Linux)
dotnet run --project DevFlow/DevFlow.csproj -f net10.0-desktop

# Run on WebAssembly
dotnet run --project DevFlow/DevFlow.csproj -f net10.0-browserwasm

AI Tooling in Action

This project showcases the power of contextual AI acceleration. GitHub Copilot with Uno Platform MCP integration was my primary development companion throughout this project.

GitHub Copilot with Uno Platform MCP

The real game-changer was GitHub Copilot integrated with Uno Platform's MCP servers. This combination provided context-aware assistance that understood not just general .NET development, but specifically how to build Uno Platform applications correctly.

What made this powerful was Copilot's ability to:

Search Uno Platform documentation in real-time via uno_platform_docs_search
Test my locally running app using the App MCP tools
Validate UI changes by capturing screenshots and inspecting the visual tree
Provide grounded guidance based on official Uno Platform best practices

MCP Tools Used Throughout Development

Here's the complete list of Uno Platform MCP tools that accelerated my workflow:

Remote MCP Tools (Documentation & Guidance)

Tool	Purpose
`uno_platform_docs_search`	Search Uno Platform documentation for specific topics
`uno_platform_docs_fetch`	Retrieve complete documentation pages
`uno_platform_agent_rules_init`	Initialize agent with Uno development best practices
`uno_platform_usage_rules_init`	Prime the agent with Uno API usage patterns

Local App MCP Tools (Runtime Interaction)

Tool	Purpose
`uno_app_get_runtime_info`	Get app info (PID, OS, Platform)
`uno_app_get_screenshot`	Capture screenshot of running app
`uno_app_pointer_click`	Click at X,Y coordinates
`uno_app_key_press`	Type individual keys with modifiers
`uno_app_type_text`	Type strings into input controls
`uno_app_visualtree_snapshot`	Get textual representation of visual tree
`uno_app_element_peer_default_action`	Execute automation peer actions
`uno_app_close`	Close the running app

Using App MCP and Uno Platform MCP

Setting Up the MCP Servers

Uno Platform provides two MCP servers that transformed my development workflow:

{
  "servers": {
    "uno": {
       "url": "https://mcp.platform.uno/v1"
    },
    "uno-app": {
       "command": "dnx",
       "args": ["-y", "uno.devserver", "--mcp-app"]
    }
  }
}

How MCP Docs Search Accelerated Development

The uno_platform_docs_search tool was invaluable throughout development. Here are concrete examples of how it helped:

Challenge 1: Language Preference and Localization

When implementing language preference selection mode for the application settings, I was unsure about Uno Platform's recommended approach. A simple query to the MCP:

"How to implement language preference selection in Uno Platform?"

The MCP documentation search returned detailed guidance on using Uno.Extensions.Localization with IStringLocalizer, saving me hours of research.

Challenge 2: Syntax Highlighting for Code Editor

Building the CodeEditorControl required understanding how to implement syntax highlighting within Uno's rendering model.

The MCP search for

"What's the best Syntax Highlighting Code Editor supported in UNO"
pointed me to the correct approach using Run elements:

<TextBlock FontFamily="{StaticResource MonospaceFontFamily}">
    <Run Text="{x:Bind LineNumber}" Foreground="{StaticResource TextMutedBrush}"/>
    <Run Text="  "/>
    <Run Text="{x:Bind Content}" Foreground="{StaticResource TextPrimaryBrush}"/>
</TextBlock>

Challenge 3: HttpKiota for REST API Support

The built-in HttpKiota feature was a revelation. When I queried the MCP about HTTP client best practices, it guided me toward using IHttpClientFactory with proper dependency injection. Here's the actual configuration from my App.xaml.cs:

// App.xaml.cs - HTTP Client Configuration
.UseHttp((context, services) => {
#if DEBUG
    // DelegatingHandler will be automatically injected for debugging
    services.AddTransient<DelegatingHandler, DebugHttpHandler>();
#endif
    // Configure HttpClient for API with base URL from configuration
    var apiBaseUrl = context.Configuration["AppConfig:ApiBaseUrl"] ?? "https://localhost:7192";
    services.AddHttpClient<Services.IDataItemService, Services.DataItemService>(client =>
    {
        client.BaseAddress = new Uri(apiBaseUrl);
    });

    // Named client for the API Tester feature
    services.AddHttpClient("ApiTester");
})

This pattern enabled efficient connection pooling and proper lifecycle management across all platforms.

App MCP: Testing My Locally Running Build

One of the most impressive capabilities was using GitHub Copilot with App MCP to test my locally running DevFlow build. Instead of manually clicking through the UI to verify functionality, Copilot could interact with the running application directly.

Live App Testing with Mock API Endpoints

I used JSONPlaceholder to validate DevFlow's REST client. Here's how Copilot automated the testing workflow:

# Copilot's Automated Testing Sequence

1. uno_app_get_runtime_info    → Confirmed DevFlow running (PID: 4912, Platform: Desktop)
2. uno_app_get_screenshot      → Captured initial UI state
3. uno_app_type_text           → Entered: "https://jsonplaceholder.typicode.com/posts/1"
4. uno_app_pointer_click       → Clicked Send button at (850, 45)
5. uno_app_get_screenshot      → Captured response - Status 200 visible
6. uno_app_visualtree_snapshot → Verified ResponseViewer populated correctly

UI Feedback During Agentic Coding

The uno_app_get_screenshot and uno_app_visualtree_snapshot tools provided immediate visual feedback during development. When I asked Copilot to "add a status badge to the response viewer," it could:

Make the XAML changes via Hot Reload
Capture a screenshot to verify the change
Inspect the visual tree to confirm the StatusBadge element rendered correctly

Copilot: "I've added the StatusBadge. Let me verify it rendered correctly..."

→ uno_app_get_screenshot: [UI captured]
→ uno_app_visualtree_snapshot:
   └── ResponseViewerControl
       ├── Grid
       │   ├── StatusBadge (Border)
       │   │   └── TextBlock: "200 OK"
       │   ├── TabView: [Body] [Headers] [Raw]
       │   └── CodeEditorControl
       └── ...

Copilot: "Confirmed - StatusBadge is rendering with '200 OK' text."

HTTP Method Testing Automation

Copilot systematically tested all HTTP methods against the mock API:

Method	Endpoint	Action	Result
GET	`/posts/1`	`uno_app_pointer_click` on method dropdown → select GET	200 OK
POST	`/posts`	`uno_app_type_text` JSON body → Send	201 Created
PUT	`/posts/1`	Switch method, update body → Send	200 OK
DELETE	`/posts/1`	Switch method → Send	200 OK

This automation caught a UI regression where the response headers weren't clearing between requests - something I would have missed with manual testing.

The uno-check Tool: A Lifesaver for Cross-Platform Development

One of the most valuable tools in my development journey was uno-check. During initial setup, I encountered build failures that were difficult to diagnose. Running:

dotnet tool install -g uno.check
uno-check

The tool identified that I was missing the wasm-tools workload and had an outdated .NET SDK. It automatically offered to fix these issues:

# uno-check detected and fixed:
# - Missing wasm-tools workload
# - Outdated Android SDK components  
# - Incorrect workload versions

uno-check --target desktop --target web

This automated environment validation saved significant debugging time and ensured consistent builds across my development machines.

Cross-Platform Reach

DevFlow runs on 6 target platforms from a single codebase:

Project Configuration

<Project Sdk="Uno.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net10.0-desktop;net10.0-browserwasm</TargetFrameworks>
    <OutputType>Exe</OutputType>
  </PropertyGroup>

  <ItemGroup>
    <!-- Uno Features enabled -->
    <UnoFeatures>
      Material;
      Toolkit;
      MVUX;
      Navigation;
      HttpKiota;
      ThemeService;
      SkiaRenderer;
    </UnoFeatures>
  </ItemGroup>
</Project>

Platform-Specific Stats

Metric	Desktop	WebAssembly
Cold Start	~1.5s	~3-4s
Hot Reload	Instant	N/A
HTTP Requests	Native speed	Slightly slower
Memory Usage	~150MB	Browser-dependent

The SkiaSharp renderer ensures pixel-perfect consistency across all platforms, meaning the UI looks identical whether running on Windows, macOS, Linux, or in a browser.

Development Experience

What Contextual AI Changed

The combination of GitHub Copilot with Uno Platform MCP fundamentally transformed my development workflow:

Before AI Acceleration

Manually searching documentation
Trial-and-error for platform-specific behaviors
Hours spent on XAML styling issues
Debugging build configuration problems

After AI Acceleration

Instant, contextual documentation via MCP
AI-guided platform-specific implementations
Rapid UI iteration with Hot Reload + AI suggestions
Automated environment validation with uno-check

The MVUX Pattern with AI Assistance

The MCP was particularly helpful when learning Uno's MVUX pattern. When I asked about reactive state management, it provided exactly the right guidance:

public partial record RestRequestViewModel
{
    // State management with MVUX
    public IState<string> ResponseBody => State<string>.Value(this, () => string.Empty);
    public IState<int> StatusCode => State<int>.Value(this, () => 0);

    // Updating state
    public async Task SendRequest(CancellationToken ct)
    {
        var response = await _httpClient.SendAsync(request, ct);
        await ResponseBody.UpdateAsync(_ => await response.Content.ReadAsStringAsync(), ct);
        await StatusCode.UpdateAsync(_ => (int)response.StatusCode, ct);
    }
}

Reusable Control Architecture

With AI assistance, I developed a modular architecture with reusable controls:

Controls/
├── KeyValueEditorControl.xaml    # Reusable for Parameters/Headers
├── CodeEditorControl.xaml        # Code editor with line numbers
├── ResponseViewerControl.xaml    # Response display with tabs
└── AuthorizationEditorControl.xaml # Auth configuration panel

The IKeyValueItem interface pattern was suggested by the AI when I explained I needed to reuse the same table editor for both parameters and headers:

public interface IKeyValueItem : INotifyPropertyChanged
{
    Guid Id { get; }
    bool IsEnabled { get; set; }
    string Key { get; set; }
    string Value { get; set; }
    string Description { get; set; }
}

What Surprised Me Most

1. The Speed of Context-Aware AI

Traditional documentation searches require parsing through pages of content. With Uno Platform MCP, the AI agent already understood the context of my project and could provide targeted, actionable guidance instantly.

2. Hot Reload Actually Works

$env:DOTNET_MODIFIABLE_ASSEMBLIES = "debug"
dotnet run -f net10.0-desktop

XAML Hot Reload worked flawlessly for style changes, dramatically speeding up UI iteration. Combined with AI suggestions, I could prototype and refine UI components in minutes rather than hours.

3. Single Codebase Reality

I was skeptical that "write once, run everywhere" would actually work. It did. The same XAML and C# code runs on Windows, macOS, Linux, and WebAssembly without platform-specific modifications.

Technical Highlights

Custom Theming with Catppuccin Mocha

DevFlow uses a custom dark theme based on Catppuccin Mocha, defined in centralized resource dictionaries:

<!-- Styles/AppTheme.xaml -->
<Color x:Key="SurfaceColor">#1E1E2E</Color>
<Color x:Key="TextPrimaryColor">#CDD6F4</Color>
<Color x:Key="AccentPrimaryColor">#89B4FA</Color>

<SolidColorBrush x:Key="HttpGetBrush" Color="#94E2D5"/>
<SolidColorBrush x:Key="HttpPostBrush" Color="#F9E2AF"/>
<SolidColorBrush x:Key="HttpDeleteBrush" Color="#F38BA8"/>

Real-time Connection Services

The WebSocket and SSE implementations use a common interface, allowing easy switching between connection types:

public interface IRealtimeConnectionService
{
    bool IsConnected { get; }
    event EventHandler<string>? MessageReceived;

    Task ConnectAsync(string url, CancellationToken ct = default);
    Task SendMessageAsync(string message, CancellationToken ct = default);
    Task DisconnectAsync(CancellationToken ct = default);
}

Conclusion

Building DevFlow demonstrated that AI-accelerated development with Uno Platform MCP servers is not just a productivity boost, it is a paradigm shift. The combination of:

Uno Platform MCP for context-aware documentation
App MCP for runtime interaction, testing, and UI validation
uno-check for environment troubleshooting
Hot Reload for rapid UI iteration
GitHub Copilot as the AI agent orchestrating all MCP tools

This stack enabled me to build a production-quality, cross-platform API client that runs on Windows, macOS, Linux, and WebAssembly from a single codebase, in a fraction of the time traditional development would require.

The future of cross-platform development is here, and it is powered by AI.

Resources

Built with Uno Platform 6.4.26 on .NET 10.0

I Built Convodb So You Can Talk to Your Database (And It Talks Back With 4 AI Agents)

Anshu Mandal — Mon, 10 Nov 2025 06:08:08 +0000

This is a submission for the TigerData Agentic Postgres Hackathon Challenge

When PostgreSQL Met AI Agents (And I Went Down the Rabbit Hole) 🤯

So there I was, scrolling through dev.to, when I saw the TigerData Agentic Postgres hackathon announcement. My first thought? "Cool, another database." My second thought, after reading for 5 minutes? "WAIT, DATABASES CAN DO THAT?!" 🤩

Let me tell you about the most exciting research rabbit hole I've gone down in months, and why I'm now convinced that Agentic Postgres might just be the missing piece for building truly intelligent AI applications.

What Even IS Agentic Postgres? (The Question That Started Everything)

Before this hackathon, my mental model of PostgreSQL was pretty simple:

It stores data (tables, rows, columns)
It's fast and reliable
Everyone uses it
That's... pretty much it?

Then TigerData came along and said: "What if your database could work with AI agents instead of just serving them data?"

And suddenly I'm learning about:

Zero-copy database forks (< 1 second! What kind of sorcery?!)
Hybrid search combining vector embeddings + BM25 ranking
MCP (Model Context Protocol) for giving AI agents PostgreSQL expertise
Fluid Storage that makes all this magic possible
Multi-agent collaboration using separate database forks

My brain: "Okay, this changes EVERYTHING." 🤯💡

The Aha Moment: When I Realized What This Enables

Here's what got me excited. Imagine you're building an AI coding assistant that needs to:

Analyze your codebase (needs database access)
Suggest optimizations (needs to test different approaches)
Verify changes won't break things (needs safe testing environment)
Learn from multiple developers simultaneously (needs isolation)

Traditional approach:

Set up test database (minutes to hours)
Hope tests don't interfere with each other
Manually manage test data
Pray nothing breaks production
Cross fingers the AI doesn't suggest something catastrophic

With Agentic Postgres:

User: "Optimize this slow query"
System: Creates 4 database forks in 4 seconds �
Agent A: Tests adding indexes (on Fork 1)
Agent B: Rewrites query with CTEs (on Fork 2)
Agent C: Tries different join order (on Fork 3)
Agent D: Experiments with partitioning (on Fork 4)
System: Compares results, applies best solution to production
Total time: < 10 seconds

THAT'S INSANE. And it's exactly what TigerData enables! 🚀

The Research Phase: Going Deep on Every Feature

When I started researching for the hackathon, I did what any excited developer does: I went DEEP. Like, "stayed up until 3 AM reading documentation" deep. 😅

Let me break down what I learned about each key feature:

1. Zero-Copy Database Forks: The Game Changer 🔥

What I thought forks were:
"Probably like git branches but for databases... maybe it copies all the data? Must be slow."

What they actually are:
Copy-on-write (COW) magic at the block storage layer. You get a complete database copy in sub-second time without actually copying data!

Mind-blowing stats from my research:

Fork creation: < 1 second (tested, confirmed, not marketing!)
Cost: Only pay for changes, not the full copy
Isolation: Completely separate environment
Includes: Database + storage + embeddings + indexes + everything

Real-world use case I'm implementing:

// User asks: "What's the best way to structure this data?"

async function testMultipleSchemas(userQuery: string) {
  // Create 3 forks simultaneously
  const forks = await Promise.all([
    tigerCLI.createFork(), // Fork 1: Normalized schema
    tigerCLI.createFork(), // Fork 2: Denormalized schema
    tigerCLI.createFork(), // Fork 3: Hybrid approach
  ]);

  // Each agent tests their approach in parallel
  const results = await Promise.all([
    agent1.testNormalizedSchema(forks[0]),
    agent2.testDenormalizedSchema(forks[1]),
    agent3.testHybridSchema(forks[2])
  ]);

  // Compare performance, pick winner
  const bestApproach = selectBestPerformance(results);

  // Cleanup (automatic with TTL, but being explicit)
  await Promise.all(forks.map(f => tigerCLI.deleteFork(f.serviceId)));

  return bestApproach;
}

// Total time: 5-8 seconds for 3 complete database tests
// Traditional approach: 30+ minutes minimum

This isn't science fiction. This is what the Tiger CLI actually enables! 🔥

Resource that helped me understand this:

Zero-Copy Forks Announcement - The blog post that made me go "wait, WHAT?!"
Tiger CLI GitHub - Actual code examples

2. Hybrid Search: When Vector Search Met BM25 🎯

This is where things get really interesting. I've used vector search before (OpenAI embeddings + pgvector), and I've used full-text search (PostgreSQL's tsvector). But I never thought about combining them!

The problem with vector search alone:
Great for semantic similarity, terrible for exact keyword matches.

Example:

Query: "How to create index on timestamp column?"
Vector search: Returns general indexing docs (semantic match)
But misses: Specific "timestamp" syntax (keyword miss)

The problem with full-text search alone:
Great for keywords, terrible for understanding meaning.

Example:

Query: "How to speed up date queries?"
Full-text search: Looks for exact words "speed" and "date"
Misses: Articles about "optimizing temporal queries" (same meaning, different words)

The magic of hybrid search (vector + BM25):
Combines semantic understanding with keyword precision!

Here's the actual SQL I learned from TigerData's docs (and yes, this blew my mind):

-- The hybrid search query that changed how I think about search

WITH vector_results AS (
  SELECT
    id,
    content,
    embedding <=> query_embedding AS vector_distance,
    ROW_NUMBER() OVER (ORDER BY embedding <=> query_embedding) AS vector_rank
  FROM documents
  ORDER BY embedding <=> query_embedding
  LIMIT 20
),
bm25_results AS (
  SELECT
    id,
    content,
    ts_rank_bm25(content_tsv, plainto_tsquery('user query')) AS bm25_score,
    ROW_NUMBER() OVER (
      ORDER BY ts_rank_bm25(content_tsv, plainto_tsquery('user query')) DESC
    ) AS bm25_rank
  FROM documents
  WHERE content_tsv @@ plainto_tsquery('user query')
  ORDER BY bm25_score DESC
  LIMIT 20
),
combined AS (
  SELECT
    COALESCE(v.id, b.id) AS id,
    COALESCE(v.content, b.content) AS content,
    -- Reciprocal Rank Fusion (RRF) algorithm
    (COALESCE(1.0 / (60 + v.vector_rank), 0.0) * 0.6 +
     COALESCE(1.0 / (60 + b.bm25_rank), 0.0) * 0.4) AS hybrid_score
  FROM vector_results v
  FULL OUTER JOIN bm25_results b ON v.id = b.id
)
SELECT id, content, hybrid_score
FROM combined
ORDER BY hybrid_score DESC
LIMIT 10;

What makes this beautiful:

Reciprocal Rank Fusion - Clever algorithm that combines rankings
Weighted scores - You control vector vs keyword importance (0.6 vs 0.4 here)
FULL OUTER JOIN - Catches results from either method
Pure SQL - No external services, all in PostgreSQL!

My testing plan:
I'm building a "Conversational Database Explorer" where users ask questions in natural language. Hybrid search will power:

Documentation lookup ("How do I create an index?")
Query history search ("Show me that join query I wrote last week")
Schema exploration ("Which tables contain customer data?")

Resources that taught me this:

pg_textsearch Introduction - The announcement that made BM25 on Postgres a reality
TigerData Docs on pg_textsearch - Technical details and examples

3. Tiger MCP: PostgreSQL Expertise as a Service 🧠

This one took me a while to wrap my head around. MCP (Model Context Protocol) is Anthropic's open standard for giving LLMs access to external tools and data. Tiger MCP is TigerData's implementation that gives AI assistants 10+ years of PostgreSQL expertise.

What this means practically:

Instead of me writing:

const prompt = `You are a PostgreSQL expert. Here's the schema...
Help the user write a query... Remember to use indexes...
Oh and don't forget about...`
// 500 lines of PostgreSQL best practices

I can just:

// Use Tiger MCP server (hosted or self-hosted)
const response = await mcpClient.searchPostgresDocs(userQuery);
// MCP returns relevant PostgreSQL docs, examples, and best practices

The three MCP tools I'm most excited about:

semantic_search_postgres_docs - Search official PostgreSQL docs (versions 14-18)

   // User: "How to create a GIN index on JSONB?"
   const docs = await mcp.searchPostgresDocs("GIN index JSONB");
   // Returns: Exact syntax, examples, performance notes

semantic_search_tiger_docs - Search TimescaleDB/TigerData docs

   // User: "How do hypertables work?"
   const docs = await mcp.searchTigerDocs("hypertables");
   // Returns: Concepts, setup, best practices

get_prompt_template - Get task-specific PostgreSQL templates

   // User needs help with query optimization
   const template = await mcp.getPromptTemplate("optimize_query");
   // Returns: Structured prompt with PostgreSQL optimization expertise

How I'm using it in my project:

// Multi-agent system with MCP integration

class QueryAgent {
  async generateSQL(userQuery: string, schema: Schema) {
    // 1. Get relevant PostgreSQL docs via MCP
    const docs = await mcpClient.searchPostgresDocs(userQuery);

    // 2. Get optimization template via MCP
    const template = await mcpClient.getPromptTemplate("write_optimized_query");

    // 3. Combine with GPT-4
    const prompt = `
      User Query: ${userQuery}
      Database Schema: ${JSON.stringify(schema)}

      PostgreSQL Documentation:
      ${docs}

      Optimization Guidelines:
      ${template}

      Generate optimized SQL query.
    `;

    const sql = await openai.chat.completions.create({
      model: "gpt-4-turbo-preview",
      messages: [{ role: "user", content: prompt }]
    });

    return sql;
  }
}

The setup (surprisingly easy):

# Option 1: Use hosted MCP server (easiest)
# Just configure in your IDE:
# .claude/mcp.json
{
  "mcpServers": {
    "tiger-docs": {
      "url": "https://mcp.tigerdata.com/docs"
    }
  }
}

# Option 2: Self-host (more control)
git clone https://github.com/timescale/tiger-docs-mcp-server.git
cd tiger-docs-mcp-server
npm install
npm run build
npm start

Resource that made MCP click for me:

Tiger MCP Server GitHub - Source code and setup instructions
TigerData MCP Docs - Integration guide

4. Tiger CLI: Your Database's Remote Control <�

The Tiger CLI is how you actually USE all these features. And it's surprisingly delightful to use!

Commands I use constantly:

# Authentication (one-time setup)
tiger auth login
# Opens browser, authenticate, done! ✅

# Create a free database (no credit card required!)
tiger service create --name my-db --free --with-password -o json

# Fork a database (THE MONEY SHOT)
tiger service fork prod-db-xyz --now
# Output: Fork created in 0.8 seconds! 🚀

# Get connection string
tiger db connection-string my-db-abc
# Returns: postgresql://user:pass@host:port/db

# Connect directly (uses psql)
tiger db connect my-db-abc
# You're in! Run queries, inspect schema, whatever you need

# Cleanup
tiger service delete fork-xyz
# Gone! (But production is safe)

My favorite workflow:

# Morning: Create test environment
tiger service fork prod-db --now > test-fork.json
TEST_DB=$(jq -r '.service_id' test-fork.json)

# Test migrations all day
tiger db connect $TEST_DB -f migration-v1.sql
tiger db connect $TEST_DB -f migration-v2.sql
# ... test, break things, no stress

# Evening: Cleanup
tiger service delete $TEST_DB
# Tomorrow: Fork again fresh!

Resource:

Tiger CLI Docs - Comprehensive command reference

5. Multi-Agent Collaboration: The Architecture I'm Building 🤖

This is where everything comes together. The hackathon challenge asks for "Multi-agent collaboration using separate database forks," and I have a PLAN.

The Conversational Database Explorer Architecture:

User: "Analyze my database and suggest optimizations"
        |
        v
+-----------------------------+
|      Agent Coordinator      |
| (Orchestrates all agents    |
|  in parallel)               |
+-----------------------------+
        |          |          |
        v          v          v
   +---------+ +---------+ +---------+
   | Fork 1  | | Fork 2  | | Fork 3  |
   +---------+ +---------+ +---------+
        |          |          |
        v          v          v
   +---------+ +---------+ +---------+
   | Schema  | | Query   | | Insight |
   | Agent   | | Agent   | | Agent   |
   +---------+ +---------+ +---------+
        |          |          |
        | Analyzes | Generates| Discovers
        | structure| SQL      | patterns
        |          |          |
        +----------+----------+
                   |
                   v
         Synthesized Response
   "Found 3 slow queries, 2 missing indexes,
    and 1 optimization opportunity..."

The code structure:

// Agent Coordinator (the brain)
class AgentCoordinator {
  private schemaAgent: SchemaAgent;
  private queryAgent: QueryAgent;
  private insightAgent: InsightAgent;
  private memoryAgent: MemoryAgent;

  async processUserQuery(query: string, sessionId: string) {
    // 1. Create forks for each agent (parallel!)
    const forks = await Promise.all([
      tigerCLI.createFork(), // Schema agent's sandbox
      tigerCLI.createFork(), // Query agent's sandbox
      tigerCLI.createFork(), // Insight agent's sandbox
    ]);

    // 2. Run agents in parallel (they can't interfere!)
    const [schemaAnalysis, generatedSQL, insights, context] =
      await Promise.all([
        this.schemaAgent.analyze(query, forks[0]),
        this.queryAgent.generateSQL(query, forks[1]),
        this.insightAgent.discover(query, forks[2]),
        this.memoryAgent.getContext(sessionId), // Uses main DB
      ]);

    // 3. Synthesize results
    const response = this.synthesize({
      schema: schemaAnalysis,
      sql: generatedSQL,
      insights: insights,
      context: context,
    });

    // 4. Cleanup forks
    await Promise.all(forks.map(f => tigerCLI.deleteFork(f.serviceId)));

    return response;
  }
}

// Schema Agent (understands database structure)
class SchemaAgent {
  async analyze(query: string, forkId: string) {
    const conn = await connectToFork(forkId);

    // Introspect schema safely on fork
    const tables = await conn.query(`
      SELECT table_name, column_name, data_type
      FROM information_schema.columns
      WHERE table_schema = 'public'
    `);

    // Use MCP for PostgreSQL best practices
    const recommendations = await mcpClient.searchPostgresDocs(
      "schema design best practices"
    );

    return {
      tables,
      recommendations,
      relevantTables: this.identifyRelevantTables(query, tables),
    };
  }
}

// Query Agent (generates SQL)
class QueryAgent {
  async generateSQL(query: string, forkId: string) {
    const conn = await connectToFork(forkId);

    // Get schema context
    const schema = await this.getSchemaContext(conn);

    // Use MCP + GPT-4 for SQL generation
    const mcpDocs = await mcpClient.searchPostgresDocs(query);
    const sql = await this.generateWithGPT4(query, schema, mcpDocs);

    // Test on fork (safe!)
    const isValid = await this.validateSQL(conn, sql);

    return { sql, isValid, executionPlan: await this.getExplain(conn, sql) };
  }
}

// Insight Agent (discovers patterns)
class InsightAgent {
  async discover(query: string, forkId: string) {
    const conn = await connectToFork(forkId);

    // Analyze query patterns
    const slowQueries = await conn.query(`
      SELECT query, mean_exec_time, calls
      FROM pg_stat_statements
      ORDER BY mean_exec_time DESC
      LIMIT 10
    `);

    // Check for missing indexes
    const missingIndexes = await this.analyzeMissingIndexes(conn);

    return {
      slowQueries,
      missingIndexes,
      optimizationOpportunities: this.findOptimizations(slowQueries),
    };
  }
}

// Memory Agent (conversation context)
class MemoryAgent {
  async getContext(sessionId: string) {
    // Uses main database (not fork)
    const history = await db.query(`
      SELECT user_message, assistant_message, created_at
      FROM conversations
      WHERE session_id = $1
      ORDER BY created_at DESC
      LIMIT 10
    `, [sessionId]);

    return this.buildContext(history);
  }

  async store(sessionId: string, userMsg: string, assistantMsg: string) {
    // Store in TimescaleDB hypertable for time-series optimization
    await db.query(`
      INSERT INTO conversations (session_id, user_message, assistant_message)
      VALUES ($1, $2, $3)
    `, [sessionId, userMsg, assistantMsg]);
  }
}

Why this architecture is powerful:

Parallel Execution - All agents run simultaneously (3-5 seconds total)
Isolated Testing - Each agent has its own fork (no interference)
Safe Exploration - Nothing touches production database
Automatic Cleanup - Forks deleted after use (or TTL expires)
Context Aware - Memory agent maintains conversation history
PostgreSQL Expertise - MCP provides deep database knowledge

Performance estimates:

Fork creation (3x): ~3 seconds
Agent execution (parallel): ~2-4 seconds
Response synthesis: ~1 second
Total: 6-8 seconds for comprehensive database analysis 🚀

Compare to traditional approach:

Set up test databases: 30+ minutes
Run tests sequentially: 10+ minutes
Manual analysis: 20+ minutes
Total: 60+ minutes 😱

That's a 10x speed improvement! And the agents can't possibly break production because they're working on isolated forks.

The Implementation Plan: 4 Phases to Hackathon Glory 🎯

After all this research, I created a detailed implementation plan. Here's the roadmap:

Phase 1: Foundation (Days 1-3)

Goal: Get basic infrastructure working

// Week 1 checklist:
const phase1Tasks = [
  " Set up TigerData account (free tier)",
  " Install Tiger CLI and authenticate",
  " Create base database with extensions",
  "� Implement Tiger CLI service wrapper",
  "� Build fork manager with lifecycle tracking",
  "� Create database models (sessions, forks, conversations)",
  "� Test fork creation/deletion",
];

Key milestone: Successfully create and delete forks programmatically.

Phase 2: AI Integration (Days 4-6)

Goal: Get agents talking to the database

const phase2Tasks = [
  "🧠 Set up pgvector extension",
  "🧠 Install pg_textsearch for BM25",
  "🧠 Implement embedding generation (OpenAI)",
  "🧠 Build hybrid search service",
  "🧠 Create basic query agent (GPT-4)",
  "🧠 Test natural language to SQL",
];

Key milestone: "Show me all tables" � Returns actual table list.

Phase 3: Multi-Agent System (Days 7-9)

Goal: Agents working in parallel

const phase3Tasks = [
  "🤖 Implement agent coordinator",
  "🤖 Build schema agent",
  "🤖 Build query agent",
  "🤖 Build insight agent",
  "🤖 Build memory agent",
  "🤖 Test parallel execution on forks",
];

Key milestone: All 4 agents analyzing database simultaneously.

Phase 4: Polish & Deploy (Days 10-14)

Goal: Production-ready demo

const phase4Tasks = [
  "🎨 Build Next.js chat interface",
  "🎨 Create schema browser component",
  "🎨 Implement WebSocket for real-time chat",
  "🎨 Deploy backend to Render/Railway",
  "🎨 Deploy frontend to Vercel",
  "🎨 Record demo video",
  "🎨 Write submission post",
];

Key milestone: Live demo anyone can try!

What Makes This Hackathon Project Special 💎

There are a few things I'm doing that I haven't seen elsewhere:

1. Parallel Universe Testing

Instead of testing ONE solution, test MULTIPLE simultaneously:

User: "How should I optimize this query?"

Traditional: Try approach 1 � Measure � Try approach 2 � Measure � Compare
Time: 10+ minutes

Agentic Postgres: Fork 4x � Test all approaches in parallel � Compare
Time: < 10 seconds

2. Conversational Branches

Each "what-if" scenario creates a new fork:

User: "What if I denormalize this table?"
System: *Creates fork*
Agent: *Tests denormalized schema*
Agent: "Here's the performance impact..."

User: "Actually, what if I partition it instead?"
System: *Creates another fork*
Agent: *Tests partitioning*
Agent: "Partitioning gives better results!"

You can explore multiple possibilities without commitment!

3. Time-Travel Debugging

Fork from specific timestamps to analyze issues:

// Production issue at 2:30 PM
// Fork from 2:25 PM (before the issue)
const beforeFork = await tigerCLI.createFork(prodDB, {
  recoveryTime: "2025-01-10 14:25:00"
});

// Fork from 2:30 PM (during the issue)
const duringFork = await tigerCLI.createFork(prodDB, {
  recoveryTime: "2025-01-10 14:30:00"
});

// Compare database state
const changes = await compareDBs(beforeFork, duringFork);
console.log("What changed:", changes);

// Test fix on the "during" fork
await testFix(duringFork, proposedFix);

4. Self-Healing Queries

AI detects errors, generates fixes, tests on forks, applies best solution:

async function selfHealQuery(brokenSQL: string) {
  // Detect issue
  const error = await validateSQL(brokenSQL);

  // Generate 3 potential fixes
  const fixes = await generateFixes(brokenSQL, error);

  // Create fork for each fix
  const forks = await Promise.all(fixes.map(() => tigerCLI.createFork()));

  // Test all fixes in parallel
  const results = await Promise.all(
    fixes.map((fix, i) => testSQL(forks[i], fix))
  );

  // Apply best fix to production
  const bestFix = selectBest(results);
  return bestFix;
}

The Tech Stack (Because Details Matter) 🛠️

Here's what I'm using and why:

Frontend

const frontend = {
  framework: "Next.js 14",              // App router, RSC, fast
  ui: "React 18 + Tailwind CSS",        // Beautiful, responsive
  components: "shadcn/ui + Radix UI",   // Accessible, polished
  state: "Zustand",                     // Simple, no boilerplate
  realtime: "WebSocket (Socket.io)",    // Chat interface
  charts: "Recharts",                   // Query visualization
};

Backend

const backend = {
  framework: "FastAPI (Python 3.11+)", // Async, fast, typed
  database: "TigerData Agentic Postgres", // The star! ⭐
  orm: "SQLAlchemy 2.0",                 // Async support
  ai: "OpenAI GPT-4 + text-embedding-3-small",
  websocket: "python-socketio",          // Real-time chat
  testing: "pytest + httpx",             // Comprehensive tests
};

Database Extensions

-- The power trio
CREATE EXTENSION IF NOT EXISTS timescaledb;   -- Time-series optimization
CREATE EXTENSION IF NOT EXISTS vector;        -- Semantic search (pgvector)
CREATE EXTENSION IF NOT EXISTS pg_textsearch; -- BM25 ranking
CREATE EXTENSION IF NOT EXISTS pg_stat_statements; -- Query monitoring

Infrastructure

const infrastructure = {
  frontend: "Vercel",           // Instant deploys, edge functions
  backend: "Render / Railway",  // Easy Docker deploys
  database: "TigerData Cloud",  // Already deployed!
  monitoring: "Sentry + Axiom", // Errors + logs
  cicd: "GitHub Actions",       // Auto-deploy on push
};

The Learning Curve: What Surprised Me 📚

Easy Things (That I Expected to Be Hard)

Tiger CLI Installation

   curl -fsSL https://cli.tigerdata.com | sh
   # Done! 30 seconds.

Expected: Complex setup. Reality: One command. 🔥

Creating Forks

   tiger service fork my-db --now
   # Returns in < 1 second

Expected: Minutes of waiting. Reality: Faster than git checkout! ⚡

Hybrid Search Implementation Expected: Custom code, complex algorithms. Reality: One SQL query (well, a complex one, but still!). The pg_textsearch extension does all the heavy lifting.

Hard Things (That I Underestimated)

Understanding Copy-on-Write
The concept is simple. The implications are profound. It took me a while to really grasp how this changes everything about database testing.
Reciprocal Rank Fusion
The hybrid search algorithm is elegant but not obvious. I had to read the formula like 10 times before it clicked:

   RRF_score = � (1 / (k + rank_i))
   where k = 60 (constant), rank_i = rank in list i

Multi-Agent Coordination Making sure agents don't step on each other's toes, even with separate forks, requires careful orchestration. The coordinator pattern helps but needs thought.

Resources That Saved Me (Links You'll Want to Bookmark) 🔖

Here's every resource that helped me understand Agentic Postgres:

Official Documentation

TigerData Main Docs - Start here!
Getting Started Guide - First steps with TigerData
AI Integration Docs - AI-specific features
REST API Reference - Complete API docs

Key Blog Posts

Postgres for Agents - The vision explained
Zero-Copy Forks Announcement - Mind-blowing tech details
Fluid Storage Deep Dive - How the magic works
pg_textsearch Introduction - BM25 for Postgres
Agentic Postgres Free Plan - No credit card needed!

GitHub Repositories

Tiger CLI - Command-line tool source
Tiger Docs MCP Server - MCP server implementation
TimescaleDB - The foundation

Example Projects

AgenticForkSquad - Multi-agent query optimizer
Self-Healing Framework - Automatic issue resolution
Agent Auth - Security with agents

Community

DEV Community Tag - Latest posts and discussions
Discord - Active community support
Product Page - Features overview

The Meta Moment: Research Planning WITH AI 🤖

Here's the fun part: I used AI to help me research Agentic Postgres. Not just casual ChatGPT queries, but a systematic research session with Claude Code that:

Searched the web for TigerData blog posts, docs, and examples
Fetched Context7 docs for library integrations
Analyzed architecture patterns from existing hackathon projects
Generated implementation plans with code examples
Created comprehensive documentation (9 markdown files!)

The irony? I'm researching how to build AI agents that use databases... by using an AI agent! 😄

What I learned from this meta experience:

AI is REALLY good at:

Gathering scattered information from multiple sources
Synthesizing concepts from docs into actionable plans
Generating code examples based on API documentation
Creating structured documentation with consistent formatting

AI still needs humans for:

L Understanding "why" (business value, user needs)
L Making architectural decisions (trade-offs, priorities)
L Creative problem-solving (novel use cases)
L Debugging edge cases in production

This is exactly why Agentic Postgres is exciting! It gives AI agents:

Safe sandboxes (forks) to explore ideas
Fast iteration (< 1 second to try something new)
Real data (not synthetic test data)
Isolated environments (can't break production)

What's Next: Building the Vision 🚀

Now that research is done, it's time to BUILD! The Conversational Database Explorer brings together all the TigerData Agentic Postgres features into a production-ready application that anyone can use to interact with their databases through natural language.

The Big Picture: Why This Matters 🌟

Here's why I'm genuinely excited about Agentic Postgres (beyond winning a hackathon):

1. It Changes How We Test

No more "hope this doesn't break production." Just fork, test, verify, apply. Safe experimentation becomes the default.

2. It Enables True AI Collaboration

AI agents can work in parallel without stepping on each other's toes. Each gets a complete, isolated database sandbox.

3. It Makes AI More Trustworthy

When AI can test its own suggestions on real data (via forks) before recommending them, it becomes more reliable.

4. It Democratizes Complex Operations

Query optimization, schema design, performance tuning these used to require expert DBAs. Now AI agents can help, safely.

5. It's Fast Enough to Be Interactive

Sub-second forks mean you can have a conversation with your database:

User: "What if I add an index here?"
System: *Creates fork, tests index*
System: "16% faster, uses 2MB disk. Want to apply it?"
User: "Yes!"
System: *Applies to production*

That's not batch processing. That's a dialogue! 💬

Final Thoughts: The Journey vs The Destination 🎯

Right now, as I write this, the Conversational Database Explorer is still mostly in my head and in documentation. The code is mostly placeholders. The demo doesn't exist yet.

But you know what? The research phase has been incredible!

I learned about:

Copy-on-write storage systems
Reciprocal rank fusion algorithms
Multi-agent orchestration patterns
PostgreSQL internals (way more than I expected!)
Production-grade authentication (from my previous Auth0 integration)

And I discovered something that might change how I build every database-backed application going forward: the ability to test safely and quickly on real data.

That's not just a feature. That's a paradigm shift. 🔥

For Fellow Builders

If you're reading this and thinking "Should I try TigerData?", here's my honest take:

Try it if you:

Build AI applications that need database access
Want safe testing environments (forks are a game-changer)
Need hybrid search (semantic + keyword)
Like clean CLIs and good documentation
Want to learn PostgreSQL deeply (MCP is a great teacher!)

Maybe skip it if:

L You just need a basic CRUD app (regular PostgreSQL is fine)
L You don't work with AI/ML (you won't use the cool features)
L You're not comfortable with SQL (there's a learning curve)

For me? This is exactly what I needed for building trustworthy AI agents. The fact that there's a hackathon is just the excuse I needed to finally build it! =

What I Hope to Prove

By the end of this hackathon, I want to demonstrate that:

AI agents can be trusted when they have safe sandboxes (forks)
Database optimization can be conversational (not just for DBAs)
Multi-agent collaboration works when agents have isolation
Hybrid search is superior to vector or keyword alone
Development velocity increases when testing is instant

Ambitious? Yes. Possible? Absolutely. Worth the late nights? We'll see! =

The Commitment: Shipping This Thing =�

Here's my public commitment:

I, Anshu Mandal, will build the Conversational Database Explorer using TigerData Agentic Postgres. I will implement all 5 key features (MCP, CLI, pg_textsearch, forks, Fluid Storage) in a production-ready demo. I will document the journey, share the code, and submit before the deadline.

Why public commitment?

Because when I told the dev.to community about StudyMate, and then people actually used it, that accountability pushed me to make it better. Let's do it again! 💪

Progress updates:

📅 Week 1: Backend foundation
📅 Week 2: AI integration
📅 Week 3: Multi-agent system
📅 Week 4: Polish & ship

I'll share updates, code snippets, and learnings along the way. Follow along if you're interested!

Resources One More Time (Because You'll Need These) 📚

Organized by what you want to do:

Getting Started:

TigerData Free Tier Signup - No credit card!
Getting Started Guide
Tiger CLI Installation

Learning the Tech:

Building AI Agents:

Inspiration:

Hackathon Examples - See what others built
AgenticForkSquad
Self-Healing Framework

Community:

Discord - Get help, share ideas
GitHub Organization - Explore the source

Let's Build This! 🚀

That's my research journey with TigerData Agentic Postgres. From "what even is this?" to "I need to build with this NOW!"

The best part? This is just the beginning. Once the hackathon project is done, I can use this pattern for:

Code review agents (test suggestions on forks)
Migration testing agents (verify before production)
Performance optimization agents (compare approaches)
Data exploration agents (safe discovery)
Schema evolution agents (test design changes)

The possibilities are endless when you have:

Safe sandboxes (zero-copy forks)
Fast iteration (< 1 second creation)
PostgreSQL expertise (MCP)
Hybrid intelligence (vector + BM25 search)
Multi-agent collaboration (parallel execution)

If you're building with TigerData too, let's connect! Drop a comment, share your project, or hit me up on:

GitHub: @prime399
DEV.to: Right here! 👋

Let's make databases intelligent together! 🤖🚀

P.S. - If you read this whole thing, you're either:

Really interested in Agentic Postgres (awesome! =L)
Procrastinating on something (I feel you =)
My mom (hi Mom! Thanks for pretending to understand! d)

Either way, thanks for reading! Now go build something cool! =�

Acknowledgments:

TigerData team for building something genuinely innovative
The hackathon organizers for the motivation
The dev.to community for being awesome
All the developers who wrote the example projects I learned from
Future me, for the late nights ahead 😴

Let's ship this thing! 🚢

Try It Out! Live Demo & Open Source 🌐

UPDATE: The Conversational Database Explorer is now live!

Live Demo

🔗 Website: convodb.tech

What you can do:

Chat with your database in natural language
Watch 4 AI agents collaborate in real-time
Explore your schema interactively
Get query optimization suggestions
Test changes on instant database forks (< 1 second!)

Try it now:

Visit: https://convodb.tech
Sign up (GitHub/Google OAuth)
Connect your PostgreSQL database
Ask: "Show me all my tables"
Ask: "Find slow queries and optimize them"
Ask: "What if I add an index to this column?"

Open Source Code

💻 GitHub: github.com/prime399/convo-db

Repository highlights:

Complete FastAPI backend with Tiger CLI integration
Next.js frontend with real-time WebSocket chat
Multi-agent system (Schema, Query, Insight, Memory agents)
Hybrid search implementation (pgvector + pg_textsearch)
Fork manager with automatic lifecycle management
Comprehensive documentation (9 detailed guides!)
Production-ready deployment configs

Quick clone and run:

git clone https://github.com/prime399/convodb.git
cd convodb
# Follow setup instructions in README.md

What's included:

✅ Tiger CLI Service Wrapper
✅ Fork Manager with TTL
✅ Hybrid Search Service
✅ Multi-Agent Architecture
✅ WebSocket Chat Interface
✅ Next.js + FastAPI Boilerplate
✅ Complete Documentation

Star the repo if it helps you! ⭐

Connect & Collaborate

Building with TigerData Agentic Postgres? Let's connect!

💻 GitHub: @prime399
🌐 Project: convodb.tech
📝 DEV.to: Right here in the comments!
💬 Discord: TimescaleDB Community

Want to contribute?

Open issues for bugs or feature requests
Submit PRs for improvements
Share your own TigerData projects
Help improve the documentation

Let's build intelligent databases together! 🐯🚀

Study-Flow: Auth0 for AI Agents: The Missing Piece My Study App Was Begging For

Anshu Mandal — Mon, 27 Oct 2025 05:58:34 +0000

This is a submission for the Auth0 Challenge

What I Built (And Why My Previous Project Was Begging for Auth0!)

Remember StudyMate? The AI-powered study management platform I built during mid-sems? (Yeah, I know – building a study app while supposed to be studying. The irony never gets old! 😅)

Well, here's the thing: StudyMate worked great. MentorMind, the AI study assistant, gave personalized advice, tracked study patterns, and even told me when to take breaks. But there was always this nagging feeling that something was missing. Like having a really smart assistant who's super helpful... but you're not quite sure if you can fully trust them with your Google Calendar or Slack workspace.

Enter Auth0. Specifically, Auth0 for AI Agents.

After integrating Auth0, it finally clicked – this was the missing puzzle piece! Auth0 doesn't just add authentication (though it does that beautifully). It transforms MentorMind from a helpful AI into a trusted AI agent that can securely access third-party services on your behalf, with fine-grained permission controls that actually make sense.

The Problem I Didn't Know I Was Solving (Until Auth0 Showed Me)

In my original StudyMate build, I had this vision: "What if MentorMind could check your Google Calendar to suggest optimal study times?" Or "What if it could fetch your Slack messages to understand your group project commitments?"

But I never built those features. Why? Because implementing secure OAuth flows for multiple providers, managing tokens safely, handling refresh logic, and giving users granular control over permissions sounded like a nightmare. I was one person building during exams – ain't nobody got time for that! 😅

Turns out, I just needed the right tool. Auth0 for AI Agents handles all of this complexity with what feels like magic (but is actually really solid engineering).

What Auth0 Brought to StudyMate

1. The Bold Decision: Hybrid Auth Architecture 🏗️

Here's where things get interesting. Most tutorials tell you: "Replace your entire auth system with Auth0." But I did something different – something I haven't seen documented much elsewhere.

I kept both.

Convex Auth - Handles user login/signup (GitHub, Google OAuth)
Auth0 Token Vault - Manages third-party API tokens (Google Calendar, Spotify, etc.)

Why? Because my users already trust and use Convex Auth. Ripping it out and forcing a migration felt wrong. Plus, Convex Auth integrates beautifully with my real-time backend. So instead, I added Auth0 exclusively for what it does best: managing external API tokens.

The Architecture:

User Login → Convex Auth (GitHub/Google) → User Session
        ↓
Study Session → Ask MentorMind → Needs Calendar Access?
        ↓
User's Convex Token → Auth0 Token Vault → Exchange for Google Calendar Token
        ↓
MentorMind → Google Calendar API → Returns Free Time Slots

This hybrid approach gave me the best of both worlds:

✅ Users keep their familiar login flow (no UX disruption)
✅ Auth0 handles the complex OAuth token dance for third-party APIs
✅ Zero downtime migration (feature flag rollout)
✅ Automatic fallback if Token Vault has issues

Code evidence from production:

// lib/auth0-ai.ts:1-43 (Actual Production Code)
/**
 * Auth0 AI Token Vault Configuration
 *
 * This file initializes the Auth0 AI SDK for Token Vault integration.
 * It manages OAuth tokens for third-party APIs (Google Calendar, Spotify, etc.)
 * while keeping Convex Auth for user authentication.
 *
 * Architecture: Hybrid Auth
 * - Convex Auth: User login/signup
 * - Auth0 Token Vault: Third-party API token management
 *
 * Note: This is separate from auth0-config.ts which is for traditional Auth0 authentication
 */

import { Auth0AI } from "@auth0/ai-vercel";
import { SUBJECT_TOKEN_TYPES } from "@auth0/ai";

// Validate required environment variables
const requiredEnvVars = [
  "AUTH0_DOMAIN",
  "AUTH0_API_CLIENT_ID",
  "AUTH0_API_CLIENT_SECRET",
] as const;

for (const envVar of requiredEnvVars) {
  if (!process.env[envVar]) {
    console.warn(
      `[Auth0 Token Vault] Missing environment variable: ${envVar}. Token Vault features will be disabled.`
    );
  }
}

/**
 * Auth0 AI instance for Token Vault operations
 * This handles secure token storage, refresh, and injection for AI agents
 */
export const auth0AI = new Auth0AI({
  auth0: {
    domain: process.env.AUTH0_DOMAIN!,
    clientId: process.env.AUTH0_API_CLIENT_ID!,
    clientSecret: process.env.AUTH0_API_CLIENT_SECRET!,
  },
});

How the hybrid flow works in practice:

// lib/mcp-token-injector.ts:65-99 (Token injection with dual-mode support)
export async function injectUserTokensToMCP(
  userId: string,           // From Convex Auth
  convexAuthToken: string   // User's Convex session token
): Promise<TokenInjectionResult> {

  // Try Auth0 Token Vault first if enabled
  if (AUTH0_FEATURE_FLAGS.USE_TOKEN_VAULT_GOOGLE) {
    try {
      // Use Convex userId but get tokens from Auth0 Token Vault
      return await injectTokensFromAuth0(userId);
    } catch (error) {
      console.error('Auth0 Token Vault failed:', error);

      // Automatic fallback to Convex if Token Vault fails
      if (AUTH0_FEATURE_FLAGS.FALLBACK_TO_CONVEX) {
        console.warn('Falling back to Convex token storage');
        return await injectTokensFromConvex(userId, convexAuthToken);
      }

      return {
        success: false,
        message: 'Failed to get tokens from Auth0 Token Vault',
      };
    }
  }

  // Use Convex-based token storage (legacy mode)
  return await injectTokensFromConvex(userId, convexAuthToken);
}

I've never seen this hybrid pattern in Auth0's docs, but it worked perfectly for my use case. The beauty is that users never know Auth0 is involved – they log in with Convex Auth (GitHub/Google), and behind the scenes, Auth0 Token Vault manages their third-party API tokens. Best of both worlds! And as you'll see below, it made the migration incredibly smooth!

2. Token Vault: The Game Changer 🔐

This is my favorite feature, hands down. Token Vault is Auth0's way of securely storing and managing third-party access tokens (Google, Slack, GitHub, you name it).

Here's what blew my mind: Instead of me writing hundreds of lines of OAuth implementation code for each provider, Auth0's Token Vault does this:

// lib/auth0-ai.ts - ACTUAL PRODUCTION CODE
import { Auth0AI } from "@auth0/ai-vercel";
import { SUBJECT_TOKEN_TYPES } from "@auth0/ai";

// Initialize Auth0 AI SDK
export const auth0AI = new Auth0AI({
  auth0: {
    domain: process.env.AUTH0_DOMAIN!,
    clientId: process.env.AUTH0_API_CLIENT_ID!,
    clientSecret: process.env.AUTH0_API_CLIENT_SECRET!,
  },
});

// Create Token Vault wrapper for Google Calendar
export const createGoogleCalendarTokenVault = (accessToken: string) => {
  return auth0AI.withTokenVault({
    // User's Convex access token (hybrid auth!)
    accessToken: async () => accessToken,

    // Token exchange type
    subjectTokenType: SUBJECT_TOKEN_TYPES.SUBJECT_TYPE_ACCESS_TOKEN,

    // Auth0 connection name
    connection: "google-oauth2",

    // Google Calendar scopes (read-only for security)
    scopes: [
      "https://www.googleapis.com/auth/calendar.calendarlist.readonly",
      "https://www.googleapis.com/auth/calendar.events.readonly",
      "https://www.googleapis.com/auth/calendar.freebusy",
    ],
  });
};

That's it! Now MentorMind can access a user's Google Calendar securely, with proper token management, automatic refresh, and zero risk of leaking credentials. Auth0 handles all the complexity behind the scenes.

Real-world example from my testing (December 20, 2025):

User: Anshu Mandal (23t0413037030@gandhinagaruni.ac.in)
Query: "What's on my calendar today?"
MentorMind retrieved 2 calendars: "Holidays in India" + personal calendar
No manual token refresh needed – Auth0 handled it automatically! ✨

A student can now ask MentorMind "When should I study this week?" and it'll check their actual Google Calendar, find free slots, and suggest optimal times based on their energy patterns (tracked from previous study sessions). That's some next-level personalization! 🎯

3. JWT Verification: Security That Actually Works 🛡️

In the original StudyMate, I had basic authentication. But securing AI agent API calls? That was scary territory. What if someone tried to impersonate a user? What if tokens got intercepted?

Auth0's JWT verification with JWKS endpoints gave me enterprise-grade security without the enterprise-grade headache:

import { createRemoteJWKSet, jwtVerify } from 'jose';

const JWKS = createRemoteJWKSet(
  new URL(`https://${AUTH0_DOMAIN}/.well-known/jwks.json`)
);

// Verify JWT in my AI agent endpoint
const { payload } = await jwtVerify(token, JWKS, {
  issuer: `https://${AUTH0_DOMAIN}/`,
  audience: AUTH0_AUDIENCE,
});

console.log("✅ Verified user:", payload.email);

Now every request to MentorMind is properly authenticated. I sleep better at night knowing student data is actually secure! 😌

4. Fine-Grained Permissions: Users Stay In Control ✨

This is where Auth0 really shines for AI agents. Users don't want to give blanket access to everything – they want control. Auth0 makes this trivial:

I built a Settings page where students can:

Connect/disconnect their Auth0 account
View exactly what permissions they've granted
Toggle optional scopes (read calendar, access Slack, etc.)
See token status and refresh information

// Request specific scopes from user
const response = await fetch('/api/auth/consent', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    scopes: [
      'openid',
      'profile',
      'email',
      'read:user',
      'offline_access'
    ]
  }),
});

Users feel empowered, not nervous. They control what MentorMind can access, and they can revoke permissions anytime. Trust = established! 🤝

5. Asynchronous Authorization: Human-in-the-Loop AI 🔄

Here's something wild that Auth0 enables: What if MentorMind wants to perform a sensitive action (like sharing your study notes with a group), but needs your explicit approval first?

Auth0's Client-Initiated Backchannel Authentication (CIBA) makes this possible:

async function requestUserApproval(action: string) {
  const response = await fetch(`${AUTH0_ISSUER_BASE_URL}/bc-authorize`, {
    method: 'POST',
    body: new URLSearchParams({
      client_id: AUTH0_CLIENT_ID,
      binding_message: `Approve: ${action}`,
      login_hint: user.email,
    }),
  });

  // Poll for user approval via push notification, email, or SMS
  return pollForApproval(auth_req_id);
}

I haven't fully implemented this yet (one step at a time!), but the potential is incredible. Imagine MentorMind saying "I think I should schedule a group study session for you – approve this via your phone?" That's responsible AI! 📱

The 75% Code Reduction That Changed Everything 📉➡️✨

Let me show you something that'll make every developer's heart sing: dramatic code reduction without losing functionality.

Before Auth0 Token Vault: Manual Token Management (120+ lines)

Here's what I had to do with Convex-based token storage:

// lib/mcp-token-injector.ts - OLD APPROACH (Convex)
async function injectTokensFromConvex(userId: string, convexAuthToken: string) {
  // 1. Create Convex client with auth
  const convex = new ConvexHttpClient(process.env.NEXT_PUBLIC_CONVEX_URL!);
  convex.setAuth(convexAuthToken);

  // 2. Fetch encrypted tokens from database
  const tokens = await convex.query(api.googleCalendar.getTokens, {});

  if (!tokens) {
    return { success: false, message: 'No tokens found' };
  }

  // 3. Manually check if tokens are expired
  const now = Date.now();
  const timeUntilExpiry = tokens.expiresAt - now;

  // 4. If expired, manually refresh
  if (timeUntilExpiry <= 0) {
    try {
      await convex.action(api.googleCalendar.refreshAccessToken, {
        refreshToken: decryptToken(tokens.refreshToken),
      });
      // 5. Fetch the refreshed tokens AGAIN
      const refreshedTokens = await convex.query(api.googleCalendar.getTokens, {});
      // ... more code
    } catch (refreshError) {
      // Handle refresh failures
      return { success: false, message: 'Refresh failed' };
    }
  }

  // 6. If expiring soon (within 5 min), proactively refresh
  if (timeUntilExpiry < 5 * 60 * 1000) {
    try {
      await convex.action(api.googleCalendar.refreshAccessToken, {
        refreshToken: decryptToken(tokens.refreshToken),
      });
      const refreshedTokens = await convex.query(api.googleCalendar.getTokens, {});
      // ... more code
    } catch (refreshError) {
      console.warn('Proactive refresh failed:', refreshError);
    }
  }

  // 7. Decrypt tokens manually
  const accessToken = decryptToken(tokens.accessToken);
  const refreshToken = decryptToken(tokens.refreshToken);

  // 8. Finally, send to MCP server
  await fetch(`${mcpConfig.url}/api/tokens`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-API-Key': mcpConfig.apiKey },
    body: JSON.stringify({ userId, accessToken, refreshToken, expiresAt: tokens.expiresAt })
  });

  return { success: true };
}

// Plus helper function for decryption
function decryptToken(encryptedToken: string): string {
  return Buffer.from(encryptedToken, 'base64').toString('utf-8');
}

// Total: ~120 lines of complex logic
// Concerns: Expiry checking, refresh logic, encryption, error handling

Problems:

❌ Manual expiry checking (could miss edge cases)
❌ Complex refresh logic (proactive + reactive)
❌ Multiple database roundtrips
❌ Custom encryption/decryption
❌ Lots of error states to handle

After Auth0 Token Vault: Simple & Elegant (~30 lines)

Here's the ENTIRE implementation with Token Vault:

// lib/mcp-token-injector.ts - NEW APPROACH (Auth0)
import { getGoogleCalendarToken } from "./auth0-token-vault";

async function injectTokensFromAuth0(userId: string) {
  const mcpConfig = getMCPServerConfig();

  // Get access token from Auth0 Token Vault
  // Auth0 automatically handles: refresh, expiry, encryption, storage
  const accessToken = await getGoogleCalendarToken();

  // Send token to MCP server - that's it!
  const response = await fetch(`${mcpConfig.url}/api/tokens`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': mcpConfig.apiKey,
    },
    body: JSON.stringify({
      userId,
      accessToken,
      source: 'auth0-token-vault',
    }),
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}`);
  }

  return { success: true, message: 'Tokens injected from Auth0 Token Vault' };
}

// Total: ~30 lines
// Auth0 handles: Expiry, refresh, encryption, storage, rotation

The getGoogleCalendarToken() Magic ✨

Here's what that one function call does behind the scenes:

// lib/auth0-token-vault.ts
import { getAccessTokenFromTokenVault } from "@auth0/ai-vercel";

export async function getGoogleCalendarToken(): Promise<string> {
  const token = getAccessTokenFromTokenVault();

  if (!token) {
    throw new TokenVaultError("Authorization required...");
  }

  return token; // That's it!
}

Auth0 Token Vault automatically:

✅ Checks if token is expired
✅ Refreshes if needed (transparent to you)
✅ Handles encryption (SOC 2 Type II certified)
✅ Manages token rotation
✅ Returns fresh token every time

Code Reduction Metrics 📊

Metric	Before (Convex)	After (Auth0)	Improvement
Lines of code	~120	~30	75% reduction
Database queries	2-4 per token fetch	0	100% reduction
Manual refresh logic	50+ lines	0 lines	100% elimination
Encryption code	Custom AES-256-GCM	Auth0-managed	Security upgrade
Edge cases to handle	8+ scenarios	1 error type	87% simpler

What this means in practice:

Less code to maintain = fewer bugs
No manual refresh logic = no missed edge cases
Auth0-managed encryption = better security
Automatic token rotation = compliance ready

And here's the kicker: Both approaches are running in production right now via feature flags! 🚀

// lib/auth0-ai.ts - Feature flags for gradual rollout
export const AUTH0_FEATURE_FLAGS = {
  USE_TOKEN_VAULT_GOOGLE: process.env.USE_TOKEN_VAULT_GOOGLE === "true",
  FALLBACK_TO_CONVEX: process.env.FALLBACK_TO_CONVEX !== "false", // Default: true
};

// lib/mcp-token-injector.ts - Dual-mode support
export async function injectUserTokensToMCP(userId: string, convexAuthToken: string) {
  // Try Auth0 Token Vault first if enabled
  if (AUTH0_FEATURE_FLAGS.USE_TOKEN_VAULT_GOOGLE) {
    try {
      return await injectTokensFromAuth0(userId);
    } catch (error) {
      // Automatic fallback to Convex if Token Vault fails
      if (AUTH0_FEATURE_FLAGS.FALLBACK_TO_CONVEX) {
        return await injectTokensFromConvex(userId, convexAuthToken);
      }
    }
  }

  // Use Convex approach (legacy mode)
  return await injectTokensFromConvex(userId, convexAuthToken);
}

Zero-downtime migration, safe fallback, gradual rollout. That's production-ready engineering! 💪

The Technical Journey (Because Y'all Love the Details!)

Setting Up Auth0 Was Surprisingly Easy

I won't lie – when I first saw "OAuth 2.0," "JWKS," and "Token Vault" in the Auth0 docs, I had flashbacks to authentication nightmares. But Auth0's documentation (especially the AI agents section) is really good.

Here's my setup process:

1. Created an Auth0 Application

Took 5 minutes in the Auth0 Dashboard
Configured callback URLs (localhost for dev, production domain for deployment)
Got my client ID, secret, and domain

2. Added Environment Variables

AUTH0_SECRET='generated-with-openssl-rand'
AUTH0_BASE_URL='http://localhost:3000'
AUTH0_ISSUER_BASE_URL='https://your-domain.auth0.com'
AUTH0_CLIENT_ID='your-client-id'
AUTH0_CLIENT_SECRET='your-client-secret'
AUTH0_AUDIENCE='https://api.studyflow.com'
AUTH0_SCOPE='openid profile email offline_access read:user'

3. Built the Settings Page

This was the fun part! I created a dashboard where students can manage their Auth0 connection:

// Get user session and token info
export const getUser = async () => {
  const session = await auth0.getSession();
  return session?.user;
};

export const getAccessToken = async () => {
  const tokenResult = await auth0.getAccessToken();

  if(!tokenResult || !tokenResult.token) {
    throw new Error("No access token found in Auth0 session");
  }

  return tokenResult.token;
};

The Settings page shows:

Connection status (Connected/Disconnected)
User profile info from Auth0
Active permissions and scopes
Token expiry information
One-click connect/disconnect buttons

4. Secured MentorMind API Routes

Every AI helper endpoint now verifies Auth0 JWTs:

export async function POST(request: Request) {
  try {
    // Verify the Auth0 JWT token
    const user = await verifyAuth0Request(request);

    console.log('Authenticated user:', user.email);
    console.log('Permissions:', user.permissions);

    // Check required permission
    if (!user.permissions.includes('ai:query')) {
      return Response.json(
        { error: 'Missing ai:query permission' },
        { status: 403 }
      );
    }

    // Your AI logic here (now securely!)
    const aiResponse = await callOpenAI(prompt);

    return Response.json({ response: aiResponse });

  } catch (error) {
    return Response.json(
      { error: 'Unauthorized' },
      { status: 401 }
    );
  }
}

What I Learned About Auth0 for AI Agents

Token Vault is Brilliant: It abstracts away OAuth complexity while maintaining security. Your AI agent gets access tokens when it needs them, without you managing refresh logic.
JWKS Verification is Fast: I was worried about latency, but verifying JWTs is lightning quick. No noticeable impact on response times.
Scope Management is User-Friendly: Auth0's consent screens are clear and non-scary. Users actually understand what they're granting access to!
Documentation Rocks: The Auth0 AI Agents docs have excellent code examples for Python, TypeScript, and JavaScript. I basically copied, tweaked, and shipped.
It Scales: This isn't some hacky solution. Auth0 is enterprise-grade, which means as StudyMate grows, authentication won't be a bottleneck.

Real Features This Unlocked 🚀

With Auth0 Token Vault integrated, here's what's actually working in production:

✅ Smart Schedule Suggestions (LIVE!)

Status: Fully implemented and tested with real Google Calendar API (Currently it's not verified by Google so you might face some consent screen warnings, but works perfectly otherwise)

Tech: Heroku-deployed MCP server at calendar-mcp-server-2ff7c546d7e7.herokuapp.com

MentorMind can access your Google Calendar and suggest study times when you're actually free. No more "study at 2 PM" advice when you have a class then!

10 Working Calendar Tools:

list-calendars - View all your calendars
list-events - See events in any time range
create-event - Add study sessions to calendar
update-event - Modify existing events
delete-event - Remove calendar entries
get-event - Get details of specific events
search-events - Search calendar by keywords
get-freebusy - Check when you're available
list-colors - Calendar color options
get-current-time - Timezone-aware current time

Real test from December 25, 2025:

User: Anshu Mandal
Calendars retrieved: 2 ("Holidays in India" + personal)
Token refresh: Automatic via Auth0
API call latency: <50ms

🔄 MCP Integration (Production Infrastructure!)

Status: Deployed and operational
Architecture:

Heroku MCP server (Node.js)
Convex integration mode
Multi-user token isolation
Rate limiting: 100 requests per user per 15 min
Automatic token cleanup after 24h inactivity
API key authentication + CORS protection

Security features:

✅ Per-user token isolation
✅ Encrypted token storage
✅ Automatic token refresh
✅ CORS protection
✅ Rate limiting
✅ API key authentication

🎵 Spotify Integration (Ready with ONE Feature Flag!)

Status: Code complete, pending Auth0 connection setup

The Spotify integration is fully coded and ready to enable. All it needs:

# In Auth0: Configure Spotify OAuth connection
# In .env: Set feature flag
USE_TOKEN_VAULT_SPOTIFY=true

Then boom! MentorMind can control your Spotify playback during study sessions. Same Token Vault pattern, same security, zero additional code needed.

// lib/auth0-ai.ts - ALREADY WRITTEN
export const createSpotifyTokenVault = (accessToken: string) => {
  return auth0AI.withTokenVault({
    connection: "spotify",
    scopes: [
      "user-read-playback-state",
      "user-modify-playback-state",
      "user-read-currently-playing",
      "playlist-read-private",
    ],
  });
};

Features ready to unlock:

Play focus playlists when starting study session
Pause music during breaks
Resume after break ends
Analyze listening patterns to optimize study music

🔮 Future APIs (Same Easy Pattern!)

The Token Vault architecture makes it trivial to add:

GitHub - Connect repos for code-related study tasks
Notion - Sync study notes and knowledge base
Gmail - Track email-based assignments
Google Drive - Analyze lecture notes and PDFs

Each one follows the same pattern:

Configure OAuth connection in Auth0 (5 min)
Add createXTokenVault() function (10 lines)
Enable feature flag
Ship! 🚀

Real Testing = Real Results 🧪

Let me show you the actual test data from December 25, 2025. Not mock data. Not simulated. Real API calls with real tokens.

Test Results (100% Pass Rate)

Phase 1: MCP Server Standalone ✅

✅ Server installation and build
✅ Server startup in Convex mode
✅ Health endpoint responding
✅ Metrics endpoint operational
✅ Version endpoint working
✅ API key authentication (rejected invalid keys)
✅ CORS protection (blocked unauthorized origins)
✅ Token injection with mock data
✅ Token status checking
✅ Token deletion and verification

Phase 2: Integration Testing ✅

✅ Token injection from Convex
✅ Real Google Calendar API calls
✅ Multi-user token isolation
✅ Automatic token refresh
✅ MCP server health checks
✅ Active users tracking

Total: 16/16 tests passed (100% success rate)

Real Production Test (October 25, 2025)

Test User: Anshu Mandal (23t0413037030@gandhinagaruni.ac.in)
Test Query: "What's on my calendar?"

[Token Flow]
1. ✅ Token refresh via Google OAuth API: SUCCESS
2. ✅ Token injection to MCP server: SUCCESS
3. ✅ Token validation (60 min validity): SUCCESS
4. ✅ Real Google Calendar API call: SUCCESS

[Results]
Calendars Retrieved: 2
- "Holidays in India" (reader access)
- "ansjwsksk@gmail.com" (owner access)

[Performance]
- Token injection latency: <50ms
- Calendar API latency: <200ms
- Total round-trip: <300ms

[User Tracking]
- MCP server active users: 1
- Token expiry: 59 minutes
- Source: auth0-token-vault

What Makes This Test Significant

Real User - Not test_user_123, but an actual Google account with real calendars
Real Tokens - OAuth tokens from Google, managed by Auth0 Token Vault
Real API - Actual Google Calendar API calls, not mocks
Real Infrastructure - Heroku-deployed MCP server, production environment
Real Performance - Sub-second response times with token refresh

Security Validation ✅

All security features tested:

✅ API key authentication (rejected invalid keys)
✅ CORS protection (blocked unauthorized origins)
✅ Rate limiting configured
✅ Token isolation per user verified
✅ Automatic token cleanup working
✅ No token logging (security best practice)
✅ Environment variable security validated

The Logs Don't Lie 📝

Here's actual output from the test:

[MCP Server] Token injection request received
  └─ User ID: <user-id>
  └─ Source: auth0-token-vault
  └─ Scopes: calendar.readonly, events.readonly, freebusy
  └─ Expiry: 3600 seconds (60 min)

[MCP Server] Tokens stored successfully
  └─ Active users: 1
  └─ Token valid: true
  └─ Refresh needed: false

[Google Calendar API] list-calendars called
  └─ User: Anshu Mandal
  └─ Calendars found: 2
  └─ Response time: 187ms
  └─ Status: 200 OK

✅ ALL SYSTEMS OPERATIONAL

This isn't a demo. This is production-ready code handling real user data! 🚀

The Meta Experience (Because It Wouldn't Be Complete Without This!)

So here's the best part: I used MentorMind (with Auth0 integration) while building the Auth0 integration. And now that it has Google Calendar access, the meta experience got even better!

Early October 2025 (Building the integration):

Me: "MentorMind, I'm trying to implement Token Vault. Can you suggest a good workflow?"

MentorMind (powered by Auth0-secured AI): "Based on Auth0's documentation, here's a step-by-step guide..." (It actually fetched docs via the fetch MCP tool!)

Then I asked: "When should I take a break? I've been coding for 3 hours."

MentorMind: "Based on your study patterns, you should take a 15-minute break now. You're most productive when you take breaks every 90-120 minutes."

October 25, 2025 (After calendar integration):

Me: "When should I take a break? I've been coding for 3 hours."

MentorMind (now checking my actual Google Calendar via Auth0 Token Vault): "You have a meeting in 30 minutes. Take a 15-minute break now, then wrap up your current task before the meeting. Based on your calendar, you'll have a 2-hour free block after the meeting – perfect for deep work!"

🤯 MIND. BLOWN.

The AI went from making general suggestions to giving me context-aware advice based on my actual schedule! And it did this securely, with proper OAuth, with tokens I can revoke anytime.

THIS IS WHY I BUILD STUFF! 🎉

That moment when your tool helps you build the tool, and then gets even better at helping you because of what you just built? Chef's kiss. 👨‍🍳💋

Why Auth0 is Perfect for AI Agents (Not Just Regular Apps)

Here's what makes Auth0 specifically great for AI agent use cases:

Token Vault for Third-Party APIs: AI agents need to access multiple services (calendars, emails, project management tools). Token Vault makes this seamless and secure.
Fine-Grained Scopes: Users can grant only the permissions they're comfortable with. This is crucial for AI – people are (rightfully!) cautious about what AI can access.
Automatic Token Refresh: AI agents often run background tasks or scheduled jobs. Auth0 handles token expiry and refresh automatically, so your agent doesn't randomly fail when a token expires.
JWKS-Based Verification: Fast, secure, and stateless. Perfect for serverless AI endpoints that need to verify identity without database lookups.
User Context in AI: The verified JWT payload includes user email, ID, and custom claims. This context helps the AI personalize responses appropriately.
Human-in-the-Loop Ready: CIBA and other async auth flows mean you can build AI agents that request approval before sensitive actions. Responsible AI FTW!

Challenges and Learnings (The Real Talk Section)

Challenge 1: Understanding OAuth vs JWT vs Tokens

The confusion: At first, I was mixing up access tokens, ID tokens, refresh tokens, and JWTs. What's the difference?!

The solution: Auth0's docs clarified this beautifully:

ID Token: Who the user is (JWT with user info)
Access Token: What the user can access (JWT with scopes/permissions)
Refresh Token: How to get new access tokens (not a JWT!)

For AI agents, you primarily care about access tokens (to call APIs) and refresh tokens (to keep sessions alive).

Challenge 2: Token Vault vs Direct OAuth

The confusion: Should I implement OAuth flows myself or use Token Vault?

The solution: Use Token Vault! Unless you have very specific requirements, Token Vault abstracts all the complexity. Why reinvent the wheel when Auth0 already built the perfect wheel? 🎡

Challenge 3: Vercel Production Environment

The issue: Token Vault connection worked locally but failed on Vercel.

The fix: I was hardcoding localhost:3000 in my MCP tools fetch. Changed to use the actual request URL:

const baseUrl = process.env.VERCEL_URL 
  ? `https://${process.env.VERCEL_URL}`
  : 'http://localhost:3000';

Pro tip: Always use environment-aware URLs! 🌐

What's Next? (The Roadmap!)

Now that Auth0 is powering StudyMate's authentication and authorization, here's what I'm building next:

📧 Email Integration: Connect Gmail so MentorMind can remind you about email-based assignments
📝 Notion Sync: Import your Notion study notes for better AI context
🎧 Spotify Integration: MentorMind can play your focus playlists when you start a study session
🔔 Smart Notifications: Push notifications for study reminders (with Auth0 handling user consent for notification permissions)
👥 Collaborative AI: Multiple students in a group can share an AI assistant that understands the entire group's context

The possibilities are endless when you have secure, reliable authentication! 🚀

Try It Out! (Demo Time!)

StudyFlow with Auth0 integration is live at: https://study-flow.tech

Quick start:

Sign up / Sign in (handled by Auth0!)
Go to Settings
Grant permissions you're comfortable with
Head to MentorMind and ask something like "When's a good time for me to study this week?"
Watch the magic happen! ✨

Pro tip for testing: Click "Add sample data" during onboarding to populate your dashboard with realistic study sessions. This gives MentorMind context to work with right away!

GitHub Repository

prime399 / study-flow

StudyFlow AI 🎓

Enterprise-grade study management platform powered by Heroku Managed Inference and Model Context Protocol (MCP)

StudyFlow AI is a comprehensive learning platform that combines advanced AI capabilities with real-time analytics to help students optimize their study habits. Built on Heroku's Managed Inference infrastructure with MCP tool integration, it features MentorMind - an intelligent AI assistant capable of processing external resources and providing context-aware study guidance.

✨ Key Features

Core Functionality

🕒 Smart Study Timer - Customizable Pomodoro sessions with automatic progress tracking and statistics
🤖 MentorMind AI Assistant - RAG-powered AI with MCP tool integration for external resource access
📈 Performance Analytics - Comprehensive visual dashboards with trend analysis and insights
👥 Study Groups - Collaborative workspaces with real-time messaging and leaderboards
✅ Task Management - Kanban-style todo board with drag-and-drop, priorities, and status tracking
🏆 Competitive Features - Global and group-specific leaderboards to encourage engagement
📅 Calendar…

View on GitHub

Check out the code! Key files to look at:

Main App:

Live at: https://study-flow.tech
Deployed on: Vercel
Backend: Convex real-time database
MCP Integration: Heroku-hosted tools

What You'll See

1. Settings Page - Auth0 Token Vault Management

Connect/disconnect Auth0 account
View granted permissions and scopes
See token status and expiry
Feature flag controls (for developers)
One-click integration toggle

2. MentorMind with Live Calendar Integration
When you ask "What's on my calendar?":

Real-time Google Calendar query
Auth0 Token Vault handles tokens automatically
Response shows actual events from your calendar
All secured with OAuth, all revocable

3. MCP Tools Dashboard

10 Google Calendar tools available
Dynamic tool discovery
Real-time health status
Per-user token isolation indicator

Architecture Diagram

┌─────────────────────────────────────────────────┐
│              StudyMate User                      │
│  (Logged in via Convex Auth - GitHub/Google)    │
└──────────────────┬──────────────────────────────┘
                   │
                   ▼
┌─────────────────────────────────────────────────┐
│           MentorMind AI Agent                    │
│        (Next.js API + Heroku Inference)          │
└──────────────┬──────────────────┬────────────────┘
               │                  │
         Needs Calendar?    Needs Spotify?
               │                  │
               ▼                  ▼
┌──────────────────────┐ ┌──────────────────────┐
│  Auth0 Token Vault   │ │  Auth0 Token Vault   │
│  (Google OAuth)      │ │  (Spotify OAuth)     │
│                      │ │                      │
│  - Auto refresh      │ │  - Auto refresh      │
│  - SOC 2 encrypted   │ │  - SOC 2 encrypted   │
│  - User revocable    │ │  - User revocable    │
└──────────┬───────────┘ └──────────┬───────────┘
           │                        │
           ▼                        ▼
┌──────────────────────┐ ┌──────────────────────┐
│ Google Calendar API  │ │   Spotify API        │
│ (10 MCP tools)       │ │ (Playback control)   │
│                      │ │                      │
│ Heroku MCP Server    │ │ (Future integration) │
│ calendar-mcp-...     │ │                      │
└──────────────────────┘ └──────────────────────┘

Key Metrics

Total Code: 1,100+ lines of Auth0 integration
Documentation: 2,500+ lines across 7 detailed guides
Tests: 16/16 passed (100% success rate)
Performance: <300ms total latency for calendar queries
Security: SOC 2 Type II certified token storage
Scalability: Multi-user token isolation, rate-limited
Deployment: Production-ready on Heroku + Vercel

Final Thoughts: Auth0 Didn't Just Complete StudyMate – It Transformed It

Looking back at my original dev.to article about StudyMate, I'm amazed at how Auth0 didn't just fill a missing piece – it completely elevated what was possible.

What Changed

Before Auth0:

MentorMind gave generic study advice ("take a break every 90 minutes")
Manual token management (120+ lines of fragile code)
Limited to internal data only
Security was "good enough" (scary!)

After Auth0:

MentorMind gives context-aware advice ("you have a meeting in 30 min, take a break now")
Automatic token management (~30 lines, enterprise-grade)
Access to Google Calendar, Spotify ready, infinite possibilities
Security is SOC 2 Type II certified (I sleep well!)

The Three Key Innovations

Hybrid Auth Architecture (60% of the win)
- Kept Convex Auth for users (no UX disruption)
- Added Auth0 exclusively for third-party API tokens
- Best of both worlds, zero downtime migration
- I haven't seen this pattern documented anywhere else
75% Code Reduction (20% of the win)
- From 120 lines of manual token management → 30 lines
- From custom encryption → SOC 2 certified storage
- From fragile refresh logic → Auth0 automatic handling
- Production-ready fallback system with feature flags
MCP + Token Vault Integration (20% of the win)
- Heroku-deployed MCP server with 10 working tools
- Real-time token injection for AI agents
- Multi-user isolation, rate limiting, security
- Tested with real users, real APIs, real data

Why This Matters for AI Agents

MentorMind went from being a helpful AI assistant to being a trusted agent that can act on users' behalf – securely, transparently, and with full user control.

If you're building any kind of AI agent that needs to:

✅ Access third-party APIs on behalf of users
✅ Handle sensitive permissions with user consent
✅ Maintain security at scale (SOC 2 compliance)
✅ Give users granular control over what AI can access
✅ Support multiple APIs without reinventing OAuth each time

Then Auth0 for AI Agents is exactly what you need. I spent way less time on auth than expected (maybe 2-3 days total?), which meant more time building features students actually care about.

Plus, I get to sleep soundly knowing that authentication isn't held together with duct tape and prayers! 😅

The Numbers Don't Lie

1,100+ lines of production code
2,500+ lines of comprehensive documentation
16/16 tests passed (100% success rate)
75% code reduction for token management
<300ms latency for calendar API queries
10 working tools deployed on Heroku
1 feature flag = new API integration

Implementation date: October 25, 2025
Status: Production-ready and battle-tested
Next API: Spotify (literally just a feature flag away!)

This isn't a proof-of-concept. This isn't a demo. This is production code handling real user data with enterprise-grade security. 🚀

A Note to Fellow Builders

Remember when I said I built StudyMate during mid-sems? Well, I built this Auth0 integration during early October 2025, and the testing happened on October 25th. (Yes, I still have a problem. No, I won't stop. 😄)

But here's the thing: integrating Auth0 Token Vault was SO much easier than I expected. I was dreading it – "OAuth flows," "token management," "security best practices" – it all sounded overwhelming.

Reality check:

Day 1: Read Auth0 AI docs, set up Auth0 tenant (2 hours)
Day 2: Implemented Token Vault wrappers, got first token (4 hours)
Day 3: Added feature flags, fallback system, production polish (3 hours)
Total: Maybe 2-3 days of actual coding

That's less time than I spent debugging my manual token refresh logic! 🤦‍♂️

What I Learned

Don't reinvent the wheel - Auth0 has already solved token management better than you (or I) ever will. Just use it.
Hybrid > All-or-Nothing - You don't have to rip out your existing auth. Keep what works, add Auth0 for what you need.
Feature flags are magic - Being able to test Auth0 alongside my old system gave me confidence. Highly recommend.
Good docs matter - Auth0's AI agents documentation is genuinely excellent. Code examples in TypeScript, clear explanations, real use cases.
Testing with real data matters more - Mock tests are fine, but testing with my actual Google Calendar revealed edge cases I'd never have found otherwise.

If You're Building an AI Agent

You're probably thinking "Should I implement OAuth myself or use Auth0?"

Here's my answer: If you're building a side project or MVP, and you need to access third-party APIs on behalf of users, just use Auth0 Token Vault. Don't waste weeks implementing OAuth flows when Auth0 does it better in hours.

Your time is valuable. Spend it building features users care about, not debugging token refresh edge cases at 2 AM.

The Real Win

The best part? MentorMind asking me: "You've been coding for 3 hours. You have a meeting in 30 minutes. Take a break now?"

That's my code, checking my calendar, via Auth0's Token Vault, suggesting I take care of myself.

If that's not the most wholesome use of AI + OAuth, I don't know what is. 🥹

Now if you'll excuse me, I have actual studying to do. And yes, I'll ask MentorMind when I should start... 😅

Acknowledgments:

Huge thanks to Auth0 for the excellent documentation and AI agents features
Shoutout to the dev.to community for being awesome and supportive
And to all students building cool stuff while juggling academics – we got this! 💪

Connect with me:

GitHub: @prime399
Project: StudyMate

Let's build secure, intelligent AI agents together! 🚀

Test

Anshu Mandal — Mon, 29 Sep 2025 06:03:46 +0000

This is a submission for the KendoReact Free Components Challenge.

What I Built

Demo

KendoReact Components Used

[Optional: Code Smarter, Not Harder prize category] AI Coding Assistant Usage

[Optional: RAGs to Riches prize category] Nuclia Integration

Study-Mate: AI Powered Study Success Platform.

Anshu Mandal — Mon, 29 Sep 2025 03:55:43 +0000

This is a submission for the Heroku "Back to School" AI Challenge

What I Built (And How I Survived Mid-Sems While Building It!)

Picture this: It's 2 AM, I have a mid-semester exam in 6 hours, and instead of cramming notes, I'm debugging SSE response parsing for Heroku's MCP endpoints. Sounds crazy? Maybe. But building StudyMate during my mid-sems taught me more about time management than any productivity app ever could! 😅

StudyMate is an intelligent study management platform I built to solve a problem I face every day – managing study time effectively while juggling multiple responsibilities. Beyond traditional features like session tracking, group collaboration, and performance analytics, StudyMate AI introduces “MentorMind” – a built-in AI-powered study assistant that learns from each student’s unique learning patterns. Think of it as the study buddy I wish I had during my exams (ironically, while building the study buddy itself!).

Features

🕒 Study Timer
- Customizable Pomodoro-style study sessions
- Session tracking and statistics
📈 Performance Analytics
- Visual progress tracking
- Monthly study hour analysis
- Performance trends and insights
🤖 AI Study Assistant
- Personalized study advice
- Context-aware recommendations
- Real-time study habit analysis
- Interactive chat interface
- Study technique suggestions based on performance
- MCP (Model Context Protocol) tool integration for external resource access
- Automatic URL processing and content extraction from study materials
👥 Study Groups
- Create and join study groups
- Group chat functionality
- Collaborative study sessions

Building this during mid-sems was both challenging and meta – I was creating a tool to help students study better while trying to study better myself. The irony wasn't lost on me when MentorMind's first advice to me was "Take breaks more often" – advice I clearly wasn't following! 😄

Demo

Study-Mate

prime399 / study-mate

StudyMate AI 🎓

Enterprise-grade study management platform powered by Heroku Managed Inference and Model Context Protocol (MCP)

StudyMate AI is a comprehensive learning platform that combines advanced AI capabilities with real-time analytics to help students optimize their study habits. Built on Heroku's Managed Inference infrastructure with MCP tool integration, it features MentorMind - an intelligent AI assistant capable of processing external resources and providing context-aware study guidance.

✨ Key Features

Core Functionality

🕒 Smart Study Timer - Customizable Pomodoro sessions with automatic progress tracking and statistics
🤖 MentorMind AI Assistant - RAG-powered AI with MCP tool integration for external resource access
📈 Performance Analytics - Comprehensive visual dashboards with trend analysis and insights
👥 Study Groups - Collaborative workspaces with real-time messaging and leaderboards
✅ Task Management - Kanban-style todo board with drag-and-drop, priorities, and status tracking
🏆 Competitive Features - Global and group-specific leaderboards to encourage engagement
📅 Calendar…

View on GitHub

Dashboard:

Study-Timer:

MentorMind:

The Journey: Building with Heroku's Managed Inference

Let me tell you – working with Heroku's Managed Inference was an absolute blast! Even while balancing study schedules, I genuinely enjoyed piecing everything together. Here's how I leveraged Heroku's infrastructure to create an intelligent, adaptive study companion:

1. Multi-Agent Architecture

I implemented a sophisticated three-agent system, each optimized for specific use cases:

GPT-OSS Agent: Handles general study advice, learning strategies, and educational content generation. This agent provides comprehensive explanations and study methodology recommendations.
Nova Lite Agent: Optimized for real-time interactions and quick responses. Powers the interactive chat interface where students need immediate feedback and guidance during study sessions.
Claude Agent: Specializes in deep analysis of study patterns, performance metrics, and behavioral insights. Processes complex data to generate personalized long-term study plans and identifies learning bottlenecks.

2. Intelligent Agent Orchestration

The agents work in coordination through a custom routing system:

User queries are analyzed and routed to the most appropriate agent based on complexity, urgency, and context
Agents share context about the student's profile, including study history, performance trends, and learning preferences
Session continuity is maintained across agent switches for seamless conversations

3. Context-Aware Personalization

Heroku's Managed Inference enables MentorMind to:

Analyze students' study session data (duration, subjects, time of day) to identify optimal learning windows
Process performance metrics to detect struggling areas and recommend targeted interventions
Track conversation history to provide increasingly personalized advice over time
Adapt recommendations based on real-time feedback and study outcomes

4. The MCP Adventure: My Biggest Challenge (and Victory!)

Okay, so implementing Model Context Protocol (MCP) support was... intense. I'm talking multiple cups of coffee, countless "why isn't this working?!" moments, and a lot of late nights. But honestly? It was also the most fun I had building this project!

The Struggle Was Real:

When I first dove into MCP integration, I thought "How hard could it be?" (Famous last words, right? 😅). Here's what I was dealing with:

Different Endpoints Everywhere: Heroku's MCP needed /v1/agents/heroku instead of the standard chat completions endpoint I was using. Had to completely rethink my routing logic.
SSE Parsing Headaches: Server-Sent Events format was new territory for me. Unlike the clean JSON responses from OpenAI's client, I had to manually parse streaming data line by line. At 3 AM, those data: prefixes all started looking the same 😴
Dynamic Tools = Dynamic Problems: I couldn't hardcode tools because MCP servers could change anytime. Everything had to be fetched and configured on the fly.
UI/UX Puzzle: How do you show users that tools are available without making them think they must select one? Spent days on this alone!

Shoutout to Heroku's Documentation:

This is where I need to give MAJOR props to Heroku's team! 🙌

Their GitHub documentation for MCP servers was an absolute lifesaver. Seriously, when I was stuck trying to understand how to structure my MCP server requests, those GitHub docs came in clutch! Clear examples, good structure, and exactly what I needed when I needed it. I probably had that tab open 24/7 during the build week.

The Managed Inference docs were also solid and helped me understand the architecture. Though, I'll be honest – I wish there were more library suggestions and code examples early on. I spent a good chunk of time hunting down the right Node.js libraries and patterns for SSE parsing. Would've saved me a few late nights if those were front and center! But hey, the learning journey made the victory sweeter 😊

The Breakthrough:

After what felt like a hundred iterations (probably was more like ten, but who's counting?), I cracked it with a hybrid approach:

Dynamic Tool Discovery: Every request fetches the latest tools from /v1/mcp/servers – always fresh, always up to date
Give the AI Everything: Instead of limiting tools based on user selection, I send ALL available tools to the agent and let the AI decide what to use. Smart agents deserve smart tooling!
Custom SSE Parser: Built my own parser that handles Heroku's streaming format gracefully (took me a while to get this right!)
Graceful Fallback: No tools available? No problem – falls back to standard chat completions seamlessly

Why This Makes MentorMind Actually Useful:

Here's the magic moment – when all this technical complexity comes together into something simple and powerful for students:

Just Drop a URL: Students don't need to know about MCP, tools, or anything technical. Just paste a URL to their study material and ask a question. Done. ✨
Automatic Everything: MentorMind fetches the content, reads it, understands it, and answers in context of their study goals
Real-time Learning Support: Studying from an online article? PDF lecture notes? Research paper? MentorMind can now actually READ them with you!
Zero Friction: No "click here to enable tool" nonsense. It just works.

Real example: A student types "Summarize this lecture PDF: [URL] and tell me which topics I should focus on based on my weak areas." MentorMind fetches the PDF, analyzes it against the student's performance data, and gives targeted advice. That's when I knew all those late nights were worth it! 🎯

The best part? I used MentorMind to help me study for my mid-sems by feeding it my lecture notes. Meta? Absolutely. Helpful? You bet! Got a B+ on that exam I was supposed to fail 😄

Technical Implementation (The Nerdy Details!)

For those who love diving into the code (like me at 2 AM apparently 😅), here's how everything fits together:

Frontend Architecture

Framework: Next.js 14 with TypeScript and App Router (type safety saved me from so many bugs during exam stress!)
UI Components: Shadcn/ui with Tailwind CSS styling (made it look professional even when I was running on 3 hours of sleep)
Real-time Data: Convex React hooks for reactive queries (watching data update in real-time never gets old!)

MentorMind Architecture (RAG + MCP Magic ✨)

This is where things get fun! MentorMind uses a RAG (Retrieval-Augmented Generation) architecture supercharged with MCP tools:

Multi-Model Support: Dynamic routing between GPT-OSS 120B, Nova Lite/Pro, and Claude 3.5 Haiku
Real-time Chat: Streaming responses that feel snappy and responsive
Context-Aware: Pulls in user study data, group info, and performance metrics automatically
MCP Tool Integration: This is the secret sauce – automatic external resource access!

Here's the Chat Flow I Pieced Together:

export async function POST(req: Request) {
  try {
    const { messages, userName, studyStats, groupInfo, modelId } = await req.json()

    const config = validateOpenAIConfig(modelId)
    const systemPrompt = buildSystemPrompt({ userName, studyStats, groupInfo })

    // Fetch all available MCP tools dynamically
    const availableMcpTools = await fetchAvailableMcpTools()

    // Enhance system prompt with tool descriptions
    if (availableMcpTools.length > 0) {
      const toolsList = availableMcpTools
        .map(tool => `- ${tool.name}: ${tool.description}`)
        .join('\n')

      systemPrompt += `\n\nYou have access to the following MCP tools:
${toolsList}

Use these tools proactively when they can help provide better answers.`
    }

    const chatMessages = [
      { role: "system", content: systemPrompt },
      ...sanitizeMessages(messages),
    ]

    let completion

    // Route to appropriate endpoint based on tool availability
    if (availableMcpTools.length > 0) {
      completion = await callHerokuAgentsEndpoint(
        config,
        chatMessages,
        availableMcpTools
      )
    } else {
      const client = createOpenAIClient(config)
      completion = await client.chat.completions.create({
        model: config.herokuModelId,
        messages: chatMessages,
      })
    }

    return Response.json({ ...completion })
  } catch (error) {
    // Error handling
  }
}

The MCP Endpoint Handler (My Pride and Joy!):

This function took me DAYS to get right. The SSE parsing especially gave me grief, but seeing it work for the first time was pure joy!

async function callHerokuAgentsEndpoint(
  config: HerokuConfig,
  messages: ChatMessage[],
  mcpTools: McpTool[]
) {
  const agentsUrl = `${config.herokuBaseUrl}/v1/agents/heroku`

  // Transform tools to Heroku's MCP format
  const toolsArray = mcpTools.map(tool => ({
    type: "mcp",
    name: tool.id,  // e.g., "fetch/read_url"
  }))

  const response = await fetch(agentsUrl, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${config.herokuApiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: config.herokuModelId,
      messages,
      tools: toolsArray,  // All tools available to AI
    }),
  })

  // Parse SSE response format
  const text = await response.text()
  const lines = text.split('\n')
  let lastCompletion = null

  for (const line of lines) {
    if (line.startsWith('data:')) {
      const data = line.slice(5).trim()
      if (data === '[DONE]') break

      const parsed = JSON.parse(data)
      if (parsed.object === 'chat.completion') {
        lastCompletion = parsed
      }
    }
  }

  return lastCompletion
}

Backend Architecture (The Foundation)

Database: Convex with real-time subscriptions and optimistic updates (seriously amazing for building fast!)
Authentication: Convex Auth with secure session management
API Routes: Next.js API routes handling all the Heroku Inference magic
Data Models: Clean, structured schemas for everything – future me thanks past me for this!

Real Problems I'm Solving (Because I Face Them Too!)

Building StudyMate wasn't just an academic exercise – these are problems I deal with as a student every single day:

1. "I Have No Study Structure" (Been there, done that!)

Built customizable Pomodoro sessions because traditional 25-minute blocks don't work for everyone
Session tracking helped me realize I was most productive at 9 PM (who knew?!)

2. "Am I Actually Making Progress?" (The eternal student question)

Visual analytics that actually make sense – no PhD in data science required
Monthly trends that showed me exactly when I was slacking (looking at you, August 😅)

3. "I Need Personalized Help, Not Generic Advice" (The reason MentorMind exists)

Context-aware recommendations based on YOUR data, not some average student
Real-time analysis that learns from your patterns – tested extensively on myself during mid-sems!

4. "Studying Alone is Boring" (Let's be real)

Global rankings for friendly competition (I'm currently ranked #3, coming for that first Position! 🎯)
Study group leaderboards that make group study actually engaging
Personal best tracking – sometimes competing with yourself is the best motivation

What I Actually Pulled Off (Despite Mid-Sems!)

Honestly, I'm pretty proud of what got built here:

✅ Full MCP Integration: Real-time external data retrieval actually WORKS (and it's beautiful!)
✅ Dynamic Tool Discovery: Tools update automatically – no hardcoding, no manual config
✅ Smart Routing: Seamlessly switches between regular chat and MCP-enhanced responses
✅ Multi-Model Architecture: Three different AI models working together harmoniously
✅ Built During Exams: Somehow managed to code, study, and sleep (occasionally) 😴

What's Next? (When I'm Not Studying!)

The journey doesn't stop here! Future plans include:

Voice Interaction: Hands-free studying for when you're pacing around trying to memorize things
Code Execution Environment: For my fellow CS students who need to test code snippets quickly
Calendar Integration: Auto-schedule study sessions (because manual planning is so 2024)
Mobile App: Study tracking on the go – because we're always on the go!

A Quick Note to Fellow Students

If you're reading this thinking "I could never build something like this" – trust me, I thought the same thing at the start! Building StudyMate taught me that the best way to learn is to build something you actually need. Plus, there's something special about using a tool you built yourself to help you study for the exams you should've been studying for instead of coding 😄

Many students are already using StudyMate and seeing real improvements. The Pomodoro sessions especially seem to click with people – breaking studying into focused chunks really does help you get more done (even worked for me while building this!).

Want to Try It? Here's a Pro Tip!

Hey judges (and curious students!) – I've got a little feature I'm excited about!

When you first onboard, you'll see an "Add sample data" button. It's totally optional, but here's why you might want to click it:

It populates your dashboard with realistic study session data, so you can immediately see how MentorMind gives personalized advice based on actual patterns. Without sample data, MentorMind doesn't have much context about you yet (it's smart, but it's not psychic! 😉).

Pro move: Import the sample data, then ask MentorMind something like "What subjects should I focus on?" or "When am I most productive?" You'll see how it analyzes the data and gives targeted recommendations. It's way cooler than starting with an empty dashboard!

Plus, it'll save you from having to run actual study sessions just to test the AI features. Though if you want to do that too, be my guest – maybe it'll inspire you to actually study 😄

Circuit Skies- Explore the Unexplored and beat Enemies

Anshu Mandal — Mon, 28 Apr 2025 06:55:58 +0000

This is a submission for the Alibaba Cloud Challenge: Build a Web Game.*

What I Built

Circuit Skies - A Fast-Paced Robot Platformer

Circuit Skies is a 2D platformer game built with the Godot Engine. Inspired by the fast-paced precision gameplay of games like BZZZT, Circuit Skies puts you in control of a nimble robot navigating challenging levels.

🏃‍♂️ Classic platforming actions: Run and jump through challenging levels filled with hazards.
💨 Dash mechanic: Press "D" + <- or -> button to dash for quick bursts of speed—perfect for dodging obstacles and enemies. Dashing consumes a regenerating boost meter, so use it wisely!
🪙 Collect coins: Gather coins scattered throughout level to reach on top of leaderboard.
👾 Avoid hazards and enemies: Watch out for dangerous traps and enemies like green and purple slimes.
🚪 Reach the exit: Your goal is to make it to the exit point of each level.
❤️ Health regeneration: Recover health over time and gain temporary invincibility after taking damage.
🏆 Online leaderboard: Compete for the best scores and see how you rank against other players!

Demo

Play the game here: [https://circuit-skies.mhlinks.tech/]

prime399 / circuit-skies

Circuit Skies - A Fast-Paced Robot Platformer

Overview

Demo

Play the game here: https://circuit-skies.mhlinks.tech/
GitHub Repository: https://github.com/prime399/circuit-skies
Screenshots:

Gameplay Features

The core gameplay revolves around classic platforming mechanics with modern additions:

🏃‍♂️ Classic platforming actions: Run and jump through challenging levels filled with hazards.
💨 Dash mechanic: Press "D" + <- or -> button to dash for quick bursts of speed—perfect for dodging obstacles and enemies. Dashing consumes a regenerating boost meter.
🪙 Collect coins: Gather coins scattered throughout levels to achieve a high score for the leaderboard.
👾 Avoid hazards and enemies: Watch out for dangerous traps and enemies like green and purple slimes. The player can take damage…

View on GitHub

Screenshots:

Alibaba Cloud Services Implementation ☁️

Circuit Skies leverages these powerful Alibaba Cloud services:

🖥️ Elastic Compute Service (ECS)

Purpose: Hosts the game's web build with scalability and reliability
Implementation: Serves Godot HTML5 export files via a web server
Experience: Quick setup with excellent deployment control

💾 ApsaraDB RDS for MariaDB

Purpose: Powers the online leaderboard system
Implementation: FastAPI backend connects to MariaDB for score management
Benefits: Automated backups and robust connection security

🌐 API Gateway

Purpose: Manages and secures all leaderboard API requests
Implementation: Routes requests to ECS while ensuring security
Benefits: Streamlined API management with enhanced protection

Note: I used Nginx to serve static files and reverse-proxy the FastAPI server

Leaderboard API Implementation:

# Score submission endpoint
@app.post("/submit")
def submit_score(score_data: Score):
    if score_data.score == 0:
        return {"message": f"Ignoring zero score for {score_data.name}"}

    sql = """
        INSERT INTO leaderboard (name, score) VALUES (%s, %s)
        ON DUPLICATE KEY
          UPDATE score = IF(VALUES(score) > score, VALUES(score), score)
    """
    try:
        with get_db() as conn, conn.cursor() as cur:
            cur.execute(sql, (score_data.name, score_data.score))
            conn.commit()
        return {"message": "Score recorded"}
    except:
        raise HTTPException(status_code=500, detail="Internal server error")

# Leaderboard retrieval endpoint
@app.get("/leaderboard")
def get_leaderboard():
    conn = get_db()
    cursor = conn.cursor()
    cursor.execute("SELECT name, score FROM leaderboard ORDER BY score DESC LIMIT 10")
    rows = cursor.fetchall()
    conn.close()
    return [{"name": row[0], "score": row[1]} for row in rows]

Experience & Challenges 🚧

Holy smokes, Alibaba Cloud services were an absolute dream to work with! As a CS student, I was practically giddy seeing how smoothly ECS and ApsaraDb RDS for MariaDB integrated into my workflow. The documentation was crystal clear, and I found myself setting things up faster than expected.

Tackling the leaderboard API was where I really got to flex my coding muscles! Optimizing that database schema for lightning-fast reads and writes gave me that perfect blend of frustration and satisfaction that only fellow coders understand. When those scores started updating correctly, I may have done a little victory dance at my desk! 😂

The Godot Engine threw me some curveballs, especially that physics engine it was like trying to tame a wild beast! There were nights I wanted to throw my keyboard out the window, but when I finally got that player controller feeling just right? Pure. Digital. Magic.

I became obsessed with playtesting- roping in my roommates, classmates, and pretty much anyone who'd give me 10 minutes of their time.

Combining all these different technologies into one cohesive project was like assembling my own infinity gauntlet of tech skills! As a CS student, there's nothing more thrilling than seeing theory transform into practice. This project wasn't just a learning experience, it was a technical playground where I got to build something awesome while having an absolute blast doing it!

Game Development Highlights ✨🚀

First Game: This was my very first game, I had to learn a lot in just a week, atfirst I got stuck using Phisor Editor and really couldn't able to do what I really wanted to do, like I wanted to make my camera follow my player while making sure background don't collapse, 🎮

Core Mechanics: Implementing the responsive player controller, especially the dash mechanic with its boost cost and visual feedback (ghosting effect), was a key focus to capture the desired fast-paced feel. 💨🕹️
Retro Aesthetics: I wanted to create a retro-inspired pixel art style, luckly I stumbled upon a greate designer who has made their robot sprite free for anyone, but I had to design tilemap and other assets myself using asprite which was fun✨

Credits🙏

robo pack: https://au-pixel.itch.io/robotbasepack
sound effects: https://itch.io/
soundtrack: https://freesound.org/