How yyzybb537/remote_claude works
Purpose and execution surface
Remote Claude bridges locally running Claude Code or Codex CLI sessions to Feishu/Lark, while retaining terminal-based interaction through tmux. User-facing launchers are cla, cl, cx, and cdx; the management CLI supports session lifecycle and attach operations. Primary entry points: remote_claude.py, bin/remote-claude, bin/cla.
Session and terminal orchestration
The core host-side control plane creates, lists, attaches to, and kills named tmux-backed AI CLI sessions. It supports multiple terminal and Lark clients sharing one process without embedding into Claude/Codex itself. Session identity, attachment coordination, and protocol-level state live in utils/session.py, utils/protocol.py, and server/shared_state.py.
Local server: PTY stream to structured UI
The server receives terminal output/input around managed sessions, parses CLI-specific terminal regions, and exposes structured components suitable for remote rendering and interaction. server/server.py coordinates the service; server/component_parser.py selects parsers, with CLI-specific behavior in server/parsers/claude_parser.py and server/parsers/codex_parser.py. This is the key boundary between opaque ANSI terminal streams and application-level output, option, and approval controls.
Lark client and bidirectional bridge
The Lark process connects to Feishu as a bot client, manages conversation/session selection, and relays user messages or card actions back to the active terminal session. lark_client/main.py is its process entry point; lark_client/lark_handler.py handles inbound Lark events; lark_client/session_bridge.py connects those events to local session state. lark_client/shared_memory_poller.py streams local updates to the client.
Output rendering and interactive cards
Terminal data is buffered, cleaned, ANSI-rendered, and transformed into Feishu rich-text/cards, including streamed output and clickable choices or permission confirmations. The rendering pipeline is represented by lark_client/terminal_buffer.py, lark_client/output_cleaner.py, and lark_client/terminal_renderer.py; card construction/update behavior is in lark_client/card_builder.py and lark_client/card_service.py. Server-side rich text conversion is in server/rich_text_renderer.py.
State, concurrency, and transport boundaries
Shared state separates session/process control from Lark presentation, allowing terminal and remote clients to attach concurrently. The local service communicates through project protocol/session abstractions rather than directly modifying the managed Claude/Codex process. Important boundaries are utils/protocol.py, utils/components.py, and server/shared_state.py; terminal capture is isolated in lark_client/capture_output.py.
Runtime and external dependencies
The system targets macOS/Linux and relies materially on tmux, uv/Python, and installed Claude CLI or Codex CLI. Feishu/Lark is optional but requires an enterprise self-built application, credentials, event callbacks, and app publication. Environment/configuration and bot setup are managed by lark_client/config.py and lark_client/setup_wizard.py; install/bootstrap behavior begins at init.sh.
Packaging and operational modes
The project is distributed through npm while its application runtime is primarily Python, reflected by package.json, pyproject.toml, and requirements.txt. Docker support is oriented toward package/test validation rather than the primary deployment model: docker/Dockerfile.test and docker/docker-compose.test.yml. Lightweight statistics collection/query capabilities are isolated under stats/collector.py and stats/query.py.
Main entry points: component_parser.py Component parser · session.py Session manager · protocol.py Session protocol · shared_state.py Shared state
Components 22
Host Control Plane
Manages named local AI CLI sessions and terminal attachment.
- CLI launchers · User-facing cla, cl, cx, and cdx commands.
bin/cla - Management CLI · Starts and manages remote Claude sessions.
remote_claude.py - Session manager · Creates, lists, attaches to, and kills named sessions.
utils/session.py - Session protocol · Coordinates session identity and protocol state.
utils/protocol.py - tmux sessions · Hosts shareable Claude Code or Codex CLI processes.
- Claude / Codex CLI · Opaque managed terminal applications.
Local Stream Server
Converts PTY terminal streams into structured controls.
- Shared state · Separates process control from remote presentation state.
server/shared_state.py - Local server · Coordinates terminal input, output, and structured UI.
server/server.py - Component parser · Selects CLI-specific terminal parsers.
server/component_parser.py - Claude parser
server/parsers/claude_parser.py - Codex parser
server/parsers/codex_parser.py - Structured components · Represents output, choices, and approval controls.
utils/components.py - Rich text renderer · Converts server-side content for rich presentation.
server/rich_text_renderer.py
Lark Bridge
Relays Feishu events and renders terminal output as cards.
- Lark client · Runs the Feishu bot bridge process.
lark_client/main.py - Lark event handler · Handles inbound messages and card actions.
lark_client/lark_handler.py - Session bridge · Maps Lark interactions to active local sessions.
lark_client/session_bridge.py - Terminal capture · Isolates terminal output capture.
lark_client/capture_output.py - State poller · Streams local session updates to the Lark client.
lark_client/shared_memory_poller.py - Terminal render pipeline · Buffers, cleans, and renders streamed terminal output.
lark_client/terminal_renderer.py - Card service · Builds and updates interactive output cards.
lark_client/card_service.py - Feishu / Lark · Optional remote messaging and interactive-card surface.
- Bot setup · Configures Lark credentials and bot setup.
lark_client/setup_wizard.py
Connections 22
- CLI launchers → Management CLI: launches
- Management CLI → Session manager: manages
- Session manager → Session protocol: coordinates through
- Session manager → tmux sessions: creates and attaches
- tmux sessions → Claude / Codex CLI: hosts
- Session protocol → Shared state: shares state
- Local server → Shared state: reads and updates
- Local server → Component parser: parses terminal stream
- Component parser → Claude parser: Claude mode
- Component parser → Codex parser: Codex mode
- Component parser → Structured components: emits
- Structured components → Rich text renderer: renders
- Lark client → Lark event handler: receives events
- Lark event handler → Session bridge: forwards actions
- Session bridge → Session protocol: sends input
- Terminal capture → State poller: publishes updates
- Shared state → State poller: exposes session state
- State poller → Terminal render pipeline: streams output
- Terminal render pipeline → Card service: produces rendered content
- Card service → Feishu / Lark: updates cards
- Feishu / Lark → Lark event handler: messages and actions
- Bot setup → Feishu / Lark: configures bot