CodeNomad Documentation

The Messages Area displays the conversation between the User and the Assistant.

Message Types

• User Messages: Displays your text and any attached files (e.g., [@src/app.ts]).
• Assistant Messages: Displays the AI's response, including tool calls and code blocks.

Tool Calls

When the assistant uses a tool (like running a bash command or editing a file), it appears as a tool call:

• Collapsed View: Shows the tool name, a summary, and a status icon (e.g., ▶ bash: npm install vitest ✓).
• Expanded View: Click the tool call to see the specific Input sent to the tool and the resulting Output.
• File Changes: For edit tools, the UI displays the modified file path and a summary of changes (e.g., +12 lines, -3 lines). You can click to expand and view the diff inline.

Status Icons

• ⏳ Pending: Spinner indicating an action is in progress.
• ✓ Success: Green checkmark.
• ✗ Error: Red X.
• ⚠ Warning: Yellow triangle.

Navigation

• Auto-scroll: The view automatically scrolls to the bottom when new messages arrive.
• Manual Scroll: Scrolling up manually disables auto-scroll. A "Scroll to bottom" button will appear to return to the latest message.

Optimization should only occur during Phase 8 or when triggered by specific real-world indicators.

Post-MVP Triggers

Transition to optimization when you encounter:

1. User Feedback: Multiple users report slowness or abandon the app due to performance.
2. Measurable Issues: The app freezes for >2 seconds, memory usage causes crashes, or the UI becomes unresponsive.
3. Phase 8 Milestone: The MVP is complete, validated, and a user base is established.

Optimization Workflow

1. Measure First: Profile actual bottlenecks using real user data rather than assumptions.
2. Target Fixes: Fix specific bottlenecks without over-engineering.
3. Iterate: Optimize one thing at a time and verify improvements with users.

Acceptable MVP Performance

It is acceptable for the MVP if:

• 100 messages render in 1 second.
• The UI is slightly laggy during heavy streaming.
• Memory usage grows with message count.
• Multiple instances slow down the app.

CodeNomad manages state through a hierarchy of Instances, Sessions, and Messages.

Instance State

An instance represents a single OpenCode server process. Key fields include:

• id: Unique identifier.
• folder: The local directory path.
• port: The assigned port.
• proxyPath: The base URL for API/SSE calls (e.g., /workspaces/:id/instance).
• status: Current state ('starting' | 'ready' | 'error' | 'stopped').
• client: The OpenCodeClient instance.
• eventSource: The EventSource for SSE.
• sessions: A map of sessionId to Session objects.

Session State

A session is a single conversation within an instance:

• id: Unique identifier.
• parentId: If this is a child session, the ID of the parent.
• messages: An array of Message objects.
• agent: The active agent name.
• model: Contains providerId and modelId.
• status: Current state ('idle' | 'streaming' | 'error').

Message State

Individual messages within a session:

• type: 'user' | 'assistant'.
• parts: The content parts of the message.
• status: 'sending' | 'sent' | 'streaming' | 'complete' | 'error'.

CodeNomad uses Server-Sent Events (SSE) to stream messages and session updates from the OpenCode server to the UI.

Communication Flow:

1. An EventSource connects to the /event endpoint of the instance.
2. Incoming JSON events are routed to the correct instance store.
3. Reactive state (via SolidJS signals) is updated, triggering UI re-renders.

Reconnection Logic: To handle network issues or server restarts, the SSEConnection implements exponential backoff:

• maxReconnectAttempts: 5
• reconnectDelay: Starts at 1000ms and doubles with each attempt.

Key Methods:

• connect(instanceId: string, port: number): Establishes the connection.
• disconnect(instanceId: string): Closes the connection.
• onMessageUpdate(handler): Subscribes to message changes.
• onSessionUpdate(handler): Subscribes to session changes.

class SSEConnection {
  private reconnectAttempts = 0
  private maxReconnectAttempts = 5
  private reconnectDelay = 1000 // Start with 1s

  reconnect() {
    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
      this.emitError(new Error("Max reconnection attempts reached"))
      return
    }

    setTimeout(() => {
      this.connect()
      this.reconnectAttempts++
      this.reconnectDelay *= 2 // Exponential backoff
    }, this.reconnectDelay)
  }
}

Sessions are child entities of an instance, representing specific AI interactions. A session tracks the agent, the model (provider and model ID), and versioning.

Session Statuses:

• idle: No activity.
• streaming: Assistant is currently responding.
• error: An error occurred during the session.

Key Actions:

• createSession(instanceId: string, agent: string): Starts a new session.
• deleteSession(instanceId: string, sessionId: string): Removes a session.
• setActiveSession(instanceId: string, sessionId: string): Switches the active session.
• updateSession(instanceId: string, sessionId: string, updates: Partial<Session>): Updates session metadata.

interface SessionState {
  // Per instance
  getSessions(instanceId: string): Session[]
  getActiveSession(instanceId: string): Session | null

  // Actions
  createSession(instanceId: string, agent: string): Promise<Session>
  deleteSession(instanceId: string, sessionId: string): Promise<void>
  setActiveSession(instanceId: string, sessionId: string): void
  updateSession(instanceId: string, sessionId: string, updates: Partial<Session>): void
}