Server API

This page documents Claude Yard’s internal API for contributors building custom modules or integrations.

Architecture

Three layers:

1. Server (server/index.ts) — routes requests to modules
2. Modules (server/modules/) — each handles a domain (terminals, state, sync, voice)
3. Core Ops (server/core/) — standalone process management, no UI awareness

HTTP endpoints

State & configuration

Method	Path	Description
GET	/api/state	Current app state (panels, layout, sessions)
GET	/api/settings	App settings
POST	/api/settings	Update settings
GET	/cwd	Server working directory
GET	/sessions	All Claude sessions from disk

Process management

Method	Path	Description
GET	/api/panels	List open terminal panels
POST	/api/spawn	Spawn a new terminal (shell or Claude)
POST	/api/panels/:id/send	Send keystrokes to a panel
POST	/api/panels/:id/close	Close a panel
POST	/api/panels/:id/interrupt	Send SIGINT to a panel

Layout & browser

Method	Path	Description
GET	/api/layout	Current panel layout
POST	/api/layout	Set panel layout
POST	/api/browser/open	Open a browser panel

Tools

Method	Path	Description
GET	/api/mcp/tools	List all available MCP tools
POST	/api/tools/call	Call any tool by name

Unread tracking

Method	Path	Description
GET	/api/seen	Seen map (sessionId → timestamp) for unread tracking
POST	/api/seen	Mark a session as seen ({ sessionId })

Observer

Method	Path	Description
POST	/api/observer/send	Send a suggestion to a session
POST	/api/observer/dismiss	Dismiss the current suggestion
POST	/api/observer/autopilot	Toggle autopilot mode
GET	/api/observer/notebook	Get observer notebook for a session

WebSocket protocol

The terminal WebSocket connects at ws://localhost:{port}/ws/terminal.

Client → Server

Spawn a terminal:

{
  "type": "spawn",
  "id": "panel-1",
  "cols": 120,
  "rows": 40,
  "cwd": "/path/to/project",
  "autoCommand": "claude"
}

Send input:

{ "type": "input", "data": "hello world\r" }

Resize terminal:

{ "type": "resize", "cols": 160, "rows": 50 }

Server → Client

Terminal output:

{ "type": "output", "data": "...raw terminal data..." }

Metadata signal (parsed from escape sequences):

{ "type": "meta", "signal": "title", "value": "⠋ Working..." }

Session ID (after spawning a Claude session):

{ "type": "meta", "signal": "sessionId", "id": "abc123-def456-..." }

Process exit:

{ "type": "exit", "exitCode": 0 }

Spawn confirmation:

{ "type": "spawned", "id": "panel-1", "pid": 12345 }

Control WebSocket

The control WebSocket at ws://localhost:{port}/control-ws broadcasts layout changes and observer state to all connected clients.

Notebook update (observer state for a session):

{
  "type": "notebook_update",
  "panelId": "panel-1",
  "notebook": {
    "goal": "Refactoring auth module",
    "notes": ["Extracted middleware", "Updated tests"],
    "status": "active",
    "suggestion": null,
    "updatedAt": 1712600000000
  }
}

Module system

Each module implements the Module interface:

interface Module {
  name: string;
  getHttpRoutes(): HttpRoute[];
  getWsRoutes?(): WsRoute[];
  getMcpTools?(): McpTool[];
  handleToolCall?(name: string, args: any): Promise<McpToolResult>;
}

Modules register in order: core → app → sync → observer → voice.

The registry (server/modules/registry.ts) provides:

• callTool(name, args) — dispatches to the right module
• getMcpTools() — aggregates tools from all modules
• getWsRoutes() — aggregates WebSocket routes

Key files

File	Purpose
server/index.ts	Server orchestrator
server/core/core-ops.ts	PTY lifecycle, spawn(), send()
server/core/signal-parser.ts	Terminal escape sequence parser
server/modules/registry.ts	Module registry with callTool()
server/modules/core/core-module.ts	Terminal HTTP routes + WS handler
server/modules/app/app-module.ts	State, layout, browser, MCP discovery
server/modules/observer/observer-module.ts	Observer module wrapper
server/agents/lifecycle.ts	SessionLifecycle coordinator
server/agents/observer/observer.ts	Per-session observer FSM
server/seen.ts	Unread tracking (seen map)
mcp-server.mjs	MCP protocol proxy
cli.mjs	CLI tool