The foundational layer for agentic interfaces
Build any agent UI.
ThoughtSurgery is a framework-agnostic, headless toolkit that gives you real-time observability, mid-stream intervention, and safe state manipulation for AI agents. From code copilots to autonomous research pipelines — if it has an agent, you can steer it.
The Problem
Today's agent UIs are blind.
No Observability
You fire a prompt and stare at a loading spinner. What is the agent thinking? You have no idea until it's done.
No Intervention
The agent drifts off-course. Your only option? Kill the process and start over from scratch. Minutes of compute, wasted.
No Safe Editing
When agents modify files, naive string replacements corrupt code. One bad regex and your codebase is broken.
What You Can Build
Endless possibilities, one toolkit.
ThoughtSurgery isn't a template — it's a layer. Every UI below is buildable with the same primitive: useAgentUI(). Here's a glimpse at the interfaces developers are creating.
AI Coding Copilot
Watch your agent write code in real-time, token by token. See exactly where it's headed. Don't like the approach? Hit Halt & Intervene, change the system prompt to "use try-catch instead of if-checks," and resume. The agent adapts instantly.
const { agentState, sendCommand, intervene } = useAgentUI();
// Watch tokens stream in real-time
<pre>{agentState.tokens.join('')}</pre>
// Halt mid-generation
sendCommand('PAUSE');
// Inject new instructions
intervene({ systemPrompt: 'Use try-catch patterns.' });
// Resume with new behavior
sendCommand('RESUME');Research Pipeline Observer
Multi-step agentic workflows are notoriously opaque. With ThoughtSurgery, you can visualize each stage — query decomposition, retrieval, reasoning, synthesis — as state_change events. Intervene at any checkpoint: swap data sources, refine the query, or skip a step entirely.
// Listen for pipeline stage transitions
agentState.tokens // live reasoning stream
agentState.status // 'running' | 'paused' | 'awaiting_human_input'
agentState.stage // custom field via state_change events
// Your adapter emits stage updates:
this.emitEvent(ctx, {
type: 'state_change',
payload: { stage: 'synthesizing', sources: 12 }
});Multi-Agent Command Center
Orchestrate entire fleets of agents from a single dashboard. Each agent gets its ownAgentUIProvider with independent state, streaming, and intervention controls. Pause one, redirect another, swap a failed agent's backend — all without restarting the pipeline.
// Each agent gets its own provider and SSE stream
<AgentUIProvider endpoint="/api/stream?agent=research">
<AgentTile title="Research Agent" />
</AgentUIProvider>
<AgentUIProvider endpoint="/api/stream?agent=writer">
<AgentTile title="Writer Agent" />
</AgentUIProvider>
// Each tile independently reads its own state
const { agentState, sendCommand } = useAgentUI();The lighthouse keeper climbed the spiral staircase, each step echoing like a heartbeat in the throat of the tower. She pressed her palm against the cold glass and watched the storm gather its dark orchestra over the sea—
Creative Writing Studio
A novelist's dream interface. The agent writes prose while you watch each sentence form. Don't like the tone? Click a preset to inject a new voice — dramatic, literary, humorous — without losing a single word of what's already been generated. The intervene() function updates the system prompt live while preserving all accumulated tokens.
// Tone presets map to system prompts
const TONES = {
dramatic: 'Write with intense emotion and vivid imagery.',
literary: 'Write elegant prose with rich metaphors.',
humorous: 'Write with wit, irony, and comedic timing.',
};
// Inject new tone without losing output
const switchTone = (tone: string) => {
intervene({ systemPrompt: TONES[tone] });
};Autonomous DevOps Agent
Agents that deploy infrastructure need guardrails. ThoughtSurgery's awaiting_human_input status creates natural checkpoints. The agent runs autonomously through safe steps (tests, builds), then pauses and requests explicit human approval before executing high-risk operations like production deployments or database migrations.
// In your adapter — request human approval
this.emitEvent(ctx, {
type: 'state_change',
payload: {
status: 'awaiting_human_input',
checkpoint: 'production_deploy',
message: 'Ready to scale to production. Approve?'
}
});
// In the UI — render approval controls
if (agentState.status === 'awaiting_human_input') {
return <ApprovalDialog checkpoint={agentState.checkpoint} />;
}AI Document Editor
When agents edit your markdown files, one corrupted write can destroy an entire document. ThoughtSurgery's safeUpdateMarkdown() parses files into an Abstract Syntax Tree, applies edits at the node level, and serializes back — all under a per-file mutex lock. It's structurally impossible to produce invalid output.
import { safeUpdateMarkdown } from '@agentui/core/dist/ast-sync';
// Safely edit a markdown file — concurrent-proof
await safeUpdateMarkdown('./brief.md', (tree) => {
const timeline = tree.children.find(
n => n.type === 'heading' && n.children[0]?.value === 'Timeline'
);
// Insert new paragraph after the heading
const idx = tree.children.indexOf(timeline);
tree.children.splice(idx + 1, 0, {
type: 'paragraph',
children: [{ type: 'text', value: 'Phase 1 by August 15th.' }]
});
});Support Agent Supervisor
In production customer support, AI agents need human oversight in real-time. A supervisor watches the live token stream and can intervene the moment the agent is about to violate policy — like offering a refund before attempting retention. The sendCommand('PAUSE') call halts the response mid-sentence, the supervisor edits the prompt, and the agent resumes with corrected behavior. All invisible to the end customer.
// Supervisor monitors the live stream
const { agentState, sendCommand, intervene } = useAgentUI();
// Response looks wrong? Halt immediately.
sendCommand('PAUSE');
// Inject corrected instructions
intervene({
systemPrompt: 'Offer a 3-month discount before processing cancellation.'
});
// Customer never sees the interruption
sendCommand('RESUME');How It Works
A simple architecture.
Three packages. One adapter interface. Zero lock-in. Your AI backend talks to the adapter, the adapter emits events over SSE, and your React components consume them via a single hook.
Stop building blind.
Every agent UI you build deserves observability, intervention, and safe state manipulation. ThoughtSurgery gives you all three in a single, headless, framework-agnostic toolkit.