Project Center

Goal

Improve the Cursor remote development workflow.

Current workflow

GitHub repository -> SSH to server -> clone repository -> Editor (Cursor/VSCode) connects to server -> open folder

Target workflow

Unified lightweight entry point -> automatically record project after SSH clone -> one-click open in Editor (Cursor/VSCode)

Immediate focus

First, solve the problem of Cursor or VSCode opening an unfamiliar window.

Architecture Decision

Web UI + Python Backend

Because embedding a terminal and rendering ANSI sequences is complex, the terminal UI is handled in the browser.

• Frontend: HTML, CSS, and JavaScript. Use xterm.js to provide a native-like terminal experience with full ANSI support; native use of vim, tmux, and similar full-screen TUIs in the embedded terminal is an explicit product goal (see docs/todo.md). Handle layout such as drawers, dropdowns, and scrolling lists with standard web technologies.
• Backend: Python (for example FastAPI, Eel, or PyWebView). Keep the core logic here, including asyncssh for connections and history.py for state management.
• Communication: Use WebSocket for real-time terminal I/O streaming and REST APIs for local OS actions such as launching VPN or opening the workspace in an Editor.
• Decision: This architecture fully replaces the previous tkinter-based UI approach.

Branding and Windows shell

• The app uses a colored folder-root style icon for the window/taskbar where the platform supports it.
• The web UI references favicon and web app manifest assets so in-window branding matches the desktop icon.
• A Start Menu shortcut can be installed for Project Center (alongside the executable) for quick launch.

Working Principles

Always build the Minimum Viable Product (MVP) first.

When instructions conflict, follow this priority order. Higher-priority items always override lower-priority ones:

1. User instructions
2. TODO list in docs/todo.md
3. UI logic in docs/ui-logic.md

Issues and documentation

Known problems and product gaps that are not yet scheduled for work are documented in docs/issues.md by issue number: each section has a short description and, where needed, discussion notes, conclusions, and open points. Execution priority is still: user instructions > docs/todo.md > docs/ui-logic.md.

How the docs work together

Document	Role	Relationship to issues
README.md	Project goals, architecture, working principles, doc priority	This subsection defines the workflow; this file points to issues.
docs/todo.md	Queued, actionable tasks	When an item is promoted from issues, it should be added or linked in todo.md (short pointer to the matching issues section) so the same requirement is not duplicated at length in two places.
docs/ui-logic.md	Implemented Web UI and backend behavior	Issues describe gaps or future capability; after a design is decided and shipped, update ui-logic.md to match.
docs/ui-design.md	Visual and component rules	For UX issues, follow ui-design.md; add to it when new patterns are introduced.
docs/issues.md	Known problems, gaps, and per-issue discussion	Numbered ## sections; short summary plus longer notes when needed.

Workflow: capture problems in issues → when ready to build, add concrete tasks to docs/todo.md (or “see issues item N”) → after merge, update ui-logic.md (and ui-design.md if needed) → mark the issues section resolved or update its text, and fold discussion into the same section (or remove obsolete bullets).

Discussion policy

When the user asks to discuss an issue (optionally by number in docs/issues.md), the agent writes the discussion into the matching ## N. section in docs/issues.md (add sub-paragraphs, lists, or dated notes)—not only in chat.

• How it works: the user may go back and forth in chat, or add follow-up notes by editing docs/issues.md later. When the user says discuss or continues a thread tied to an issue, merge final phrasing and deltas into that section; if it does not exist yet, add ## N. … and keep numbering consistent with existing sections in docs/issues.md.
• What to archive (the discussion is incomplete if any of these is missing):
  1. Questions: what was being clarified or decided (bullets are fine).
  2. Answers: agreed conclusions, preferences, or an explicit won’t do for now (distinct from “no conclusion yet”).
  3. Open points: disagreements, deferred options, or known risks, and what happens next (e.g. move work to docs/todo.md, revisit later, or record only).

Hand-off to the workflow above: when discussion turns into implementation, add or link the work in docs/todo.md; if behavior changes relative to the shipped product, update docs/ui-logic.md (and ui-design.md if needed) after the change lands.

If the user's instruction or todo list ask for any new feature or change, always update the corresponding file.

If the user's instruction is only the single word Do, follow the task list in docs/todo.md.

Always follow the UI design rules in docs/ui-design.md.