@hanzo/agent

The cowork/code agentic UI surface for Hanzo AI — a conversation/agent-run view with tool calls, file & diff panels, a task list, reasoning, and the composer. The richer counterpart to a plain chat surface. Powers hanzo.app's Claude cowork/code experience and the Hanzo desktop app.

Built on:

• @hanzo/gui (v7) — every UI primitive. Radix-free (Tamagui). No @radix-ui/*, no @hanzo/ui.
• @hanzo/ai — the headless client for streaming completions, tools, and the portable chat store. This package never re-implements API calls.

Install

npm install @hanzo/agent @hanzo/ai @hanzo/gui react

@hanzo/ai, @hanzo/gui, and react are peer dependencies — the host app provides them (and the @hanzo/gui theme/provider).

Quick start

import { createAiClient } from '@hanzo/ai'
import { AgentRun, useAgentRun } from '@hanzo/agent'

const client = createAiClient({ getToken: () => session.accessToken })

export function Cowork() {
  const { state, send, stop } = useAgentRun({
    client,
    model: 'claude-sonnet-4-5',
    system: 'You are a coding agent.',
    tools: [
      {
        type: 'function',
        function: {
          name: 'read_file',
          description: 'Read a file from the workspace.',
          parameters: {
            type: 'object',
            properties: { path: { type: 'string' } },
            required: ['path'],
          },
        },
      },
    ],
  })

  return <AgentRun run={state} onSend={send} onStop={stop} />
}

useAgentRun owns the presented run state, streams chat.completion.chunk deltas (text + incremental tool_calls) into turns, and exposes send/stop. AgentRun is a pure view, so you can also drive it from your own state.

Components

The top-level AgentRun composes these; each is exported and usable on its own:

| Component | Purpose | |-----------|---------| | AgentRun | Task panel + transcript + composer. The full surface. | | MessageList / MessageBubble | The scrollable transcript and a single turn. | | Composer | Growing text area + Send (Enter submits, Shift+Enter newline). | | TaskList | The agent's plan / checklist with per-item status. | | ToolCall / ToolCallList | A tool invocation: name + status, expandable args/result. | | FilePanel / FilePanelList | A file the agent touched (diff or contents). | | FileDiff | Unified-diff renderer with +/- coloring. | | CodeBlock | Monospace code surface with optional gutter and header. | | Reasoning | Collapsible chain-of-thought. | | Disclosure | The expand/collapse primitive the others build on. | | StatusDot / StatusBadge | Run-status indicators. |

Model

The presented state is plain data (src/types.ts), derived from @hanzo/ai's wire types:

• AgentRunState — { turns, tasks?, running }
• AgentTurn — a user or assistant turn: text, reasoning, tools, files, error, status
• ToolInvocation — { id, name, arguments, result?, status }
• FileChange — { path, kind, diff?, contents?, language?, additions?, deletions? }
• Task — { id, title, status }

toolInvocationFromCall(toolCall) maps an @hanzo/ai ToolCall to a pending ToolInvocation.

Note on @hanzo/chat

This package does not depend on @hanzo/chat: that published package is the commerce/checkout surface (@hanzo/card / @hanzo/platform / @hanzo/workbench), not a conversation list. The transcript here is built directly on @hanzo/gui.

Develop

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest
npm run build       # tsup -> dist (ESM + CJS + d.ts)

License

BSD-3-Clause © Hanzo AI, Inc.