pocket-server: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

Pocket Server is a Node.js + Hono WebSocket server that provides AI agent capabilities, file system operations, terminal management, and background agent orchestration. Built with TypeScript and ESM modules, it serves as the backend for the Pocket Agent mobile app.

Architecture

Core Design Principles

• Event-driven mailbox pattern - Each session has its own AgentRunner with strict ordering
• Server-authoritative storage - All conversation data persisted to data/sessions/
• Streaming-first - Optimized for real-time WebSocket streaming with frame aggregation
• Module isolation - Clean separation between agent, auth, file system, and terminal modules

Module Structure

src/
├── agent/                       # AI agent orchestration
│   ├── anthropic/              # Anthropic Claude implementation
│   │   ├── anthropic.ts        # Main agent logic and streaming
│   │   ├── prompt.ts           # System prompts and context
│   │   ├── streaming.ts        # Stream event processing
│   │   ├── title.ts            # Title generation
│   │   ├── tools/              # Tool implementations
│   │   │   ├── bash.ts         # Terminal command execution
│   │   │   ├── editor.ts       # File editing operations
│   │   │   └── web-search.ts   # Web search capability
│   │   └── types.ts            # Anthropic API types
│   ├── store/                  # Session persistence
│   │   └── session-store-fs.ts # File-based session storage
│   └── index.ts                # Agent module registration
│
├── auth/                       # Authentication & authorization
│   ├── device-registry.ts     # Device management
│   ├── middleware.ts           # Auth verification middleware
│   ├── pairing.ts             # Local PIN pairing window
│   ├── routes.ts              # Auth HTTP endpoints
│   └── token.ts               # Token generation/validation
│
├── background-agent/           # Cloud agent integrations
│   └── cursor/                # Cursor IDE integration
│       ├── client.ts          # Cursor API client
│       ├── github.ts          # GitHub integration
│       ├── routes.ts          # Cursor HTTP endpoints
│       ├── tracker.ts         # Agent status tracking
│       └── types.ts           # Cursor-specific types
│
├── file-system/               # File operations
│   ├── handlers.ts           # WebSocket handlers
│   ├── service.ts            # Core file operations
│   ├── telescope-search.ts   # Fast file search
│   ├── terminal.ts           # Terminal command execution
│   └── types.ts              # File system types
│
├── notifications/             # Push notifications
│   └── index.ts              # Expo push integration
│
├── server/                    # Core server infrastructure
│   ├── router.ts             # Custom Hono router adapter
│   └── websocket.ts          # WebSocket management
│
├── shared/                    # Shared utilities
│   ├── logger.ts             # Structured logging
│   ├── paths.ts              # Path resolution utilities
│   ├── public-url.ts         # Public URL management
│   └── types/
│       └── api.ts            # Shared API types
│
├── terminal/                  # Terminal management
│   └── terminal-manager.ts   # PTY session management
│
├── tunnel/                    # Remote access
│   └── cloudflare.ts         # Cloudflare quick tunnel
│
├── cli.ts                     # CLI entry point
└── index.ts                   # Server entry point