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/fathyb/carbonyl 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.

WAIT — Stale — last commit 2y ago

• 11 active contributors
• BSD-3-Clause licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 88% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

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

What it runs against: a local clone of fathyb/carbonyl — 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 fathyb/carbonyl | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 705 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of fathyb/carbonyl. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/fathyb/carbonyl.git
#   cd carbonyl
#
# 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 fathyb/carbonyl and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause 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"

# 4. Critical files exist
test -f "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "src/browser.rs" \\
  && ok "src/browser.rs" \\
  || miss "missing critical file: src/browser.rs"
test -f "src/browser/bridge.rs" \\
  && ok "src/browser/bridge.rs" \\
  || miss "missing critical file: src/browser/bridge.rs"
test -f "src/output/renderer.rs" \\
  && ok "src/output/renderer.rs" \\
  || miss "missing critical file: src/output/renderer.rs"
test -f "src/input/parser.rs" \\
  && ok "src/input/parser.rs" \\
  || miss "missing critical file: src/input/parser.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 705 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~675d)"
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/fathyb/carbonyl"
  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).

Carbonyl is a Chromium-based browser engine compiled to run entirely in the terminal via ANSI escape codes, with no GUI toolkit dependency. It renders full web pages (including WebGL, WebGPU, audio, video, and animations) directly to the terminal framebuffer, starting in <1 second and maintaining 60 FPS performance. It solves the problem of viewing modern web content in headless, SSH, and safe-mode console environments where X11/Wayland are unavailable. Hybrid Rust+C++ architecture: Rust CLI and FFI wrapper (src/lib.rs exports a cdylib) bridges to Chromium's C++ core. The chromium/ subdirectory contains the patched Chromium checkout with platform-specific tweaks (patches/chromium/, patches/skia/, patches/webrtc/). Build orchestration via shell scripts in scripts/ (build.sh, gn.sh, gclient.sh) and Cargo (Cargo.toml, build.rs). Terminal rendering is handled by custom Chromium patches that bypass the normal windowing system.

DevOps engineers, terminal power users, and SSH-over-slow-connections users who need to view web content without a display server; developers building terminal-based tools that need full web rendering; and systems running in restricted environments (containers, safe mode, CI/CD systems).

Early-stage experimental (v0.0.3 as of last release). The project is actively developed (89k lines of Rust, significant C++ patches to Chromium core), but carries known limitations: fullscreen mode unsupported, no extension ecosystem yet. Not recommended for production end-user browsing; best suited for specialized headless use cases. Binaries are released but updates are infrequent.

High integration risk: the project maintains 14 in-tree Chromium patches (0001-0014 in chromium/patches/) that must be rebased on Chromium version upgrades, making dependency updates fragile. Single maintainer (fathyb) with infrequent release cadence. The build is complex (Chromium submodule + Skia + WebRTC patches) and platform-specific; Docker is provided to mitigate, but native builds require Chromium's full dependency chain. No automated test suite visible in file structure.

No recent activity visible from file timestamps, but the repository structure shows mature patch management (14 numbered Chromium patches) and Docker infrastructure (Dockerfile, docker-build.sh, docker-push.sh). The npm packaging pipeline (npm-package.mjs, npm-package.sh, npm-publish.sh) suggests ongoing distribution work. Last visible milestone: v0.0.3 with macOS (amd64/arm64) and Linux (amd64/arm64) binary releases.

Clone with submodules, then build via Docker (safest) or native:

git clone --recursive https://github.com/fathyb/carbonyl
cd carbonyl
# Via Docker (recommended):
docker run --rm -ti fathyb/carbonyl https://example.com
# Or native build (requires Chromium deps):
bash scripts/build.sh

For npm: npm install --global carbonyl && carbonyl https://github.com

Daily commands: After cloning:

# Build from source (requires Chromium toolchain):
bash scripts/build.sh

# Run against a URL:
./target/release/carbonyl https://example.com

# Or via Docker:
docker run --rm -ti fathyb/carbonyl https://example.com

No dev server; this is a statically-linked binary. For development, modify Rust code in src/ or patches in chromium/patches/, then rebuild.

• src/lib.rs — Main library entry point that orchestrates Chromium integration, terminal rendering, and input handling—every contributor must understand this orchestration.
• src/browser.rs — Core browser abstraction managing Chromium initialization and lifecycle; foundational for all rendering operations.
• src/browser/bridge.rs — Rust FFI bridge to C++ Chromium code; critical for understanding the Chromium→Rust boundary and rendering pipeline.
• src/output/renderer.rs — Terminal output rendering engine that converts Chromium frames to terminal-compatible formats; central to performance and visual fidelity.
• src/input/parser.rs — Input event parser handling keyboard/mouse events from terminal; essential for user interaction flow.
• Cargo.toml — Defines Rust dependencies and build configuration; required reading for understanding the minimal dependency footprint.
• src/browser/BUILD.gn — GN build configuration for Chromium integration; needed to understand the C++/Rust compilation bridge.

Add a new input handler (e.g., joystick support)

1. Create a new input module at src/input/{device_type}.rs with an event parsing function (src/input/{device_type}.rs)
2. Import and integrate into the main input parser orchestrator in src/input/parser.rs (src/input/parser.rs)
3. Define new InputEvent variants in src/input.rs to represent the device's capabilities (src/input.rs)
4. Handle the new events in src/ui/navigation.rs or src/browser.rs depending on whether they affect UI or web content (src/ui/navigation.rs)

Improve color quantization or add a new palette mode

1. Add new quantization algorithm or palette strategy to src/output/quantizer.rs (src/output/quantizer.rs)
2. Expose the new palette mode as a CLI option by extending src/cli/program.rs argument parsing (src/cli/program.rs)
3. Pass the palette mode through BrowserConfig in src/browser.rs and forward to the rendering pipeline (src/browser.rs)
4. Use the selected palette in src/output/painter.rs during pixel-to-cell conversion (src/output/painter.rs)

Add a new browser feature or Chrome flag

1. Add the new command-line flag to src/cli/program.rs argument definitions (src/cli/program.rs)
2. Store the setting in a new struct field in src/browser.rs (BrowserConfig or similar) (src/browser.rs)
3. Pass the setting to Chromium via args in src/browser/bridge.rs or src/browser/bridge.cc during browser initialization (src/browser/bridge.rs)
4. If the feature requires Chromium source changes, add a new patch file under chromium/patches/chromium/ (chromium/patches/chromium/00XX-{descriptive-name}.patch)

Debug rendering artifacts or performance issues

1. Inspect frame buffer composition in src/output/renderer.rs render loop and frame_sync.rs timing (src/output/renderer.rs)
2. Check pixel-to-terminal conversion and color mapping in src/output/painter.rs (src/output/painter.rs)
3. Verify ANSI escape sequence correctness in src/output/xterm.rs output generation (src/output/xterm.rs)
4. Confirm terminal window state tracking matches actual viewport in src/output/window.rs (src/output/window.rs)

• Rust (core application) — Memory safety without GC; FFI interop with Chromium C++; fast terminal I/O and event handling.
• Chromium (rendering engine) — Full web standards compliance (WebGL, WebGPU, CSS animations); reuse of mature engine; patches minimize surface area.
• Mojo IPC (browser-renderer communication) — Chromium's native inter-process communication; avoids custom serialization for display and input events.
• ANSI/xterm escape sequences — Universal terminal compatibility; 256-color and Truecolor palette support; no X11/Wayland dependency.
• GN build system — Chromium's native build system; allows seamless integration of C++ patches and custom components.

• Columnar terminal rendering (characters ≠ pixels) instead of true pixel output

  • Why: Enables SSH and remote terminal use; eliminates GPU dependency; works in safe-mode console.
  • Consequence: Lower visual fidelity than GPU rendering; color quantization and character block artifacts at fine details.

• Patch-based Chromium integration rather than direct fork

  • Why: Easier to track upstream Chromium releases; smaller maintenance surface; clear change history.
  • Consequence: Patches must be rebased on new Chromium versions; integration points tightly coupled to specific Chromium APIs.

• Minimal CLI (no GUI framework)

  • Why: Reduces binary size and startup time; pure terminal interface; no window manager dependency.
  • Consequence: No tab UI, no bookmark manager, no browser extensions; focused single-window experience.

• Synchronous rendering loop (no async/await in hot path)

  • Why: Predictable frame timing; easier to debug; lower latency for input→output.
  • Consequence: Must carefully manage blocking operations; TTY I/O must be non-blocking.

• Does not support browser extensions or Web Store integration
• Does not provide a graphical UI or tabbed interface
• Does not support Windows natively (Linux/macOS focus)
• Does not provide real-time collaborative editing or multi-user features
• Does not aim to replace traditional graphical browsers for complex web applications requiring precise rendering

Submodule complexity: chromium/.gclient and .gitmodules manage Chromium's own submodules (Skia, WebRTC). A shallow clone will fail; always use git clone --recursive. Platform specificity: Scripts auto-detect platform via scripts/platform-triple.sh; cross-compilation is not straightforward. Patch rebasing: Chromium major version bumps require rebasing all 14 patches manually; no automation visible. GN/Ninja toolchain: Build requires Chromium's GN build system and Ninja; not in typical package managers. Docker assumption: Native builds assume you have installed Chromium's full Linux build dependencies (apt/yum packages for build-essential, python3, git, curl, etc.); the Dockerfile is the 'known good' environment. Minimal test coverage: No tests/ directory visible; validation is manual and Docker-based. Single-threaded assumption: The terminal I/O abstraction may assume single-threaded event loop (check patches 0009 and 0013 for details).

• Software Rasterization (vs. Hardware Accelerated Rendering) — Carbonyl replaces Chromium's GPU rendering pipeline with Skia's CPU-based rasterizer (patch 0003); understanding this trade-off (slower but works headless) is fundamental to why the project exists
• ANSI Terminal Escape Codes & Framebuffer Abstraction — The core innovation: Carbonyl renders Chromium's output not to X11/Wayland, but directly to ANSI codes; patches 0003 and 0009 implement this abstraction layer
• Chromium Patching via Patch Files (GNU Patch Format) — 14 numbered .patch files in chromium/patches/ define all Carbonyl-specific modifications; understanding patch application, rebasing, and conflict resolution is essential for maintenance
• FFI (Foreign Function Interface) & cdylib — Rust's cdylib crate type (Cargo.toml) enables the Rust CLI to call C++ Chromium internals; Carbonyl's architecture hinges on this boundary
• GN Build System & Ninja — Chromium uses GN (a meta-build generator) and Ninja (the fast build tool); scripts/gn.sh configures this; understanding the two-stage build is necessary for troubleshooting
• Headless Browser Automation (vs. Headful) — Carbonyl is a headless variant of Chromium (no window manager required), enabling SSH and container deployment; patches remove windowing assumptions throughout the codebase
• Unicode Width & Text Layout for Terminal Output — Dependencies on unicode-width and unicode-segmentation handle East Asian characters and grapheme clusters in terminal; patches 0007, 0008, 0010 tune text rendering for terminal constraints

• browsh/browsh — Direct predecessor/competitor: also renders Firefox in terminal via headless automation, but slower; Carbonyl's README explicitly compares against it
• tcontext/yabause — Another terminal rendering project; demonstrates emulator GUIs in ANSI, similar technical challenges to Carbonyl
• chromium/chromium — The upstream Chromium project; Carbonyl is a heavily-patched fork maintained as in-tree patches for distribution
• fathyb/html2svg — Carbonyl's predecessor project (acknowledged in README); was the original html-to-raster proof-of-concept before becoming a full browser
• gfxstrand/mesa — Provides software GL rendering that Carbonyl depends on for WebGL in terminal (via Skia)

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 integration tests for CLI argument parsing in src/cli/cli.rs

The repo has src/cli.rs and src/cli/cli.rs but no corresponding test module. Given that Carbonyl is a browser with complex CLI options (URL handling, rendering flags, display settings), adding comprehensive tests for argument parsing would prevent regressions and document expected behavior for contributors.

• [ ] Create tests module in src/cli/cli.rs with test cases for URL parsing, flag validation, and edge cases
• [ ] Test integration between src/cli.rs and src/cli/cli.rs argument handling
• [ ] Document test cases for common user scenarios (SSH usage, Docker, npm installation)
• [ ] Run cargo test to verify integration with existing codebase

Add GitHub Actions workflow for automated Chromium patch validation

The repo contains 14+ Chromium patches in chromium/patches/ that must be applied in order during builds (0001 through 0014). There's no visible CI validating these patches apply cleanly, which risks silent failures when Chromium or patch dependencies change. A GitHub Action would catch broken patches early.

• [ ] Create .github/workflows/patch-validation.yml that runs scripts/patches.sh against patched Chromium versions
• [ ] Validate patch application order using chromium/patches/chromium/*.patch files
• [ ] Include patch generation testing (referenced in scripts/patches.sh) to ensure reproducibility
• [ ] Configure workflow to trigger on changes to chromium/patches/ or Chromium submodule updates

Extract and document rendering bridge API in src/browser/bridge.rs with examples

The repo has a complex bridge architecture (src/browser/bridge.rs, bridge.h, bridge.cc, carbonyl.mojom) that connects Rust, C++, and Blink/Skia. Multiple patches (0012-0014) restructured this bridge, but there's no developer documentation. Adding inline documentation and examples would help contributors understand the rendering pipeline.

• [ ] Add comprehensive rustdoc comments to src/browser/bridge.rs documenting the bridge interface
• [ ] Document the relationship between bridge.rs, src/browser/bridge.cc, and src/browser/renderer.h
• [ ] Add example usage comments showing how terminal rendering connects through carbonyl.mojom
• [ ] Create a brief BRIDGE.md file explaining DPI setup (0006), text rendering (0008, 0010), and Skia integration (patches 0013-0014)

• Add basic integration tests: Create tests/integration_test.rs that spawns carbonyl against a local file:// HTML page and verifies terminal output contains expected text. Currently no test harness exists, making regressions invisible.
• Document the patching workflow: Write scripts/PATCHING.md explaining how to rebase chromium/patches/ on a new Chromium version, including which patches conflict most often and why. This would lower barrier to Chromium dependency updates.
• Implement screenshot capture for headless CI: Add a --screenshot flag to output a terminal-rendered PNG/SVG at the URL, enabling use in CI pipelines. Would require wrapping Skia's screenshot API and piping it through current terminal renderer.

• High · Incomplete Dockerfile - Truncated Security Configuration — Dockerfile (line ~20). The Dockerfile is truncated mid-execution at the user creation step ('c'). This incomplete configuration may result in missing security hardening steps, improper file permissions, or missing security directives that were intended to be applied. Fix: Complete the Dockerfile by adding all intended RUN commands, ensuring proper file permissions are set for the carbonyl user and application files, and verify all security configurations are in place before deployment.
• High · Chromium Patches - Unverified Custom Modifications — chromium/patches/ directory (all patch files). The codebase applies 14 custom patches to Chromium and 2 to Skia, including patches that disable security features (text rendering, debug assertions). These modifications to core security-sensitive components could introduce vulnerabilities or remove security protections without clear documentation of the security implications. Fix: Document security implications for each patch, particularly those disabling features. Conduct security review of patch 0005 (Remove-some-debug-assertions.patch) and patch 0007 (Disable-text-effects.patch) to ensure they don't weaken security. Implement a patch verification/signing process.
• High · Missing Cargo.toml Dependency Verification — Cargo.toml, Cargo.lock. While dependencies listed are relatively minimal and appear legitimate, there is no evidence of dependency auditing or lock file security verification in the provided information. The project uses 'libc' which is a critical low-level dependency. Fix: Run 'cargo audit' regularly in CI/CD pipeline. Pin exact versions in Cargo.lock. Implement automated dependency scanning and security alerts. Document rationale for using libc and verify it's from the official source.
• Medium · Configuration File Without Apparent Access Controls — .refloat/config.js. .refloat/config.js is present in the repository structure but no access controls or input validation mechanisms are documented. If this file is used for runtime configuration, it could be vulnerable to manipulation. Fix: Review the purpose and usage of config.js. If it's deployed with the application, ensure it's not world-writable. Implement input validation for any configuration loading. Consider moving sensitive configs to environment variables.
• Medium · Docker Image Lacks Security Hardening — Dockerfile (FROM debian:bullseye-slim). The Dockerfile uses 'debian:bullseye-slim' as base image. While slim variant is good, there's no evidence of additional hardening: no security scanning of base image, no distroless alternative considered, and the image allows running arbitrary commands from untrusted sources (based on Docker usage example showing direct URL input). Fix: Scan base image for vulnerabilities. Consider using distroless or alpine images for smaller attack surface. Add LABEL directives for security metadata. Implement read-only filesystem where possible. Use '--security-opt=no-new-privileges' in Docker recommendations.
• Medium · Terminal Input Processing - Potential for Input-Based Attacks — src/input/dcs/parser.rs, src/input/keyboard.rs, src/input/mouse.rs. The input processing system (src/input/ with DCS parser, keyboard, mouse handlers) processes untrusted terminal input. Custom parsers for DCS (Device Control String) and terminal protocols could be vulnerable to parsing errors, buffer overflows, or injection attacks if not carefully validated. Fix: Implement comprehensive input validation and bounds checking. Add fuzzing tests for DCS parser. Sanitize all terminal input before processing. Implement timeout mechanisms for malformed input sequences. Use established parsing libraries where possible rather than custom implementations.
• Medium · Arbitrary URL Handling Without Validation — src/cli/cli.rs, src/cli/program.rs. The application accepts URLs directly as command-line arguments and passes them to Chromium without documented validation. This could allow SSRF (Server-Side Request Forgery), file:// protocol access, or other malicious URL schemes. Fix: Implement URL validation whitelist for protocols (https, http only by default). Sanitize and validate all user-provided URLs. Implement SSRF protections. Document security considerations around file://, data:, and javascript: URLs.
• Low · No Apparent Security Documentation — undefined. No SECURITY.md Fix: undefined

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.