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/Aloxaf/silicon 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

• 24+ active contributors
• MIT licensed
• CI configured
• ⚠ Stale — last commit 2y ago
• ⚠ Concentrated ownership — top contributor handles 60% of recent commits
• ⚠ 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 Aloxaf/silicon repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Aloxaf/silicon.

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

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Aloxaf/silicon(\\.git)?\\b" \\
  && ok "origin remote is Aloxaf/silicon" \\
  || miss "origin remote is not Aloxaf/silicon (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master 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/bin/silicon/main.rs" \\
  && ok "src/bin/silicon/main.rs" \\
  || miss "missing critical file: src/bin/silicon/main.rs"
test -f "src/formatter.rs" \\
  && ok "src/formatter.rs" \\
  || miss "missing critical file: src/formatter.rs"
test -f "src/font.rs" \\
  && ok "src/font.rs" \\
  || miss "missing critical file: src/font.rs"
test -f "src/assets.rs" \\
  && ok "src/assets.rs" \\
  || miss "missing critical file: src/assets.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 619 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~589d)"
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/Aloxaf/silicon"
  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).

Silicon is a Rust CLI tool that renders source code into beautiful images, similar to Carbon but without requiring a browser or internet connection. It uses syntect for syntax highlighting, imageproc for image generation, and harfbuzz for advanced text shaping, producing PNG output with customizable styling (shadows, backgrounds, fonts, window chrome). Single binary with library split: src/lib.rs exports core rendering logic (blur, formatter, font handling), while src/bin/silicon/main.rs handles CLI via structopt with config parsing. Assets (fonts in assets/fonts/, syntax/theme definitions in assets/syntaxes.bin and assets/themes.bin) are bundled at compile time. Harfbuzz integration is optional, toggled at feature level.

Developers and technical writers who want to quickly generate polished code snippet images for documentation, blog posts, and presentations without web dependencies. Users value the offline-first approach and shell integration (clipboard input/output) over Carbon's visual polish.

Actively maintained but modest scope—at v0.5.2 with established CI/CD pipelines (release.yml, dependabot), single maintainer (Aloxaf), and available on major package managers (Cargo, AUR, Homebrew). The project is production-ready for its intended use case but intentionally stays simpler than Carbon; not abandoned but not rapidly evolving.

Single-maintainer project with limited test visibility in the file list and heavy reliance on external system libraries (libharfbuzz, fontconfig, libxcb on Linux, pasteboard on macOS). Windows builds require disabling harfbuzz feature by default, suggesting platform-specific fragility. Dependency chains through imageproc, syntect, and font-kit introduce transitive risks.

Recent maintenance focus is on dependency updates (Cargo.lock shows recent image, syntect, dirs versions) and platform support refinement. No specific PR or issue data visible, but CI workflows (ci.yml, release.yml) are actively configured with dependabot for automated updates, indicating steady-state maintenance rather than active feature development.

git clone https://github.com/Aloxaf/silicon
cd silicon
cargo build --release
./target/release/silicon --help

On Ubuntu, first install system deps: sudo apt install libfreetype6-dev libexpat1-dev libharfbuzz-dev libfontconfig1-dev pkg-config. On macOS, Homebrew handles deps via brew install silicon directly.

Daily commands:

cargo run --release -- main.rs -o main.png
# or with features disabled:
cargo run --release --no-default-features --features bin -- --from-clipboard -l rs --to-clipboard

No dev server; it's a CLI tool. For library use, omit the bin feature in Cargo.toml.

• src/lib.rs — Core library entry point defining the public API and primary rendering pipeline that all consumers depend on
• src/bin/silicon/main.rs — CLI entry point that orchestrates argument parsing, file loading, and invokes the core rendering logic
• src/formatter.rs — Handles syntax highlighting and code formatting—a load-bearing module for visual output quality
• src/font.rs — Font loading and management system that supports multiple font sources and fallbacks
• src/assets.rs — Embeds and manages bundled syntax definitions, themes, and fonts—critical for zero-dependency distribution
• Cargo.toml — Defines feature flags (harfbuzz, bin) and optional dependencies that change core rendering behavior
• src/bin/silicon/config.rs — Configuration parsing from CLI arguments and config files that drives all rendering parameters

• CLI & Config (main.rs, config.rs) (structopt, shell-words, anyhow) — Parse user input, resolve file paths, merge CLI flags with config files, validate arguments
  • Failure mode: Missing files, invalid flags, or malformed config cause early exit with error message
• Core Renderer (lib.rs) (imageproc, custom layout logic) — Orchestrate the entire rendering pipeline: load assets, format code, layout text, render to image buffer
  • Failure mode: Out-of-memory on huge files, invalid image dimensions, or unsupported color modes
• Syntax Highlighter (formatter.rs) (bat (embedded), syntaxes.bin) — Apply TextMate grammar rules to source code, produce token stream with color assignments
  • Failure mode: Unknown file extension defaults to plaintext; malformed syntax definitions produce uncolored output
• Font System (font.rs, hb_wrapper.rs) (font-kit, harfbuzz-sys, freetype) — Discover fonts on system, load TTF/OTF files, integrate HarfBuzz for text shaping, handle fallbacks
  • Failure mode: Font not found → fallback to embedded Hack font; HarfBuzz unavailable → basic glyph positioning
• Asset Manager (assets.rs) — Expose

Add a new color theme

1. Create a new .tmTheme or .yaml theme file following the bat syntax standard (assets/themes)
2. Run assets/sync_from_bat.sh to recompile themes.bin with your new theme (assets/sync_from_bat.sh)
3. Reference the theme name in the config via --theme flag or config file (src/bin/silicon/config.rs)

Add a new syntax highlighter language

1. Place .sublime-syntax definition in assets/syntaxes/ (compatible with bat format) (assets/syntaxes)
2. Re-run theme sync to include new syntax in .bin bundle (assets/sync_from_bat.sh)
3. Syntax will be auto-detected from file extension via the formatter (src/formatter.rs)

Add a new rendering option (e.g., border style)

1. Add new config field to the Config struct (src/bin/silicon/config.rs)
2. Add corresponding CLI argument via structopt macro in main (src/bin/silicon/main.rs)
3. Pass config option into rendering pipeline and implement visual logic (src/lib.rs)

Add support for a new font source

1. Extend the font loading logic and priority chain (src/font.rs)
2. Update fallback strategies to include your new source (src/font.rs)
3. Test font discovery via CLI --font parameter (src/bin/silicon/config.rs)

• Rust + imageproc — Provides zero-dependency, fast, offline image rendering without requiring web browsers or network calls (unlike Carbon)
• HarfBuzz (optional) — Enables proper Unicode text shaping and complex script handling for multilingual code display
• bat syntax/theme format — Reuses mature, well-maintained syntax definitions and color themes from the bat project rather than inventing custom formats
• structopt CLI framework — Provides declarative, type-safe argument parsing with automatic help text generation
• Embedded assets (.bin bundles) — Eliminates external file dependencies, enabling single-binary distribution and offline operation

• Optional HarfBuzz feature vs. basic text rendering

  • Why: HarfBuzz adds C FFI complexity and build-time dependencies but enables correct text layout for ligatures and complex scripts
  • Consequence: Default binary is smaller/faster to compile without HarfBuzz, but users with complex scripts need to enable the feature

• Embedded theme/syntax binaries vs. external files

  • Why: Bundling eliminates config file paths and ensures users always have working defaults
  • Consequence: Slightly larger binary size but guaranteed offline operation; theme customization requires recompilation

• Clipboard integration vs. file-only output

  • Why: Clipboard support improves UX for social media sharing workflows
  • Consequence: Adds platform-specific clipboard dependency; may fail on headless systems

• Syntax highlighting via bat format vs. hand-rolled parser

  • Why: Reusing bat's proven syntax definitions provides broad language support and correctness
  • Consequence: Binds to bat's TextMate-based grammar; harder to add experimental syntax systems

• Does not provide a web UI or browser-based interface (intentionally offline-first)
• Does not support real-time collaborative editing or multi-user sessions
• Does not implement advanced code transformation or AST-based analysis—purely visual rendering
• Does not handle terminal ANSI escape sequences; input must be plain source code
• Does not support plugins or scripting for custom themes/formatters without recompilation

Feature flags matter: default includes harfbuzz, but Windows users often need --no-default-features --features bin to avoid link-time failures. Assets must be present: syntaxes.bin and themes.bin are required at runtime; they're embedded in the binary during build but sync script (assets/sync_from_bat.sh) must be run manually if updating. Platform-specific clipboard: macOS uses pasteboard crate, Windows uses clipboard-win, Linux uses generic clipboard—test on your target OS. Font fallback chain syntax: colon-separated fonts with optional size suffix (e.g., Hack; SimSun=31) is parsed by src/font.rs; malformed input silently falls back to defaults. No MSVC support documented: Rust edition 2018 + complex C dependencies suggest MinGW/Unix-like build is expected on Windows.

• Syntax highlighting via compiled definitions (syntect + .bin assets) — Silicon embeds pre-compiled syntax/theme rules (syntaxes.bin, themes.bin) rather than parsing YAML at runtime; understanding how syntect loads these definitions is key to customizing or debugging highlighting
• HarfBuzz text shaping — Complex scripts (CJK, Arabic, Devanagari) require proper glyph positioning; Silicon wraps harfbuzz-sys for this via src/hb_wrapper.rs, falling back to simple layout when disabled—critical for international code display
• Font fallback chains — Silicon allows specifying multiple fonts with per-font size overrides (e.g., 'Hack; SimSun=31') for multi-script support; understanding the chain resolution in src/font.rs is essential for supporting non-Latin characters
• Raster image composition (imageproc + image crate) — Silicon builds the final image by compositing text glyphs, shadows, backgrounds, and window chrome using imageproc pixel-level operations; changes to visual output require understanding image compositing order
• SIMD for geometry calculations (pathfinder_simd) — Text layout coordinates use SIMD-optimized geometry; the patched pathfinder in Cargo.toml provides performance for rendering large code snippets
• Platform-specific clipboard backends — Silicon supports --from-clipboard and --to-clipboard via different crates per OS (pasteboard/macOS, clipboard-win/Windows, generic/Linux); feature-gating and platform testing are non-trivial
• Rayon data parallelism — Image rendering is parallelized across CPU cores via rayon; critical for performance when generating large or high-resolution images

• sharkdp/bat — Source of syntax definitions and themes (assets/syntaxes.bin and assets/themes.bin are synced from bat via assets/sync_from_bat.sh); core upstream dependency for highlighting
• dawnlabs/carbon — The original web-based Carbon tool that inspired Silicon; direct alternative that requires browser/internet but offers more sophisticated visual styling
• Aloxaf/cargo-ship — Same maintainer's shipping/release tool; useful for understanding CI/release patterns in Aloxaf's ecosystem
• servo/pathfinder — Provides pathfinder_geometry and pathfinder_simd used for text layout geometry; patched in Cargo.toml for SIMD performance
• rust-lang/rustfmt — Shares similar CLI design philosophy (structopt-based) and operates on source code; relevant for understanding Rust CLI tooling 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 src/formatter.rs and src/hb_wrapper.rs

The repo currently lacks visible unit tests for core rendering modules. The formatter and harfbuzz wrapper are critical for code-to-image conversion quality, but have no visible test coverage. This is a high-risk area where bugs could degrade output quality. Adding tests would improve maintainability and catch regressions in syntax highlighting and text rendering.

• [ ] Create tests/formatter_tests.rs with test cases for different code languages and syntax highlighting edge cases
• [ ] Create tests/hb_wrapper_tests.rs covering font fallback, text shaping, and different character sets
• [ ] Add CI test execution in .github/workflows/ci.yml (if not already running cargo test)
• [ ] Document expected behavior for font rendering with unsupported glyphs

Add integration tests with example code snippets and golden image comparisons

The example/example.rs exists but there's no automated testing against known-good outputs. Adding golden image tests would catch visual regressions when dependencies (syntect, imageproc, fonts) are updated. This is critical for a tool whose primary value is visual output quality.

• [ ] Create tests/integration_tests.rs with test cases using files from example/
• [ ] Set up golden image comparison logic using image crate's pixel-level comparison
• [ ] Generate and commit baseline .png files in tests/golden_images/ for different themes and languages
• [ ] Add a CI step in .github/workflows/ci.yml to run integration tests and flag visual differences above a threshold

Add detailed README documentation for library usage and feature flags

The README.md is incomplete (ends mid-sentence: 'It's is implemented in Rust and') and lacks critical documentation. The codebase has important feature flags (bin, harfbuzz) but no guidance for users wanting to use silicon as a library vs. CLI tool. The dependencies section has platform-specific overrides (macOS pasteboard, Windows clipboard-win) that should be documented.

• [ ] Complete the README.md 'Why Silicon' section and add section: 'As a Library vs CLI Tool'
• [ ] Document feature flags in README: when to use default=[], default=["harfbuzz"], and disable harfbuzz for lighter builds
• [ ] Add 'Configuration' section documenting src/bin/silicon/config.rs options with examples
• [ ] Add 'Platform Notes' section explaining macOS pasteboard and Windows clipboard-win dependencies
• [ ] Add code examples showing both CLI usage and library usage (with example from lib.rs)

• Add tests for src/font.rs fallback chain parsing logic: No test file visible for font.rs despite its critical role in cross-platform text rendering; PR should add unit tests for the font spec parser (e.g., 'Hack; SimSun=31; code2000' edge cases)
• Document CLI flag examples in README for each src/bin/silicon/config.rs option: Config.rs has many structopt fields but README only shows a few examples; adding a systematic table of all flags with before/after image comparisons would help users discover features
• Create a GitHub Action / shell script to auto-generate and commit updated assets/syntaxes.bin and assets/themes.bin: assets/sync_from_bat.sh exists but is manual; automating the sync with bat releases (via schedule or workflow dispatch) reduces maintenance friction and keeps syntax support current

The silicon codebase shows a generally reasonable security posture for a CLI image generation tool. The primary concerns are: (1) an outdated clipboard dependency lacking recent security updates, (2) a git-patched dependency that reduces supply chain transparency, and (3) missing explicit vulnerability scanning in CI/CD. The project does not exhibit obvious injection vulnerabilities, hardcoded secrets, or misconfigurations in the visible portions. Recommendations focus on dependency management, vulnerability monitoring, and input validation for image processing. The MIT license and open repository suggest good transparency practices.

• Medium · Outdated clipboard dependency — Cargo.toml - dependencies.clipboard. The clipboard crate version 0.5.0 is significantly outdated. Recent versions contain bug fixes and security improvements. This dependency handles clipboard operations which could potentially be exploited if not up-to-date. Fix: Update clipboard to the latest stable version (0.5.0 is from 2022). Consider using recent alternatives like arboard if clipboard is no longer actively maintained.
• Medium · Patched dependency override without clear rationale — Cargo.toml - patch.crates-io.pathfinder_simd. The Cargo.toml includes a patch.crates-io override for pathfinder_simd pointing to a git repository. While patches can be legitimate, using git sources instead of versioned releases makes dependency supply chain more opaque and harder to audit. Fix: Document why this patch is necessary. If the official version is sufficient, remove the patch. If the patch is essential, consider forking to a stable point or waiting for an official release.
• Low · Regex-onig feature may have historical vulnerabilities — Cargo.toml - dependencies.syntect. The syntect dependency uses regex-onig feature which enables Oniguruma regex library. While not inherently insecure, Oniguruma has had vulnerability history. The library processes user-supplied syntax files which could potentially contain malicious patterns. Fix: Monitor security advisories for regex-onig and Oniguruma. Consider if regex-onig is necessary or if the default regex engine would suffice. Validate/sanitize custom syntax files from untrusted sources.
• Low · No explicit security audit or vulnerability scanning visible — .github/workflows/ci.yml (not provided in full). No evidence of cargo-audit or similar security scanning tools in CI/CD pipeline based on provided workflow files. The project does not appear to have explicit dependency vulnerability scanning enabled. Fix: Add cargo-audit or cargo-deny to CI pipeline. Include automated dependency vulnerability scanning on pull requests and releases.
• Low · Image processing from untrusted sources — Cargo.toml - dependencies.image and src/ (image processing code not fully visible). The image crate with multiple format decoders (jpeg, png) is used without visible validation. Processing specially crafted image files could potentially cause DoS or other issues. Fix: Implement input validation for image formats. Set reasonable size limits on processed images. Consider using fuzzing tests for image parsing code.

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.