mcpField
P
polpo-react

polpo-react

github.com/lumea-labsDevelopment040 installsUpdated 3d ago
Repository

About polpo-react

A skill for developers building Polpo applications with React runtime state, hooks, and composable chat UI. It covers implementation practices for durable sessions, tool interactions, reconnects, and attachments.

Key features

  1. 01Use runtime state and hooks
  2. 02Compose chat UI components
  3. 03Handle durable messages and reconnects
  4. 04Validate client tool calls
  5. 05Work with attachment parts and file URLs

Use cases

  1. 01Add a Polpo chat interface to an application
  2. 02Build custom message composition and interactions
  3. 03Resume durable runs and continue tool results

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/lumea-labs/polpo-skills --skill polpo-react

After installing, type/polpo-reactin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
cli.md
components.md
contract-version.md
patterns.md
runtime-chat.md
theming.md

Details

From the project README

Polpo React

Use @polpo-ai/react for runtime state and hooks. Use @polpo-ai/chat for composable UI. Keep application routing and business-side client tool execution in the consuming app.

Install

npm install @polpo-ai/chat @polpo-ai/sdk @polpo-ai/react \
  react-virtuoso lucide-react streamdown

Or add source components with npx @polpo-ai/ui add. For a new application use npx create-polpo-app.

Provider

import { PolpoProvider } from "@polpo-ai/react";

<PolpoProvider baseUrl={process.env.NEXT_PUBLIC_POLPO_URL!} autoConnect={false}>
  {children}
</PolpoProvider>

baseUrl is the project root; do not append /v1 or /api/v1. Do not expose privileged server API keys in browser bundles. Use the application's authenticated backend/proxy when credentials must remain server-side.

Chat Choice

Use the high-level component for ordinary chat:

<Chat agent="support" sessionId={sessionId} />

Use useChat directly when the product needs durable delivery, custom interactions, explicit client tools, Loop continuation, or its own message composition.

UI Invariants

  • Treat Session history from Polpo as canonical; do not duplicate optimistic messages after reconnect or client-tool continuation.
  • Show reconnecting separately from streaming and do not mark detached durable runs failed.
  • Render a client tool only after validating its name and arguments against the local handler.
  • Continue tool results with a stable idempotency key and current Session version.
  • Suggestions belong to the assistant message that produced them and are actionable only while it remains the latest message.
  • Attachments use typed content parts and authenticated file URL resolution; never place local filesystem paths in browser-visible messages.

References

Comments

Markdown supported