SilentForge

Transform public GitHub repositories into portable, evidence-backed static presentation sites.

SilentForge reads README content, metadata, file trees, releases, and lightweight code signals, then emits self-contained HTML you can preview, zip, and deploy anywhere. Install from npm (npm install -g silentforge) or run instantly with npx silentforge. Use the reposite / silentforge CLI for one-shot generation, or the local Workbench for interactive preview and GitHub Pages deployment.

The pipeline is deterministic and source-bound—no fabricated sections. Optional Codex (preferred) or OpenAI planning can reorder chapters, but every claim traces back to extracted repository data.

中文文档 · Live demo — scroll-story site auto-built from this README on every push to main

Screenshots

Workbench	Preview & export	Deploy
Paste a repo URL, tune output settings, and generate locally.	Stream generation steps, inspect diagnostics, preview the site, download ZIP.	Copy a GitHub Pages workflow and publish from your repository.

Overview

SilentForge targets teams and maintainers who need a credible, offline-capable project narrative without standing up a docs platform or hand-authoring a landing page from scratch.

Surface	Role
`reposite init`	One-shot CLI generation to a local directory
Workbench	Local web UI with live job stream, diagnostics, preview, and ZIP export
Generated site	Plain HTML / CSS / JS / JSON—editable and hostable anywhere

Both entry points share the same generation engine, so Preview, ZIP download, and CLI output are structurally identical.

A typical generated site includes a hero, features, visuals, usage commands, README deep-dives, tech stack, architecture diagram, and resource links. Browse the live demo to see this repository rendered end-to-end.

Quick start

Requires Node.js 20+. Pick one install path:

Path	When to use
`npx silentforge`	Try once—no install
`npm install -g silentforge`	Use `reposite` / `silentforge` daily
Build from source	Contribute or run unreleased commits

# Generate a static presentation site (npx — no install)
npx silentforge init vercel/next.js
# Open the generated index.html (macOS example)
open vercel/next.js-site/index.html
# Launch the local Workbench UI
npx silentforge web

Optional local preview after generation:

npx --yes serve "vercel/next.js-site"

Usage

Typical workflows after Quick start:

# CLI — generate to a folder and open locally
npx silentforge init owner/repo
open owner/repo-site/index.html # macOS; adjust path on Linux/Windows# Workbench — interactive preview, diagnostics, ZIP, deploy guide
npx silentforge web
# → http://127.0.0.1:4177/# Custom output directory and locale
npx silentforge init owner/repo -o my-site --locale zh
# Optional AI-assisted chapter ordering (Codex login preferred; OPENAI_API_KEY as fallback)
codex login # once, if using local Codex
npx silentforge init owner/repo --ai
OPENAI_API_KEY=sk-… npx silentforge init owner/repo --ai

Publish to GitHub Pages: generate in Workbench, open Deploy, copy the workflow YAML into .github/workflows/silentforge-pages.yml, enable Settings → Pages → GitHub Actions, then push to main. See Deploy to GitHub Pages.

Examples

Try SilentForge on well-documented public repositories:

Repository	Best for	Command
openai/openai-node	Developer deck (install + usage)	`npx silentforge init openai/openai-node`
vercel/next.js	Architecture signals in a large monorepo	`npx silentforge init vercel/next.js`
tailwindlabs/tailwindcss	Visual README content	`npx silentforge init tailwindlabs/tailwindcss`
axios/axios	Compact library narrative	`npx silentforge init axios/axios`
microsoft/playwright	Docs-heavy project with releases	`npx silentforge init microsoft/playwright`

See examples/README.md for more detail.

Live demo:SilentForge on GitHub Pages — live and auto-updated from this repository on every push to main (workflow). Open it to preview scroll-story chapters, extracted commands, and architecture signals before deploying your own repo.

How it works

flowchart LR
input[GitHub repository URL]
fetch[Fetch snapshot]
parse[Parse README and metadata]
analyze[Analyze codebase signals]
plan[Build presentation plan]
render[Render static site]
output[HTML CSS JS JSON ZIP]
input --> fetch --> parse --> analyze --> plan --> render --> output

Ingest — Resolve owner/repo, fetch repository metadata, README, releases, and file tree via the GitHub API.
Extract — Parse README structure (features, install, usage, FAQ, screenshots, sections) and derive a lightweight code wiki (stack, entry files, configs, module map, Mermaid diagram).
Diagnose — Score repository readiness and surface gaps before publication.
Plan — Select presentation mode, theme, and chapters (rule-based by default; optional Codex or OpenAI with schema validation).
Emit — Write a self-contained static site with scroll-story navigation, detail pages, and bundled Mermaid runtime (no CDN dependency).

Features

Scroll-story presentation sites — sticky chapter navigation, detail routes, three themes (Dark Signal, Editorial Light, Blueprint), five narrative modes or auto-selection from repository signals
Code wiki — detected stack, entry files, config signals, directory summaries, module map, and offline Mermaid architecture diagram
Repository diagnostics — readiness score with strengths, gaps, and recommendations in Workbench Overview
Local Workbench — paste a URL, stream generation over SSE, inspect Overview / Resources / Code Wiki / Preview, download ZIP, copy GitHub Pages workflow from Deploy; Settings dialog for mode, theme, chapters, and Codex-first AI
Source-bound output — plain HTML, CSS, JS, and JSON; no consumer build step; Preview and ZIP share identical files
Internationalization — Workbench and generated site chrome in EN / 中文; repository facts stay as extracted from the source repo

Requirements

Requirement	Notes
Node.js 20+	Required for CLI and Workbench
Public GitHub repository	`https://github.com/owner/repo` or `owner/repo` shorthand
`GITHUB_TOKEN`	Optional; recommended for higher API rate limits (CLI env var or Workbench UI)
`codex login`	Optional; preferred AI backend for `--ai` when Codex CLI is installed and logged in
`OPENAI_API_KEY`	Optional fallback for AI-assisted presentation planning (`--ai` or Workbench checkbox)
`OPENAI_BASE_URL`	Optional OpenAI-compatible endpoint (e.g. gpt2cursor bridge) when using `OPENAI_API_KEY`

Installation and distribution

npm (recommended)

Published on npm as silentforge. Requires Node.js 20+.

# One-shot generation (no install)
npx silentforge init owner/repo
# Workbench UI
npx silentforge web
# Global install — adds reposite + silentforge to your PATH
npm install -g silentforge
reposite init owner/repo
reposite web
# Project-local install (optional)
npm install silentforge
npx silentforge init owner/repo

npm install -g fails with EACCES? On macOS/Linux, npm may lack permission to write symlinks under /usr/local/bin. Use npx silentforge instead, or see Global install permission errors below.

The reposite and silentforge commands both point to the same CLI entrypoint declared in package.json:

"bin": { "reposite": "./dist/cli.js", "silentforge": "./dist/cli.js" }

Build from source

git clone https://github.com/ingeniousfrog/SilentForge.git
cd SilentForge
npm install
npm run build

Run without installing the global command:

# One-shot site generation
node dist/cli.js init openai/openai-node
# Workbench (compiled)
node dist/cli.js web
# Developer loop (TypeScript directly via tsx)
npm run dev -- init openai/openai-node
npm run web

Install reposite onto your PATH:

npm link # from the repo root after npm run build
reposite --help
reposite init openai/openai-node
reposite web

Alternatively, after npm run build:

npm install -g .

Desktop packaging (DMG / EXE)

Native installers are planned. Until then, distribution is build-from-source or npm link / global install as above. A packaged app will bundle the compiled dist/ output and launch reposite web locally—no separate Node install required on the user's machine.

Verify the install

reposite --help
reposite web
# open http://127.0.0.1:4177/

Open <output-dir>/index.html after reposite init, or serve the folder with any static file server.

Deploy to GitHub Pages

SilentForge publishes a static presentation site generated from the target repository itself—README, metadata, file tree, and code signals—not a hand-written marketing page. The Live demo is this product applied to this repository.

One-time prerequisite (every repository)

GitHub requires a manual Pages enablement before the first Actions deploy can succeed:

Open your repository Settings → Pages → Build and deployment.
Set Source to GitHub Actions (not "Deploy from a branch").
Save.

Skipping step 2 causes the workflow to fail at configure-pages with Get Pages site failed, or the deploy job to return status 404. After enabling Pages, open Actions, select Deploy SilentForge presentation site, and Re-run failed jobs (or Run workflow).

SilentForge demo site (this repo)

Live now:https://ingeniousfrog.github.io/SilentForge/

.github/workflows/silentforge-pages.yml is already committed. On every push to main it:

Checks out the repo and runs npm ci && npm run build.
Generates a presentation site for ${{ github.repository }} into site/.
Publishes site/ to GitHub Pages.

First-time setup (only if you fork or clone into a fresh repo without Pages enabled):

Enable Pages: Settings → Pages → Source: GitHub Actions.
Run Deploy SilentForge presentation site from Actions.

After the first successful deploy, future pushes to main regenerate and republish automatically.

Any other repository

Complete the one-time prerequisite above.
Copy .github/workflows/silentforge-pages.yml into your repo—or generate locally in Workbench, open Deploy, and copy the workflow YAML.
Push to main or run the workflow manually from Actions.

Other repos use the Workbench Deploy workflow template with npx --yes silentforge@latest init ${{ github.repository }} -o site --locale en (requires silentforge >= 0.1.1 on npm). This repository builds from its own source with npm ci && npm run build so CI always matches the latest commit.

Expected URL pattern: https://<user>.github.io/<repo>/ (organization repos use the same path shape).

After Pages is live, add a README badge (also available from Workbench Overview):

[![Presentation site](https://img.shields.io/badge/Presentation-SilentForge-6366f1?style=for-the-badge)](https://YOUR_USER.github.io/YOUR_REPO/)

GitHub authentication (optional)

SilentForge reads public repository data through the GitHub REST API (metadata, README, releases, file tree). Authentication is optional but recommended: unauthenticated requests share a low hourly limit (~60/hour/IP); an authenticated token raises the limit substantially (~5,000/hour).

The token is used only when calling api.github.com. It is never sent to OpenAI or any other third party.

Method	Where	How
Workbench UI	Browser → your local Workbench server	Expand GitHub access (optional), paste a personal access token, optionally check Remember on this device
`GITHUB_TOKEN` env var	CLI and Workbench server fallback	`export GITHUB_TOKEN=ghp_…` before `reposite init` or `reposite web`
`--token` flag	CLI only	`reposite init owner/repo --token ghp_…`

Workbench behavior:

Token is submitted with the generation job to your local server (POST /api/jobs).
It is kept in memory for that job only and is not returned by job status APIs.
If Remember on this device is checked, the token is stored in browser localStorage (silentforge.githubToken) for convenience—useful for personal machines and future desktop builds.
If the UI field is empty, the server falls back to process.env.GITHUB_TOKEN (set when you started Workbench).

For public repositories, a classic PAT with default public read access is sufficient. Fine-grained tokens need Contents: Read-only (and Metadata: Read-only) on the target repository.

Workbench

Start the local Workbench from source:

npm run web

Open http://127.0.0.1:4177/

Custom host or port:

npm run web -- --host 127.0.0.1 --port 4188

Run against the compiled CLI entrypoint:

npm run build && npm run web:dist

Workflow

Appearance — Toggle Dark / Light in the header (defaults to system preference; persisted as silentforge.uiTheme after manual selection).
Locale — Switch EN / 中文 (persisted as silentforge.locale; affects Workbench copy and the next generation job).
GitHub token (optional) — Expand GitHub access (optional) if you hit rate limits or generate frequently. Token stays on your machine; see GitHub authentication.
Settings — Open the Settings dialog to configure output mode, theme, chapters, and optional AI-assisted structure (Codex status badge, OpenAI key/base URL for the server-side job). Settings are saved when you click Generate.
Target — Paste a public GitHub URL or owner/repo shorthand and click Generate.
Inspect — Follow the generation stream; review Overview, Resources, Code Wiki, and Preview (opens automatically on completion).
Export — Download the ZIP from the tab bar, open Deploy for GitHub Pages steps, or use Back to home to start a new target.

Output settings

Workbench Settings → Output settings control the generated site only—not the Workbench shell:

Control	Effect
Mode	Narrative structure (`auto`, developer deck, architecture map, visual showcase, compact story)
Theme	Generated page palette (`auto`, Dark Signal, Editorial Light, Blueprint)
Chapters	Include or omit section types when matching repository content exists

Optional AI-assisted structure arranges extracted repository data with local Codex when logged in, otherwise with OpenAI when OPENAI_API_KEY is set. Facts remain source-bound; the pipeline falls back to local rules on failure or validation errors.

CLI reference

`reposite init <github-repo-url>`

Generate a static presentation site from a repository.

reposite init https://github.com/openai/openai-node
reposite init openai/openai-node

Option	Description
`-o, --output <dir>`	Output directory (default: `<repo-name>-site`)
`--ai`	Enable AI-assisted structure (Codex first when logged in, OpenAI env fallback, then local rules)
`--mode <mode>`	`auto`, `developer-deck`, `architecture-map`, `visual-showcase`, `compact-story`
`--theme <theme>`	`auto`, `signal-dark`, `editorial-light`, `blueprint`
`--chapters <kinds>`	Comma-separated chapter kinds (see Presentation modes and themes)
`--locale <locale>`	Generated site UI language: `en` (default) or `zh`
`--token <token>`	GitHub token (falls back to `GITHUB_TOKEN`)

Examples:

# AI-assisted planning (Codex preferred after `codex login`)
reposite init openai/openai-node --ai
# OpenAI API fallback
OPENAI_API_KEY=your_key reposite init openai/openai-node --ai
# gpt2cursor-compatible bridge
OPENAI_BASE_URL=http://127.0.0.1:8787/v1 OPENAI_API_KEY=g2c_… reposite init openai/openai-node --ai
# Explicit presentation options
reposite init openai/openai-node \
--mode developer-deck \
--theme signal-dark \
--chapters features,usage,architecture \
--locale zh \
--token "$GITHUB_TOKEN"

`reposite web`

Run the local Workbench server.

reposite web
reposite web --host 127.0.0.1 --port 4177

Generated output

reposite init writes a self-contained directory:

Path	Purpose
`index.html`	Scroll-story entry with sticky chapter navigation
`assets/site.css`	Theme-aware presentation styles
`assets/site.js`	Chapter navigation, progress tracking, Mermaid bootstrap
`assets/mermaid.js`	Bundled Mermaid runtime (offline-capable)
`details/*.html`	Installation, usage, architecture, releases, README detail pages
`data/site.json`	Structured repository model and final presentation plan
`README.md`	Brief note on opening or deploying the generated site

Content sources (never fabricated):

README: title, summary, features, install/usage, FAQ, screenshots, links, long-form sections
GitHub metadata: stars, topics, license, releases, default branch, language, homepage
Code wiki: project structure, stack detection, entry files, config files, module map, Mermaid diagram
Readiness diagnostics (also visible in Workbench Overview)

Presentation modes and themes

Modes

Mode	Best for
`auto`	Let SilentForge infer structure from README, screenshots, and codebase signals
`developer-deck`	API/library projects with install and usage emphasis
`architecture-map`	Systems with strong structural or module signals
`visual-showcase`	Projects with screenshots and visual README content
`compact-story`	Minimal narrative for small or early-stage repositories

Generated-site themes

Theme ID	Label	Character
`signal-dark`	Dark Signal	Default dark developer-tool palette
`editorial-light`	Editorial Light	Light editorial layout with serif headings
`blueprint`	Blueprint	Engineering grid background

Set via Workbench Output settings or --theme on the CLI. auto follows the selected presentation mode.

Chapter kinds

features, visuals, usage, readme-insights, technology, architecture, resources

The hero chapter is always included. Enabled chapters without matching repository content are omitted.

Internationalization

Surface	Localized?	Mechanism
Workbench UI	Yes — EN / 中文	Header locale capsule (`silentforge.locale`)
Workbench appearance	Yes — Dark / Light	Header theme capsule (`silentforge.uiTheme`; system default until overridden)
Generated site chrome	Yes — nav, labels, footers, diagnostics	`--locale` / Workbench locale at generation time
README and repository facts	No	Always shown as extracted from the source repository

Switching Workbench locale does not retroactively translate past job events; it affects the UI and the next generation run.

Environment variables

Variable	Purpose
`GITHUB_TOKEN`	GitHub API authentication when the Workbench UI token field is empty, or for CLI runs without `--token`
`CODEX_PATH`	Optional path to the Codex CLI binary
`CODEX_MODEL`	Optional Codex model override (`-m`)
`OPENAI_API_KEY`	Optional AI presentation planning fallback (`--ai` or Workbench checkbox)
`OPENAI_BASE_URL`	Optional OpenAI-compatible endpoint (e.g. gpt2cursor bridge)
`OPENAI_MODEL`	Override OpenAI/Codex model (default: `gpt-5.5`)
`SILENTFORGE_AI_TIMEOUT_MS`	AI planning timeout in milliseconds (default: `60000` for Codex, `15000` for OpenAI API)

Copy .env.example for a commented starter template. On Windows, local Codex via PTY requires node-pty; macOS/Linux can fall back to the script command when PTY is unavailable.

Workbench-local preferences (browser localStorage, not environment variables): silentforge.locale, silentforge.uiTheme, silentforge.githubToken (when "Remember on this device" is enabled).

Design guarantees

Principle	Behavior
Source-bound	Claims trace to extracted repository data
No filler	Empty sections are omitted, not padded with placeholders
Editable artifacts	Plain HTML, CSS, JavaScript, and JSON—no proprietary runtime
Single artifact path	Preview, ZIP, and CLI output share identical files
Local-first	CLI and Workbench run on your machine; GitHub Pages is an optional publish target
Graceful AI fallback	Rule-based planning when Codex/OpenAI is unavailable or validation fails

FAQ

Do I need a GitHub token?

No for occasional public repos. A personal access token helps when you hit API rate limits (~60 requests/hour unauthenticated vs ~5,000/hour authenticated).

Global install permission errors (`EACCES`)

If npm install -g silentforge fails with EACCES: permission denied, symlink ... -> /usr/local/bin/reposite, npm cannot write global bin links to a system directory. This is common on macOS—not a SilentForge bug.

Easiest: skip global install and use npx silentforge init … or npx silentforge web (Quick start).

Recommended for daily use: point npm’s global prefix to a directory you own:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
# add to ~/.zshrc or ~/.bashrc:export PATH="$HOME/.npm-global/bin:$PATH"

Then run npm install -g silentforge again. Using nvm, fnm, or volta also avoids /usr/local permission issues.

Avoid sudo npm install -g unless you understand the ownership trade-offs.

Is the Live demo the official SilentForge website?

No—it is a generated presentation site built from this repository by SilentForge itself. Use it to preview output quality and chapter layout, not as a separate marketing site. Forks or fresh clones still need the one-time Pages setup.

Can I deploy to hosts other than GitHub Pages?

Yes. Download the ZIP or upload the output folder to Vercel, Cloudflare Pages, Netlify, or any static host. Workbench Deploy includes copy-paste commands.

Does SilentForge work on private repositories?

The current release targets public repositories. Private repo support is planned.

Will SilentForge invent features not in my README?

No. Sections without repository evidence are omitted. Optional AI may reorder chapters but must cite extracted signals; failures fall back to local rules.

Development

npm test# unit tests
npm run test:coverage # coverage report
npm run dev -- init owner/repo # CLI via tsx
npm run web # Workbench via tsx

Project layout (selected):

src/
analyzer/ Codebase signal extraction
commands/ CLI init command
github/ Repository snapshot fetching
i18n/ EN / zh message catalogs
presentation/ Planning (rules + optional Codex/OpenAI)
readme/ README parsing
site/ Static site generation
workbench/ Local server, job store, UI

License

Apache-2.0 — see LICENSE.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs/screenshots		docs/screenshots
examples		examples
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README-CN.md		README-CN.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Latest commit

History

Folders and files

Repository files navigation