truden

Hold Alt and shake your mouse anywhere in your web app to capture and snip UI for AI assistants.

Truden gives your web application an instant screen-snipping overlay. Users select any region on the screen (or press Enter for full viewport), and the capture is either:

1. Mode A (Frontend Only): Handed directly to your in-app multimodal AI chat assistant as an image Blob with zero backend setup.
2. Mode B (Vision LLM Backend): POSTed to a backend route handler where your preferred AI SDK analyzes the image and returns a text description.

Installation

npm install truden
# or
pnpm add truden
# or
yarn add truden

2-Minute Quickstart

Mode A: Direct Image Attachment (Frontend Only)

import { useEffect, useState } from "react";
import truden from "truden";

export default function App() {
  const [imageBlob, setImageBlob] = useState<Blob | null>(null);

  useEffect(() => {
    // Initializes Alt+shake and triggers
    return truden.init({
      onResult: (blob: Blob) => {
        console.log("Captured image:", blob);
        setImageBlob(blob); // Attach to your AI chat prompt!
      },
    });
  }, []);

  return (
    <div>
      <h1>My Application</h1>
      <p>Hold Alt and shake mouse to snip!</p>
      {imageBlob && (
        <img
          src={URL.createObjectURL(imageBlob)}
          alt="Captured snippet"
          style={{ maxWidth: 400, marginTop: 16, borderRadius: 8, display: "block" }}
        />
      )}
    </div>
  );
}

Mode B: Vision LLM Analysis (Server Adapter)

1. Server Route Handler (app/api/truden/route.ts)

import { handler } from "truden/server";
import { openai } from "@ai-sdk/openai";
import { generateText } from "ai";

export const POST = handler({
  analyze: async ({ image, prompt }) => {
    const { text } = await generateText({
      model: openai("gpt-4o"),
      messages: [
        {
          role: "user",
          content: [
            { type: "image", image },
            { type: "text", text: prompt },
          ],
        },
      ],
    });
    return text;
  },
});

2. Client Setup

import { useEffect } from "react";
import truden from "truden";

export default function App() {
  useEffect(() => {
    return truden.init({
      endpoint: "/api/truden",
      onResult: (description: string) => {
        console.log("Vision analysis:", description);
      },
    });
  }, []);

  return <div>App Content</div>;
}

Triggers

Trigger	Default	How to Activate
Alt + Shake	Enabled	HoldAlt and shake mouse horizontally
Keyboard Shortcut	Ctrl+Shift+S	PressCtrl+Shift+S (or Cmd+Shift+S on Mac)
Floating Button	Disabled	Enable withfloatingButton: true in init()
Custom Event	truden:open	window.dispatchEvent(new CustomEvent('truden:open'))
Touch Long-Press	Enabled (600ms)	Press and hold on touchscreen
Programmatic	Always available	Calltruden.open() from any button or hook

Documentation

Comprehensive guides and API reference are available in the /documentation directory:

• 📖 Getting Started
• 🚀 Framework & Platform Guides (React, Next.js, Svelte, Vue, Angular, TanStack Start, Solid, Vanilla)
• 🎯 Trigger Configurations
• 🖼️ Mode A: Frontend AI Assistants
• 🤖 Mode B: Vision LLM Adapters
• 📚 Complete API Reference
• ⚠️ Known Limitations & Security

---

License

MIT © Francis Igwe