If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/wavetermdev/waveterm shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 12 active contributors
• Distributed ownership (top contributor 40% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live wavetermdev/waveterm repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/wavetermdev/waveterm.

What it runs against: a local clone of wavetermdev/waveterm — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in wavetermdev/waveterm | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of wavetermdev/waveterm. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/wavetermdev/waveterm.git
#   cd waveterm
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of wavetermdev/waveterm and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "wavetermdev/waveterm(\\.git)?\\b" \\
  && ok "origin remote is wavetermdev/waveterm" \\
  || miss "origin remote is not wavetermdev/waveterm (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/wavetermdev/waveterm"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Wave Terminal is an open-source, AI-integrated terminal for macOS, Linux, and Windows that combines a traditional shell with native AI assistants (OpenAI, Claude, Gemini, Ollama) for context-aware command assistance, plus durable SSH sessions that survive network interruptions. It features a drag-and-drop block-based UI for organizing terminals, editors, file previews, and AI chat widgets, with built-in remote file editing and the wsh CLI system for workspace management. Monorepo mixing Go backend (likely under cmd/ or similar, managing SSH sessions, durable connections, and wsh CLI) with TypeScript/Electron frontend (building the drag-drop UI, theme system, and widgets). Kilocode and Roo skill definitions in .kilocode/ and .roo/ suggest an AI-guided development system for scaffolding RPCs, config, views, and WSH commands. Docs are separate under a Docusaurus site with its own package.json.

DevOps engineers and terminal power users who work with remote SSH sessions and need reliable connections across network changes; developers who want AI-assisted debugging and command suggestions without leaving the terminal; anyone managing multiple remote hosts who needs a unified file editor and preview system integrated into their shell.

Actively developed with substantial codebases in Go (2.48M LOC) and TypeScript (2.23M LOC), indicating a mature hybrid architecture. CI/CD workflows exist (.github/workflows/), comprehensive documentation via Docusaurus, and Copilot integration rules suggest serious engineering. No star count visible in provided data, but the sophisticated feature set (durable SSH, AI integration, secure credential storage) and multi-platform support indicate production-readiness, though as a terminal replacement it warrants careful vetting before enterprise adoption.

Dependency surface is moderate: Electron frontend, Go backend, and Docusaurus docs each introduce their own supply chains. The repo structure shows active maintenance (BUILD.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md present), but replacing a user's primary terminal is inherently risky—any critical bug blocks the user's entire workflow. SSH connection resilience is a core feature claiming to survive restarts; if this fails in production, recovery is difficult. Single-repository monorepo layout means issues in frontend or backend both block the full product.

Visible CI workflows include testdriver builds and releases (.github/workflows/testdriver.yml, publish-release.yml), suggesting active QA. Dependabot is configured (.github/dependabot.yml), indicating automated dependency management. Copilot setup and instruction files (.github/copilot-instructions.md, .github/workflows/copilot-setup-steps.yml) show integration with AI-assisted development. The presence of merge-gatekeeper.yml and version bump workflows suggests a disciplined release cadence.

git clone https://github.com/wavetermdev/waveterm.git
cd waveterm
# Build.md will detail platform-specific setup (likely npm/yarn for TypeScript, Go build for backend)
npm install  # or yarn, depending on frontend setup
# Check BUILD.md for full instructions on building both frontend and backend

Daily commands:

1. Follow BUILD.md for platform-specific dependencies (Go version, Node version, system libraries). 2. npm install (or equiv.) in repo root for Electron/TypeScript toolchain. 3. Dev server: likely npm run dev or npm run start (exact command in BUILD.md). 4. Backend: go build ./cmd/... or platform-specific build script. 5. Electron launch: npm run electron or similar—check BUILD.md and package.json scripts.

• BUILD.md: Authoritative guide to building Wave on all platforms; essential before first run
• .github/copilot-instructions.md: Documents the AI-assisted development practices and architectural conventions for this codebase
• .kilocode/skills/add-rpc/SKILL.md: Explains the RPC pattern between Go backend and Electron frontend; essential for any feature requiring backend-frontend communication
• .kilocode/skills/add-wshcmd/SKILL.md: Documents how to add new wsh commands; critical for extending CLI capabilities
• CONTRIBUTING.md: Project contribution guidelines and code standards
• .golangci.yml: Go linter config; shows code quality standards for the 2.48M LOC backend
• .roo/rules/rules.md: Additional AI-guided development rules, likely overlapping with Kilocode patterns

Adding a new wsh command: Follow .kilocode/skills/add-wshcmd/SKILL.md; backend logic in Go, CLI wiring in Go backend. Creating a new view/widget: Use create-view skill (.kilocode/skills/create-view/SKILL.md); TypeScript + React in frontend. Adding config options: add-config skill guides schema and storage. Adding AI model support: Extend the AI chat widget RPC layer (add-rpc skill pattern). UI changes: SCSS in src/ (inferred from 283K CSS lines), theme definitions likely in config. Start here: Read .kilocode/rules/overview.md and CONTRIBUTING.md for conventions.

1. Durable SSH state management: SSH session state persists across restarts; incorrect changes to reconnection logic could lose user data. 2. Electron + Go IPC: Frontend-backend communication relies on RPC layer (add-rpc skill) — messages must be strictly typed and tested. 3. Credential storage: Uses native system backends (macOS Keychain, Windows Credential Manager, Linux secret-service); tests must run on target OS. 4. AI API key handling: Keys are BYOK (bring your own); if storage or transmission is broken, user keys leak silently. 5. Remote file editor state: Editing files over SSH with automatic backups requires careful conflict resolution; local and remote state can diverge. 6. .kilocode and .roo rules are AI guides: These are custom scaffolding rules; contributors must follow them or generated code will be inconsistent. 7. Testdriver builds: CI includes testdriver (testdriver.yml), suggesting integration tests run against full app; ensure test data is not checked in.

• Durable SSH Sessions with Automatic Reconnection — A core Wave feature replacing lost connections transparently; understanding the state machine (connected → disconnected → reconnecting → syncing) is essential for debugging SSH-related issues and adding features like session migration or failover
• Electron IPC and RPC Patterns — Wave's architecture splits UI (Electron/TypeScript) from logic (Go backend); contributors must understand async RPC messaging, type safety, and error handling to add features. The add-rpc skill formalizes this pattern
• Terminal Multiplexing and Block-Based Layouts — Wave's drag-drop block system (terminals, editors, previews, AI chat) requires careful state management per block; layout persistence and undo/redo are non-trivial, especially when combined with durable SSH state
• [Secure Credential Storage Using Native System Keychains](https://support.apple.com/en-us/HT204085 (macOS Keychain), https://learn.microsoft.com/en-us/windows/win32/secauthn/credentials-manager) — Wave stores API keys and SSH credentials in OS-native backends (macOS Keychain, Windows Credential Manager, Linux secret-service); testing and deployment require understanding these platform differences and access controls
• Streaming Terminal Output and Scrollback Management — Wave AI reads terminal output for context; the system must efficiently stream, buffer, and search large scrollback histories without blocking the UI or consuming unbounded memory
• [LLM Context and Token Budgeting](https://platform.openai.com/docs/guides/tokens (OpenAI token counting), https://www.anthropic.com/research/claude-token-counter) — Wave's AI assistant must fit terminal context, file contents, and user prompts within token limits (varies by model: GPT-4 Turbo ~128K, Claude 3 ~200K); contributors need to understand context compression and prioritization
• File Preview Rendering Pipeline — Wave supports inline previews for markdown, images, video, PDFs, CSVs, and directories; each format requires different rendering strategies (syntax highlighting, image decoding, PDF streaming). Contributors adding new formats must integrate with the preview system

• microsoft/terminal — Windows Terminal is the modern terminal competitor; Wave differentiates with AI integration and durable SSH, but shares similar UX goals
• alacritty/alacritty — GPU-accelerated terminal written in Rust; represents the lightweight, performance-focused alternative; Wave sacrifices speed for feature richness (AI, widgets, SSH durability)
• mosh/mosh — Mobile Shell pioneered UDP-based durable SSH connections; Wave's durable SSH sessions build on similar concepts but integrated into a full terminal UI
• OpenAI/gpt-4-turbo — Not a repo, but Wave's AI integration depends on external model APIs; understanding the model capabilities is essential for AI widget feature development
• vercel/hyper — Electron-based terminal with extensibility focus; Wave is similar in tech stack (Electron + Node) but diverged toward AI and SSH durability

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Docusaurus build validation workflow to CI/CD pipeline

The repo has a .github/workflows/deploy-docsite.yml for deployment but no separate pre-deployment validation workflow. With Docusaurus 3.9.2 and complex MDX plugins (remark-typescript-code-import, rehype-highlight), a dedicated workflow should lint, build, and validate the documentation before deployment. This prevents broken doc builds from reaching production.

• [ ] Create .github/workflows/validate-docs.yml workflow that runs on PR to docs/
• [ ] Add steps to run npm run build and npm run typecheck in the docs directory
• [ ] Include remark and ESLint linting steps (config exists in .eslintignore and .prettierignore)
• [ ] Test against the custom @waveterm/docusaurus-og plugin to catch integration issues
• [ ] Add status check requirement in GitHub branch protection rules documentation

Create skill documentation generator for .kilocode/skills/ directory

The repo has a well-structured skills directory with SKILL.md files (add-config, add-rpc, add-wshcmd, create-view, electron-api, waveenv, wps-events, context-menu) but no automated documentation or index. A contributor could add a script that generates a consolidated skills reference and validates that each skill follows the expected structure.

• [ ] Create scripts/generate-skills-index.js that scans .kilocode/skills/*/SKILL.md
• [ ] Generate a root .kilocode/SKILLS_INDEX.md with categorized list and links
• [ ] Add validation to ensure each skill directory has required files (SKILL.md, examples, etc.)
• [ ] Add pre-commit hook or npm run script to regenerate index (update Taskfile.yml)
• [ ] Document the skill template structure in .kilocode/rules/overview.md

Add TypeScript strict mode compliance test for frontend type safety

The repo has tsconfig in devDependencies and .vscode/settings.json configured, but no workflow validates TypeScript strict mode across the codebase. Given the AI-integrated UI complexity and Electron integration, adding a CI workflow to enforce strict mode compilation would catch type safety issues early.

• [ ] Create .github/workflows/typecheck-strict.yml that runs tsc --strict on all TypeScript files
• [ ] Add scripts/typecheck-strict.sh to validate React components (referenced in .vscode/extensions.json)
• [ ] Create a tsconfig.strict.json with strict mode enabled for enforcement
• [ ] Check Electron API types and React component props in the frontend
• [ ] Document strict mode adoption plan in CONTRIBUTING.md with migration guidelines

• Add unit tests for the wsh command routing layer in the Go backend (inferred from add-wshcmd skill). The backend likely has a command dispatcher; add tests for new command registration, argument parsing, and error cases.
• Improve Docusaurus documentation for the RPC pattern: the add-rpc skill exists but docs/ may lack concrete examples of adding a new RPC endpoint from Go to TypeScript, complete with type definitions. Add a tutorial with a real example (e.g., add ai-model-list RPC).
• Add CSS tests or visual regression tests for the drag-drop block UI. With 283K lines of CSS/SCSS and a complex block-based layout, many contributors probably break spacing or alignment. Set up snapshot testing for common block configurations.

The codebase demonstrates generally good security practices with a responsible disclosure policy and organized structure. However, the primary concerns are the unverified GitHub tarball dependency (bypassing npm security mechanisms) and lack of lock file verification. The flexible versioning constraints on dependencies, while allowing updates, require active security monitoring. The documentation tools and static analysis nature of this web component reduces injection and runtime vulnerability risks. Recommendations focus on hardening dependency management and implementing automated security scanning in CI/CD pipelines.

• High · Unverified GitHub Tarball Dependency — package.json - dependencies[@waveterm/docusaurus-og]. The package.json contains a direct GitHub tarball dependency (@waveterm/docusaurus-og) pinned to a specific commit hash without integrity verification. This bypasses npm's security checks and could allow man-in-the-middle attacks or compromised repository access. Fix: Consider publishing this package to npm registry with proper versioning and checksums. If internal hosting is required, use npm private registries or git SSH URLs with branch protection and code review requirements.
• Medium · Incomplete Dependency Lock Information — Repository root - missing lock file verification. The provided package.json lacks a corresponding package-lock.json or yarn.lock file content. Without lock files, different installations could pull different versions, potentially including security-patched or vulnerable versions inconsistently. Fix: Ensure package-lock.json or yarn.lock is committed to version control and up-to-date. Regularly run 'npm audit' or 'yarn audit' to identify and remediate vulnerable dependencies.
• Medium · Docusaurus Trailing Version Dependency — package.json - all @docusaurus/* dependencies. Multiple Docusaurus dependencies use caret (^) versioning (^3.9.2), allowing minor and patch updates automatically. While patch updates are usually safe, minor version updates could introduce breaking changes or security issues without explicit review. Fix: Consider using tilde (~3.9.2) for more conservative updates, or pin exact versions (3.9.2) and explicitly review updates before upgrading.
• Low · Development Dependency Caret Versioning — package.json - devDependencies section. ESLint, Prettier, and other dev tools use flexible version constraints (^9.39, ^10.1.8, etc.), which could introduce unexpected linting or formatting changes during updates. Fix: Pin dev tool versions to specific releases (e.g., '9.39.0' instead of '^9.39') to ensure consistent development environments across team members.
• Low · No Security Policy Visible in Documentation — SECURITY.md. While SECURITY.md exists with a responsible disclosure email, there is no visible security policy documentation regarding dependency management, security review processes, or incident response procedures. Fix: Enhance SECURITY.md to include: dependency update policy, security scanning automation, vulnerability response SLA, and instructions for security-related contributions.
• Low · Incomplete Package.json Content — package.json - devDependencies section (truncated). The provided package.json appears truncated (devDependencies section ends mid-line), making complete security analysis impossible. Unknown dependencies may exist beyond the visible content. Fix: Provide complete package.json content for thorough analysis. Ensure all dependencies are analyzed against known vulnerability databases.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.