imcodes: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Build & typecheck
npm run build                              # daemon (src/ → dist/)
npx tsc --noEmit                           # daemon typecheck only
npx tsc -p server/tsconfig.json --noEmit   # server (stricter: noUnusedLocals, noImplicitReturns)

# Tests (vitest workspace)
npm test                               # all projects
npm run test:unit                      # daemon only (src/**/*.test.ts, test/**/*.test.ts, excludes e2e)
npm run test:server                    # server only (server/test/**/*.test.ts)
npm run test:web                       # web only (web/test/**/*.test.ts, jsdom environment)
npm run test:e2e                       # e2e only (test/e2e/**/*.test.ts, 30s timeout, requires tmux)
npx vitest run path/to/file.test.ts    # single file

# Server (self-hosted backend)
cd server && npm run dev               # run server via tsx
cd server && npm run migrate           # apply PostgreSQL migrations

# Dev
npm run dev                            # run daemon via tsx

Architecture

IM.codes is a specialized instant messenger for AI coding agents — a three-tier system for remote terminal access, file browsing, multi-agent workflows, and session management:

You (browser / mobile app)
        ↓ WebSocket
Server (Node.js + Hono + PostgreSQL, self-hosted in server/)
        ↓ WebSocket
Daemon (Node.js CLI on user's machine, src/)
        ↓ tmux / ConPTY / transport
AI Agents (Claude Code / Codex / Gemini CLI / OpenClaw / Shell)
        ↔ imcodes send (agent-to-agent)

Daemon (src/)

Node.js process that manages AI agent sessions via tmux. Entry point: src/index.ts (commander CLI).

• Agent layer (src/agent/): Two runtime backends — process agents run in tmux/ConPTY sessions, transport agents stream via network protocols.
  • Process drivers (src/agent/drivers/): claude-code.ts, codex.ts, gemini.ts, opencode.ts, shell.ts — each implements AgentDriver (build launch/resume commands, detect status via terminal patterns, capture output). tmux.ts wraps tmux (Linux/macOS), conpty.ts provides ConPTY (Windows).
  • Transport providers (src/agent/providers/): qwen.ts (Qwen, LOCAL_SDK — spawns CLI process with stream-json output), openclaw.ts (OpenClaw, PERSISTENT — WebSocket to gateway). Each implements TransportProvider — connect(), send(), onDelta(), onComplete(). Streaming is event-driven (no terminal scraping).
  • Agent types: ProcessAgent = 'claude-code' | 'codex' | 'gemini' | 'opencode' | 'shell' | 'script', TransportAgent = 'openclaw' | 'qwen'. Defined in src/agent/detect.ts.
  • session-manager.ts manages all sessions, auto-restart with loop prevention. provider-registry.ts manages transport provider lifecycle.
• Transport relay (src/daemon/transport-relay.ts): Converts transport provider callbacks (onDelta, onComplete, onError) to unified timeline events (assistant.text, session.state, tool.call).
• Routing (src/router/): message-router.ts routes inbound messages to the correct session. command-parser.ts handles /bind, /status, /send, etc.
• Server link (src/daemon/server-link.ts): WebSocket client connecting to the server at /api/server/:id/ws. Sends { type: 'auth', serverId, token } on open. Credentials stored in ~/.imcodes/server.json after imcodes bind.
• Session store (src/store/session-store.ts, SQLite layer in session-store-db.ts): SQLite (WAL) at ~/.imcodes/sessions.sqlite, one row per session, debounced incremental writes in one transaction. The pre-SQLite sessions.json is imported once on first start and frozen as sessions.json.migrated-to-sqlite; nothing reads it afterwards. Online snapshots: sessions.sqlite.bak.1-3.