Skip to main content
The @polpo-ai/react package wraps the TypeScript SDK with React hooks and a context Provider. It connects to the SSE event stream for live updates — no polling needed.

​
Install

npm install @polpo-ai/sdk @polpo-ai/react

​
Provider setup

Wrap your app with PolpoProvider: 
import { PolpoProvider } from "@polpo-ai/react";

function App() {
  return (
    <PolpoProvider
      baseUrl="https://api.polpo.sh"
      apiKey="pk_live_..."
      autoConnect={true}
    >
      <Dashboard />
    </PolpoProvider>
  );
}
PropTypeDefaultDescription
baseUrlstringrequiredAPI base URL
apiKeystring—Project API key
autoConnectbooleantrueAuto-connect to SSE stream
eventFilterstring[]—Filter SSE events (e.g. ["task:*"])

​
Hooks

​
useTasks(filter?)

const { tasks, isLoading, error, createTask, deleteTask, retryTask } = useTasks();

// With filter
const { tasks } = useTasks({ status: "in_progress", group: "sprint-1" });

​
useTask(taskId)

const { task, isLoading, error } = useTask("task-123");

​
useMissions()

const { missions, isLoading, createMission, deleteMission } = useMissions();

​
useMission(missionId)

const {
  mission, report, isLoading,
  executeMission, abortMission, resumeMission,
  addTask, removeTask, reorderTasks,
} = useMission("mission-456");

​
useAgents()

const { agents, isLoading, addAgent, updateAgent, removeAgent } = useAgents();

​
useProcesses()

const { processes, isLoading } = useProcesses();

​
useMemory() / useAgentMemory(name)

const { memory, isLoading, save } = useMemory();
const { memory: agentMem, save: saveAgent } = useAgentMemory("backend-dev");

​
useSessions()

const { sessions, isLoading, rename, remove } = useSessions();

​
useEvents(filter?, maxEvents?)

const { events } = useEvents(["task:*", "agent:*"], 100);

​
useStats()

const { stats } = useStats();
// { pending, inProgress, done, failed, totalAgents, ... }

​
usePolpo()

Direct access to the client and store: 
const { client, store } = usePolpo();

​
Real-time updates

All hooks automatically update when SSE events arrive. No manual refetching needed. 
function TaskList() {
  const { tasks } = useTasks();

  // This component re-renders automatically when:
  // - A task is created, updated, or deleted
  // - A task transitions state
  // - The SSE connection reconnects (full refresh)

  return (
    <ul>
      {tasks.map(t => (
        <li key={t.id}>{t.title} — {t.status}</li>
      ))}
    </ul>
  );
}

​
Connection status

const { connectionStatus } = usePolpo();
// "connecting" | "connected" | "reconnecting" | "disconnected" | "error"
On reconnect, the Provider automatically refetches all resources to fill any SSE gaps.