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/gui-cs/Terminal.Gui 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
• 6 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 53% of recent commits

_{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 gui-cs/Terminal.Gui repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gui-cs/Terminal.Gui.

What it runs against: a local clone of gui-cs/Terminal.Gui — 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 gui-cs/Terminal.Gui | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | 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 gui-cs/Terminal.Gui. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gui-cs/Terminal.Gui.git
#   cd Terminal.Gui
#
# 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 gui-cs/Terminal.Gui and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f ".claude/rules/cwp-pattern.md" \\
  && ok ".claude/rules/cwp-pattern.md" \\
  || miss "missing critical file: .claude/rules/cwp-pattern.md"
test -f ".claude/rules/unicode-graphemes.md" \\
  && ok ".claude/rules/unicode-graphemes.md" \\
  || miss "missing critical file: .claude/rules/unicode-graphemes.md"
test -f "Directory.Build.props" \\
  && ok "Directory.Build.props" \\
  || miss "missing critical file: Directory.Build.props"
test -f ".claude/api-reference.md" \\
  && ok ".claude/api-reference.md" \\
  || miss "missing critical file: .claude/api-reference.md"
test -f ".github/workflows/build-validation.yml" \\
  && ok ".github/workflows/build-validation.yml" \\
  || miss "missing critical file: .github/workflows/build-validation.yml"

# 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/gui-cs/Terminal.Gui"
  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).

Terminal.Gui is a cross-platform .NET library for building sophisticated terminal UI (TUI) applications with responsive layouts, 50+ built-in widgets, mouse support, TrueColor, and Unicode. It solves the problem of creating modern, interactive console UIs on Windows, macOS, and Linux without writing platform-specific terminal control codes. Monolithic repo with C# as primary language (99% of codebase). Core widget implementations likely in src/ (inferred), examples in Examples/UICatalog/, comprehensive .claude/ AI assistant rules documenting API patterns, code layout, event patterns, and Unicode grapheme handling. CI orchestrated through .github/workflows/ with DocFX-based documentation pipeline (api-docs.yml).

.NET developers building CLI tools, system administration utilities, and interactive console applications who need a high-level abstraction over ANSI escape sequences and platform-specific terminal APIs. Also used by developers creating in-line CLI tools similar to GitHub Copilot's CLI interface.

Production-ready and actively maintained. The project has 11k+ GitHub stars, over 1.7M NuGet downloads, comprehensive CI/CD pipelines (.github/workflows/ contains build-validation, integration-tests, codeql-analysis), and recently released v2.0. Multiple active GitHub workflows and recent commit activity indicate ongoing development.

Low risk for core stability but moderate risk for bleeding-edge features. The codebase is large (~11M lines of C#) with established test infrastructure and proper dependency management (.config/dotnet-tools.json). Main risks: cross-platform terminal behavior variations require careful testing on all three platforms (Windows/macOS/Linux), and the large surface area (50+ widgets) means breaking changes in v3+ could affect many applications.

Version 2.0 has been released and is actively being refined. Recent workflow additions show focus on integration testing (integration-tests.yml), CodeQL security analysis, and automated release preparation (prepare-release.yml, finalize-release.yml). The .claude/ directory with multiple agent configurations and feedback memory files suggests active use of AI-assisted development for code quality and maintenance.

git clone https://github.com/gui-cs/Terminal.Gui.git
cd Terminal.Gui
dotnet restore
dotnet build
dotnet run --project Examples/UICatalog/UICatalog.csproj

Daily commands:

dotnet run --project Examples/UICatalog/UICatalog.csproj
``` for the full demo. For development: ```bash
dotnet build
dotnet test
``` (inferred from CI workflows). See .github/workflows/build-validation.yml for full build matrix.

• .claude/rules/cwp-pattern.md — Documents the CWP (Control With Properties) pattern that governs how all UI controls are implemented in Terminal.Gui
• .claude/rules/unicode-graphemes.md — Essential guide for handling Unicode text rendering, critical for cross-platform TUI correctness
• Directory.Build.props — Central build configuration that controls version, packaging, and all project defaults across the monorepo
• .claude/api-reference.md — Public API contract documentation that all contributors must respect when adding or modifying controls
• .github/workflows/build-validation.yml — Primary CI/CD pipeline defining test coverage expectations and build validation for all commits
• .claude/projects/C--Users-Tig-s-gui-cs-Terminal-Gui/memory/feedback_textview_fragile.md — Institutional knowledge about TextViewcomponent fragility and refactoring hazards
• CONTRIBUTING.md — Developer contribution guidelines and code review expectations for this project

• View (Base Control Class) (C# abstract class hierarchy, property system, event handlers) — Abstract base for all 50+ built-in controls; manages properties, layout, input routing, rendering lifecycle
  • Failure mode: Broken layout or event routing cascades across entire control tree
• Layout Engine (Constraint-based layout algorithm, cache invalidation) — Recursive layout calculation system for responsive positioning; handles width/height constraints and auto-sizing
  • Failure mode: Layout cycles, incorrect positioning, memory overhead if not properly cached
• Terminal Driver Abstraction (Platform APIs (Win32 Console, termios, launchctl), capability detection) — Platform-specific implementations (Windows, Unix, macOS) for color, input, screen manipulation
  • Failure mode: Rendering artifacts, unresponsive input, platform-specific crashes
• Double-Buffer & Renderer (Cell-based memory buffer, LCS/diff algorithm) — Maintains off-screen buffer, renders views, diffs against previous frame, writes minimal delta to terminal
  • Failure mode: Flickering output, excessive I/O

Add a New Terminal.Gui Control

1. Read .claude/rules/cwp-pattern.md to understand control implementation structure with properties, state management, and layout behavior (.claude/rules/cwp-pattern.md)
2. Create control class inheriting from View base, implementing CWP pattern for properties and state (Examples/Example/Example.cs)
3. Add unit tests validating control rendering, input handling, and layout responsiveness (.github/workflows/unit-tests.yml)
4. Create example demonstrating control usage in Examples folder following fluent builder pattern (Examples/FluentExample/FluentExample.csproj)

Support New Platform or Terminal

1. Review Unicode and grapheme handling requirements in .claude/rules/unicode-graphemes.md (.claude/rules/unicode-graphemes.md)
2. Implement terminal driver abstraction handling color, mouse, keyboard for target platform (.github/workflows/build-validation.yml)
3. Add platform-specific configuration and testing in build validation workflow (.config/dotnet-tools.json)

Create Integration Example (MVVM, F#, Native AOT)

1. Choose integration pattern: MVVM (CommunityToolkitExample), F# (FSharpExample), or Native AOT (NativeAot) (Examples/CommunityToolkitExample/LoginView.cs)
2. Create new example project folder with .csproj matching target framework from Directory.Build.props (Directory.Build.props)
3. Implement example code following pattern conventions and include README.md documentation (Examples/Example/Example.cs)
4. Add example validation to integration test workflow if applicable (.github/workflows/integration-tests.yml)

• .NET / C# with target frameworks net8.0, net9.0 — Cross-platform runtime with native support for Windows, macOS, Linux; strong type safety and modern language features
• Double-buffering rendering with cell-level diffing — Minimizes terminal I/O for performance and smooth animations; reduces flicker
• Responsive layout system (not grid-based) — Enables terminal UIs to adapt dynamically like responsive web pages rather than fixed-size terminal grids
• Unicode grapheme-cluster aware text handling — Correctly renders international text, emoji, and complex scripts in terminal environment
• GitHub Actions CI/CD with matrix testing — Validates behavior across Windows, macOS, Linux platforms and multiple .NET versions simultaneously

• 48+ built-in controls vs. custom control toolkit

  • Why: Provides high-level abstraction for common UI patterns to accelerate application development
  • Consequence: Larger surface area to maintain; custom highly specialized controls require extension

• Responsive layout system vs. grid-based constraints

  • Why: More flexible adaptation to terminal resize events and natural element sizing
  • Consequence: More complex layout calculation; potential performance hit on very large layouts

• TrueColor support with fallback to 256/16-color modes

  • Why: Modern terminals support 24-bit color; graceful degradation on legacy terminals
  • Consequence: Conditional color palette logic; testing burden across color mode combinations

• Web-based UI rendering or browser interoperability
• Real-time collaboration or distributed state synchronization
• Native platform GUI integration (GTK, Cocoa, Win32 native windows)
• Embedded analytics or telemetry collection
• Database abstraction layer or ORM
• Authentication or authorization framework

Terminal dimensions and rendering are platform-specific: the same code may behave differently on Windows Console vs Unix terminals (especially regarding mouse events and color support). Unicode grapheme handling requires careful attention per .claude/rules/unicode-graphemes.md — simple character iteration will break multi-codepoint characters. Cross-platform testing is mandatory; CI runs on all three platforms but local development typically on one OS. Double-buffering means visual changes only render on explicit flush calls — forgetting this causes flickering. Mouse events availability varies by terminal emulator even on same OS.

• Double buffering — Terminal.Gui uses double buffering to eliminate flicker; understanding when buffer swaps occur is critical for responsive UI design and performance tuning
• ANSI escape sequences — Core mechanism for cross-platform terminal control on Unix/Linux/macOS; Terminal.Gui abstracts these but knowing them helps debug rendering issues
• Unicode grapheme clusters — Terminal.Gui's .claude/rules/unicode-graphemes.md exists because emoji, diacritics, and combining marks require grapheme-aware string handling, not simple char iteration
• Responsive layout systems — Terminal.Gui's innovation is layout responsiveness without CSS; understanding DIP/screen coordinates and constraint-based sizing is core to building adaptive TUIs
• Terminal I/O multiplexing (select/epoll) — Cross-platform keyboard and mouse input handling requires async I/O patterns; Windows Console API and Unix termios have fundamentally different APIs
• TrueColor (24-bit color) — Terminal.Gui supports 16.7M colors but only on compatible terminals; fallback handling for 256-color and 16-color modes is essential for broad compatibility
• Event-driven UI architecture — Per .claude/rules/event-patterns.md, Terminal.Gui uses event bubbling and routing similar to web frameworks; understanding event propagation prevents input handling bugs

• migueldeicaza/gui.cs — The predecessor library to Terminal.Gui v1; understanding its design provides historical context for v2 architectural decisions
• spectreconsole/spectre.console — Alternative .NET console UI library focusing on rich formatting and tables; often used alongside Terminal.Gui for specific output scenarios
• gui-cs/Terminal.Gui.Templates — Companion repo providing dotnet templates for scaffolding new Terminal.Gui projects; referenced in quick-start
• gui-cs/Terminal.Gui.SampleApps — Collection of example applications demonstrating Terminal.Gui patterns in real-world scenarios
• JetBrains/intellij-community — JetBrains Rider and CLI tools use similar TUI patterns for cross-platform terminal UIs; good reference for production TUI design patterns

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 comprehensive unit tests for Terminal.Gui.Views namespace

The repo has extensive CI workflows (.github/workflows/) but the file structure suggests Views are core abstractions. Currently, there's no visible test coverage documentation or dedicated test files for individual View types. With 50+ built-in views mentioned in README, systematically adding unit tests for underrepresented View types would significantly improve code quality and make the codebase safer for refactoring.

• [ ] Identify View types in src/ without corresponding test files in the test suite
• [ ] Start with commonly-used Views (e.g., TextField, Button, ListView, TableView)
• [ ] Create unit tests covering initialization, event handling, and state management
• [ ] Reference .claude/rules/testing-patterns.md for the maintainer's testing conventions
• [ ] Integrate tests into the existing test execution (referenced in .github/workflows/unit-tests.yml)

Implement missing API documentation for event-handling patterns

The .claude/rules/event-patterns.md exists, suggesting the maintainers have strong conventions around events, but .claude/api-reference.md may lack concrete examples. The repo uses custom event patterns (non-standard .NET conventions), and this is a barrier to new contributors. Creating well-documented examples of the custom event system with real View implementations would reduce contributor onboarding friction.

• [ ] Review .claude/rules/event-patterns.md and identify divergences from standard .NET events
• [ ] Audit .claude/api-reference.md for gaps in event documentation
• [ ] Create a new dedicated guide (e.g., docs/event-patterns-guide.md) with 5-10 real examples from actual Views
• [ ] Include before/after patterns showing old vs. new event handling
• [ ] Link this guide from the main CONTRIBUTING.md

Add stress-test validation workflow for long-running TUI scenarios

The repo has a stress-tests.yml workflow file (.github/workflows/stress-tests.yml) but it's likely incomplete or not integrated into the main CI pipeline. Given Terminal.Gui is for sophisticated TUI apps, stress-testing rendering loops, memory under continuous updates, and Unicode grapheme handling (mentioned in .claude/rules/unicode-graphemes.md) is critical. A well-defined stress test suite would catch performance regressions early.

• [ ] Review existing .github/workflows/stress-tests.yml and identify missing test scenarios
• [ ] Create stress test cases for: rapid View updates, large datasets in TableView, continuous input handling, and Unicode-heavy rendering
• [ ] Reference .claude/rules/unicode-graphemes.md for grapheme-specific stress scenarios
• [ ] Integrate stress test results into PR checks (modify .github/workflows/build-validation.yml)
• [ ] Document expected baselines and failure thresholds in .github/workflows/README.md

• Add unit tests for the Table/TreeView sorting and filtering logic — the 'scalable to infinite elements' claim needs robust test coverage for edge cases like empty datasets, single-element trees, and large filtered result sets
• Extend Unicode support test suite in .claude/rules/unicode-graphemes.md with regional indicators, zero-width joiners, and emoji skin tone modifiers — Terminal.Gui claims Unicode support but complex grapheme clusters often have platform-specific rendering bugs
• Create platform-specific terminal compatibility matrix documentation: audit which features (mouse drag, TrueColor gradients, specific key sequences) work on Windows 10/11 Terminal, iTerm2, GNOME Terminal, and add skip conditions to integration tests for unsupported combinations

The Terminal.Gui codebase demonstrates reasonable security practices with centralized dependency management (Dependabot configured), MIT license transparency, and structured project organization. However, the primary concern is the inadequate vulnerability disclosure policy in SECURITY.md, which directs security reports to public issue trackers instead of a private channel. Additionally, example projects containing authentication logic warrant review to ensure they don't introduce anti-patterns. No hardcoded secrets or injection-prone SQL patterns are evident from the file structure analysis. The project would benefit from implementing a responsible disclosure policy, conducting security audits on example code, and maintaining regular dependency vulnerability scans.

• Medium · Vulnerability Disclosure Policy Missing Details — SECURITY.md. The SECURITY.md file lacks specific security contact information and response timelines. It directs users to submit security issues via public Issues, which is not a best practice for sensitive security disclosures. Fix: Add a dedicated security contact email (e.g., security@example.com) or use GitHub's Security Advisory feature. Implement a responsible disclosure policy with expected response times. Avoid directing security reports to public issue trackers.
• Low · Potential Dependency Version Tracking Gap — Directory.Packages.props. The Directory.Packages.props file structure suggests centralized dependency management, but without viewing the actual dependency versions, there's a risk of outdated or vulnerable transitive dependencies not being explicitly tracked. Fix: Regularly audit dependencies using tools like 'dotnet list package --vulnerable' and 'OWASP Dependency-Check'. Implement automated dependency scanning in CI/CD pipelines via GitHub Dependabot (already configured in .github/dependabot.yml).
• Low · DevContainer Configuration Exposure — .devcontainer/devcontainer.json. The .devcontainer/devcontainer.json file may contain or reference sensitive environment configurations. If committed with secrets, this could expose credentials to anyone with repository access. Fix: Ensure no hardcoded secrets, API keys, or credentials are in devcontainer configuration. Use devcontainer secrets management or environment variable references instead. Document sensitive setup steps separately.
• Low · Example Project Configuration Review Needed — Examples/CommunityToolkitExample/. The Examples/CommunityToolkitExample directory contains LoginActions.cs and LoginViewModel.cs which may contain authentication logic. Without code review, there's risk of insecure authentication patterns. Fix: Review authentication examples to ensure they follow security best practices: use HTTPS, implement proper credential handling, avoid storing plaintext passwords, and use established authentication libraries.
• Low · Build Configuration Security — Directory.Build.props. Directory.Build.props is a global MSBuild configuration file. If misused, it could enforce insecure build settings across the entire project. Fix: Ensure build configurations enforce security settings: enable compiler warnings, use security analyzers (SecurityCodeScan, Roslyn analyzers), and disable insecure features like dangerous compiler options.

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.