H3Code

H3Code is a local desktop workbench for coding agents. Today it is an Electron and SvelteKit desktop UI that talks to a local runtime server over WebSocket. PI Agent is the current working provider; the runtime server gives the UI one H3Code-owned protocol that can grow to support multiple providers.

PI remains the current working provider and the source of truth for sessions, messages, tool execution, model behavior, queueing, compaction, and retry. H3Code owns the local experience around that runtime: repo selection, process lifecycle, connection diagnostics, UI state, rendering, metadata indexing, and preferences.

The web and marketing app are preserved in apps/web.

Start with:

• docs/h3code-agent-server-product.md — product direction for the local runtime server architecture.
• docs/agent-server-architecture.html.html — visual/reference architecture proposal.
• docs/h3code-desktop-mvp.md — current PI desktop MVP boundary.

Current State vs Direction

Current desktop path:

Svelte renderer
  -> RuntimeClient (WebSocket)
    -> @h3code/agent-runtime-server (localhost)
      -> AgentRuntime
        -> PiProviderAdapter (@h3code/agent-provider-pi)

Provider direction:

Svelte renderer
  -> local runtime server WebSocket
    -> ProviderAdapter interface
      -> PiProviderAdapter / CodexProviderAdapter / CursorProviderAdapter
        -> actual provider runtime

The runtime packages now exist:

• @h3code/agent-protocol defines provider-neutral protocol, commands, runtime events, read models, workspace summaries, and provider contracts.
• @h3code/agent-runtime owns provider registration, runtime bindings, event ingestion, and read-model projection.
• @h3code/agent-runtime-ws provides the WebSocket transport.
• @h3code/agent-runtime-persistence stores projected runtime state and bindings for cold start.
• @h3code/agent-runtime-server composes the local server, runtime, persistence, metadata registry, WebSocket transport, and PI adapter.
• @h3code/agent-provider-pi implements the current PI provider adapter with the in-process PI SDK.
• @h3code/agent-metadata stores recent repos, indexed session metadata, desktop settings, and related local metadata.

Electron main now supervises the local server and native shell affordances. The legacy PI IPC path has been removed.

Product Boundary

Providers own:

• Sessions and canonical message history.
• Agent runtime behavior, tools, models, queueing, compaction, and retry.
• Provider-native IDs, files, authentication, and execution details.

H3Code owns:

• Desktop and future local-client UI.
• Local Agent Server orchestration.
• Provider selection and capability-gated UI.
• Repo/workspace context, git diff, worktree inventory, and metadata indexing.
• Minimal local preferences.

H3Code should not persist transcripts or become the source of truth for provider-owned sessions.

Current Desktop Status

The desktop app currently implements the core PI provider loop through the runtime server:

• Select a local repo with the native directory picker.
• Start the local runtime server and connect the renderer over WebSocket.
• Create an in-process PI SDK provider session for the selected repo.
• List PI sessions for repos.
• Switch sessions and create new PI-owned sessions.
• Load H3Code session read models, messages, and session stats.
• Send prompts, steer, and follow-up messages through the H3Code WebSocket protocol.
• Abort active runs.
• Render transcript messages, streaming assistant output, tool blocks, runtime diagnostics, extension UI, and recent tool activity.

Still planned:

• Harden the local WebSocket boundary with startup auth and fuller payload validation.
• Keep renderer code on server-projected SessionReadModel shapes.
• Add Codex Server and Cursor providers behind the same H3Code protocol.

Repository Shape

apps/
  desktop/       # Electron + SvelteKit desktop app
  web/           # SvelteKit marketing site
packages/
  agent-protocol/            # H3Code protocol, runtime events, read models, provider contracts
  agent-runtime/             # Runtime bindings, event ingestion, read-model projection
  agent-runtime-ws/          # WebSocket transport
  agent-runtime-persistence/ # SQLite runtime read-model persistence
  agent-runtime-server/      # Local server composition for desktop
  agent-provider-pi/         # In-process PI SDK provider adapter
  agent-metadata/            # Local metadata and desktop preferences
docs/
  h3code-agent-server-product.md
  agent-server-architecture.html.html
  h3code-desktop-mvp.md
  SvelteKitAiElements.md
  SvelteKitShadcn.md

Stack

• Electron
• SvelteKit
• TypeScript
• Tailwind CSS
• shadcn-svelte / Bits UI
• Node.js + ws for the local runtime server
• In-process PI SDK provider for the current provider path
• SQLite metadata index and desktop settings (@h3code/agent-metadata)

Local Development

Install dependencies:

npm install

Run all workspace dev tasks:

npm run dev

Run the desktop app:

npm run dev:desktop

Run the web app:

npm run dev:web

Run checks:

npm run check
npm run lint
npm run build

Package-specific checks:

npm run check --workspace @h3code/agent-protocol
npm run test --workspace @h3code/agent-runtime
npm run test --workspace @h3code/agent-runtime-server