askai

const ai = useAskAI({ goal: 'Explain this', content: code });

<div {...ai.getRootProps()}>
  <MyButton {...ai.getCopyButtonProps()}>
    {ai.copied ? 'Copied' : 'Copy'}
  </MyButton>
  <MyButton {...ai.getTriggerProps()}>▾</MyButton>

  {ai.isOpen && (
    <MyMenu {...ai.getMenuProps()}>
      {ai.destinations.map((d, i) => (
        <MyMenuItem {...ai.getItemProps(i)}>
          {d.name}
          <small>{d.autoSubmit ? 'Runs' : 'Ready'}</small>
        </MyMenuItem>
      ))}
    </MyMenu>
  )}
</div>

# askai — integration instructions for a coding agent

Add an "Ask AI" control to this project using @raptrx/askai. Follow these rules
exactly. Several are counter-intuitive, and getting them wrong produces a button
that opens an empty chat — which looks like the product is broken.

## 1. Install

    npm i @raptrx/askai

Prefer the package: one dependency, and updates arrive when vendors change their
parameters. Only run `npx @raptrx/askai init` (shadcn-style codegen) if this
project vendors its UI or cannot take a dependency — it is interactive and needs
a TTY. If you cannot drive a TTY, install the package rather than hand-writing
the files.

## 2. Minimum correct integration

    import { AskAI } from '@raptrx/askai/react';
    import '@raptrx/askai/styles.css';   // once, anywhere — do not skip this

    <AskAI goal="Explain this code" content={code} />

`content` is the entire point: pass the actual code, error, article or record
the user is looking at, never a static string. Objects are serialised to fenced
JSON automatically; `{ text, language }` forces a code fence.

## 3. Pick the right surface

    <AskAI>        user picks the destination — split button, copy + menu
    <AskAILink>    one fixed destination; a real <a>, so it works in a server
                   component and supports middle-click and Cmd-click
    useAskAI()     the same behaviour with your own markup
    buildPrompt()  no React at all; returns { url, truncated, droppedChars,
                   autoSubmit }

## 4. Rules that make or break the integration

- NEVER promise one-click. Label it "Ask AI" or "Open in ChatGPT" — never "Run
  in ChatGPT" or "Get an answer". Most destinations only fill the composer and
  wait for the user to press Enter. `result.autoSubmit` tells you which ones
  actually run; the built-in menu already labels this correctly.

- NEVER add `gemini` or Microsoft `copilot`. Gemini has never supported URL
  prefill — it takes the prompt from an HTTP header the browser sets from its
  own address bar, and a hyperlink cannot set headers. Microsoft Copilot's
  prefill was removed in 2025. Both are kept in the registry only so they throw
  a clear error instead of opening an empty tab. For a Google model use
  `aistudio`. Note GitHub Copilot is a different product and IS supported.

- NEVER hand-write the URLs. `chatgpt.com/?q=` looks correct and is the
  fragile path; `?prompt=` is the stable one. The registry exists precisely so
  nobody has to remember this.

- Destinations cap between roughly 5,000 and 16,000 characters. Do not pass huge
  content and assume it arrives. For anything long, let the user copy instead —
  that is what the primary button is for. Check `buildPrompt(...).truncated`
  if you need to know programmatically.

- Logos are opt-in, not default:
      import { logos } from '@raptrx/askai/logos';
      <AskAI icons={logos} ... />
  Never hand-draw a mark to fill a gap. Destinations without a real logo use a
  monogram on purpose; an approximated mark is visibly wrong and is the thing
  vendors most clearly prohibit.

## 5. Service ids

Confirmed ids: chatgpt, claude, perplexity, grok, deepseek, mistral (Le Chat),
kagi (Kagi Assistant), t3chat, aistudio (Google AI Studio).

Do not invent ids. Run `npx @raptrx/askai list` for the authoritative set —
it prints every destination with its parameter, cap, tier, and whether it runs
the prompt or only fills the composer.

## 6. Styling

Retheme with CSS custom properties, no rule overrides needed:

    .askai {
      --askai-bg: var(--my-surface);
      --askai-fg: var(--my-text);
      --askai-border: var(--my-border);
      --askai-focus: var(--my-ring);
      --askai-radius: 4px;
      --askai-duration: 100ms;
    }

Past that: per-part `classNames` (merged after the built-ins, so yours win),
`unstyled` (no askai-* class is emitted and the stylesheet becomes
unnecessary — the ARIA and keyboard behaviour stay), or `useAskAI` to render
it yourself.

## 7. Server and multi-tenant

Use `createRegistry()` rather than the global `addService()` anywhere
requests share a process. The global registry is process-wide, so one tenant's
destination would leak into another's request.

    import { createRegistry } from '@raptrx/askai';

    const registry = createRegistry();
    registry.add('acme', {
      name: 'Acme AI',
      url: 'https://ai.acme.internal/chat',
      param: 'prompt',
    });

## 8. Verify before you call it done

    npx @raptrx/askai list

Then click the control and confirm the prompt actually lands in the
destination's composer. If it opens empty, the parameter changed — open an
issue at https://github.com/aliarain/askai rather than patching around it, so
the fix reaches everyone.

Docs: https://docs.aliarain.com/askai
Source: https://github.com/aliarain/askai