winkterm: Instructions file for Codex

AGENTS.md

This file provides guidance to Codex (Codex.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

Automated Test Suite

# From the repository root, run the stable full local suite:
.\scripts\test-all.ps1

# Optional flags:
.\scripts\test-all.ps1 -SkipFrontendE2E
.\scripts\test-all.ps1 -SkipCodexSmoke
.\scripts\test-all.ps1 -RunVnc

scripts/test-all.ps1 runs backend pytest, frontend lint/build/typecheck, starts a temporary backend, verifies the agent terminal API, runs Codex chat and tool-call WebSocket smoke tests, starts the frontend, then runs the Puppeteer settings E2E. The script stops the backend/frontend processes it starts. VNC smoke is skipped by default because it requires a configured SSH/VNC target; use -RunVnc only when that target is available.

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

When frontend/package.json or frontend dependencies change, always commit the matching frontend/package-lock.json. Before pushing, verify the Docker install path with the same npm major used by the Docker image:

cd frontend
npx [email protected] ci --omit=optional --ignore-scripts