winkterm CLAUDE.md

CLAUDE.md

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

Project Overview

WinkTerm is an AI + terminal "human-machine fusion" ops tool. The AI and the user share the same pty session, and all interaction happens inside the terminal. The user talks to the AI by typing a # message; the AI can suggest commands and write them into the input line, where the user presses Enter to run or Backspace to edit.

Common Commands

Backend Development

cd backend
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# Start the development server
python -m uvicorn backend.main:app --reload --port 8000

Frontend Development

cd frontend
npm install
npm run dev           # Development mode
npm run build         # Build (output to frontend/out/)
npm run lint          # Lint check
npm run gen:api       # Generate TypeScript types and react-query hooks from OpenAPI

Desktop App Packaging

# Windows
build\build.bat

# Or run manually
pyinstaller build\winkterm.spec --clean --noconfirm

Docker Deployment

docker compose up -d

Architecture

Core Data Flow

User keyboard input
    │
    ▼
Frontend Terminal (xterm.js)
    │  WebSocket
    ▼
ws_handler.py
    │
    ├── Normal input ──► pty_manager.write() ──► shell process
    │
    └── Lines starting with # ──► intercept ──► Agent (LangGraph)

Key Modules

Module	Path	Responsibility
WebSocket handling	backend/terminal/ws_handler.py	Message dispatch, # detection, Agent invocation
PTY management	backend/terminal/pty_manager.py	Shell process wrapper, read/write, context retrieval
Session management	backend/terminal/session_manager.py	Multi-terminal sessions, active state
Agent graph	backend/agent/graph.py	LangGraph StateGraph definition
Agent tools	backend/agent/tools/	Terminal interaction tool definitions
SSH connections	backend/ssh/	SSH connection management, file transfer