nyaterm/CLAUDE.md

CLAUDE.md

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

Development commands

Root app

• pnpm install — install JS dependencies
• pnpm dev — run the Vite frontend only
• pnpm tauri dev — run the full desktop app in Tauri dev mode
• pnpm build — run tsc and build the frontend with Vite
• pnpm tauri build — build the production desktop bundle
• pnpm lint — run Biome checks for src/**/*.ts and src/**/*.tsx
• pnpm format — apply Biome formatting to src/**/*.ts and src/**/*.tsx
• pnpm format:check — check Biome formatting without writing changes
• pnpm i18n:check — check locale JSON formatting
• pnpm i18n:fix — rewrite locale JSON formatting
• pnpm version-sync — sync version numbers across app files
• pnpm release — version sync + frontend build + Tauri build

Rust / Tauri backend

• cargo fmt --manifest-path src-tauri/Cargo.toml — format Rust code
• cargo clippy --manifest-path src-tauri/Cargo.toml --all-targets — lint Rust code
• cargo test --manifest-path src-tauri/Cargo.toml — run backend Rust tests
• cargo test --manifest-path src-tauri/Cargo.toml <test_name> — run a single backend Rust test
• cargo test --manifest-path src-tauri/crates/otp/Cargo.toml — run OTP crate tests
• cargo test --manifest-path src-tauri/crates/otp/Cargo.toml <test_name> — run a single OTP crate test

Example single-test command:

• cargo test --manifest-path src-tauri/Cargo.toml normalizes_trailing_slashes_without_breaking_roots

Docs site

• pnpm --dir docs-site start — build and serve the docs site locally for all locales (/ and /en/)
• pnpm --dir docs-site start:zh — run the zh-CN docs dev server with hot reload
• pnpm --dir docs-site start:en — run the English docs dev server with hot reload
• pnpm --dir docs-site start:ko — run the Korean docs dev server with hot reload
• pnpm --dir docs-site build — build the docs site

Big-picture architecture

• This is a Tauri 2 desktop app: React/TypeScript frontend in src/, Rust backend in src-tauri/src/, and IPC between them via Tauri commands/events.
• The frontend should call Rust through the typed wrapper in src/lib/invoke.ts, not raw scattered invoke() calls where a shared wrapper already exists.
• Tauri commands are registered centrally in src-tauri/src/lib.rs and grouped by concern under src-tauri/src/cmd/ (session, sftp, connection, credential, settings, watcher, translate, stats, tunnel, proxy, otp, importer, plus app, backup, clipboard, cloud_sync, log, and ai).

Window model

• src/main.tsx decides between two boot paths:
  • main window: AppProvider + App.tsx
  • child windows: ChildAppProvider + ChildWindowRouter
• Child windows are opened from src/lib/windowManager.ts using ?window= query params. Current child-window flows include settings, new-session, quick-command, and per-file auto-upload dialogs.
• Modal child-window focus/enable state is managed in windowManager.ts plus src/ChildWindowRouter.tsx; changes here affect cross-window UX.

Frontend state model

• src/context/AppContext.tsx is the main state container. It owns:
  • tab/session workspace state
  • persisted UI/app settings
  • saved connections/groups loading and refresh
  • startup session restoration from persisted ui.open_tabs
• src/context/ChildAppProvider.tsx is a lightweight provider for child windows. It only loads/saves settings and emits cross-window events; it does not manage the full tab/session workspace.
• src/context/TransferContext.tsx separately tracks file transfer progress from backend transfer-event notifications.

Workspace / terminal model

• The terminal workspace has two distinct layers that are easy to confuse:
  • src/lib/workspaceTabs.ts manages the persistent logical tab model. Each tab owns a recursive pane tree (leaf session panes and split panes). This is what gets serialized into ui.open_tabs for startup restore.
  • src/lib/tabWindows.ts manages the runtime terminal window layout: which tabs live in each split window leaf, active tab per leaf, and window split ratios for the multi-tab/multi-split UI.
• src/App.tsx is the shell that composes activity bars, left/right panels, the terminal workspace, quick command / serial send bottom panels, OTP dialogs, transfer UI, recording, and lock screen.
• src/components/terminal/XTerminal.tsx is the xterm.js integration point. It wires Fit/Search/WebLinks addons, shell integration, command suggestions, reconnect hooks, and listens to per-session backend events.

Backend runtime model

• src-tauri/src/lib.rs constructs and stores the shared backend managers in Tauri state:
  • SessionManager
  • TunnelManager
  • RecordingManager
  • PendingAuthManager
  • HostKeyVerifyManager
  • QuickCommandsStore
  • CloudSyncManager
  • AgentApprovalManager (gates AI agent command execution)
• Tauri commands are registered centrally in src-tauri/src/lib.rs; newer backend capability areas now include app, backup, clipboard, cloud sync, logging, and AI in addition to sessions/SFTP/settings/importers.
• src-tauri/src/core/session.rs contains SessionManager, which is the central registry for active sessions, command routing, command history, fuzzy history search, and session lifecycle events.
• Session implementations live under src-tauri/src/core/:
  • ssh/ for SSH transport, auth, OSC/CWD tracking, tunnels, and SFTP
  • pty.rs for local terminal sessions
  • telnet.rs for Telnet sessions
  • serial.rs for serial sessions
  • recording.rs for terminal recording
  • watcher.rs for file-watch driven flows
  • importer.rs for Xshell / MobaXterm / WindTerm import
  • cloud_sync.rs for sync/backup runtime and conflict events
  • portable_snapshot.rs for defining what sync/backup payloads include
  • ai/ for provider calls, streaming responses, structured command cards, agent execution/approval, prompt redaction, and audit/history storage
• Backend session I/O is event-driven. The Rust side emits session-specific and app-wide events such as terminal-output-{id}, cwd-changed-{id}, session-closed-{id}, sessions-changed, connections-changed, command-history-changed, transfer-event, otp-request, cloud-sync-status-changed, cloud-sync-history-changed, and cloud-sync-conflict.

SSH / auth / transfer details

• SSH logic is split across src-tauri/src/core/ssh/:
  • client.rs handles russh client setup, keepalive config, proxy-aware connection setup, and TOFU-style known_hosts verification (host-key prompts are coordinated through HostKeyVerifyManager)
  • auth.rs handles saved auth loading plus keyboard-interactive / OTP flows through PendingAuthManager and the otp-request event
  • io.rs streams terminal output and emits CWD updates
  • sftp.rs implements remote file operations and emits transfer progress events consumed by TransferContext
  • tunnel.rs manages local / remote / dynamic SSH tunnel behavior
• SFTP commands exposed to the frontend are in src-tauri/src/cmd/sftp.rs; the file explorer and transfer UI sit on top of these commands and events.
• File watcher / auto-upload flows bridge backend and child windows: remote files are downloaded locally, watched by src-tauri/src/core/watcher.rs, then uploaded back through the auto-upload UI flow.

Persistence model

• App data lives under ~/.nyaterm/, but the primary store is now ~/.nyaterm/nyaterm.redb rather than a set of standalone JSON files.
• Important redb JSON documents include settings, sessions, keys, passwords, otp, quick-command, tunnels, proxies, history, cloud-sync, cloud-sync-state, ai-history, and ai-audit.
• Important text documents stored through the same layer include known_hosts and master.key.
• Sensitive values are encrypted before being written; cloud-sync credentials and other secret-bearing config need to stay within the existing crypto/storage helpers.
• When changing settings or workspace persistence, update both the frontend defaults (AppContext / ChildAppProvider) and the Rust persistence/migration code (src-tauri/src/config/settings/mod.rs, src-tauri/src/config/ui.rs, and related src-tauri/src/storage.rs / cloud-sync snapshot code when applicable).
• The app also contains legacy Dragonfly migration paths; if you change persistence formats, check that import/migration behavior still makes sense for ~/.dragonfly/ data.

Project-specific guidance

• If a task touches UI, prefer shadcn/ui patterns and components. The repo has an explicit Cursor rule for this in .cursor/rules/ui.mdc.
• shadcn is configured in components.json, and shared UI components live in src/components/ui/.
• When changing user-facing UI text, update both locale files:
  • src/i18n/locales/en.json
  • src/i18n/locales/zh-CN.json
  • src/i18n/locales/zh-TW.json
  • src/i18n/locales/ko.json
• The root app currently has no dedicated frontend unit test runner configured in package.json; the automated tests in this repo are Rust tests under src-tauri/ and src-tauri/crates/otp/.
• Frontend linting includes a no-console check before Biome (pnpm lint runs scripts/check-no-console.mjs and biome check src/).
• Vite uses the @ alias for src/.
• Tauri dev/build behavior is configured in src-tauri/tauri.conf.json; the dev server runs on port 1420 with HMR on 1421.
• There is a separate Docusaurus docs app in docs-site/. The most useful repo docs for implementation context are in docs-site/docs/development/ (architecture.md, frontend.md, backend.md, setup.md, contributing.md).
• Repo docs and recent history use Conventional Commits (feat:, fix:, perf:, chore:).