Turn a transparent portrait and structured profile data into a responsive, animated GitHub Profile README.

This is an opinionated starter kit, not a loose prompt. It provides the layout, portrait renderer, responsive SVG animation, configuration schema, setup wizard, README generator, validation, and optional recent-activity automation.

You need a GitHub account, Git, Node.js 20 or newer, and a head-to-torso PNG with a transparent background. The setup runs locally on macOS, Linux, or Windows.

• An animated ASCII portrait generated from your transparent PNG.
• Separate desktop/mobile and dark/light SVG assets.
• A professional README with About, Focus, Projects, Research Direction, and Tech Stack sections.
• Hash-based asset filenames so GitHub does not keep an outdated cached image.
• An optional daily activity block that only edits its own markers.
• A private-input workflow: your original portrait is never copied into the repository.

Click Use this template above, select Create a new repository, and use these settings:

• Owner: your personal GitHub account
• Repository name: exactly your GitHub username
• Visibility: Public

GitHub username: octocat
Repository name: octocat
Repository URL:  github.com/octocat/octocat

GitHub only displays a Profile README when the repository owner and repository name match. Do not clone this starter repository directly for your profile; create your own repository from the template first.

Clone the profile repository you just created. For example, if your username is octocat:

git clone https://github.com/octocat/octocat.git
cd octocat
npm ci

Replace every octocat in the example with your own GitHub username. Run the commands from Terminal, PowerShell, or the integrated terminal in your code editor.

Use a head-to-torso PNG with a transparent background. Keep the source file outside the repository when possible, for example ~/Pictures/profile-transparent.png. The generator reads it locally and does not copy it into your repository.

Guided CLI:

npm run setup

The wizard asks for your public profile information and the absolute path to your portrait, then generates the hero assets and replaces this starter README with your profile README.

AI coding agent: after installing the dependencies, open PROMPT.md, attach your portrait path, and ask Codex, Claude Code, or another coding agent to follow it.

npm run check
git status --short

Open the four generated SVG files in assets/hero/ and check the desktop/mobile variants in both dark and light mode. Confirm that your project links are correct and that the original portrait is not listed by git status.

git add README.md profile.config.json assets/hero
git commit -m "feat: create my GitHub profile"
git push origin main

Your profile should appear at https://github.com/YOUR_USERNAME shortly after the push.

If GitHub asks you to approve workflows created from a template, open the repository's Actions tab and enable them. The optional activity workflow only runs when the repository name matches its owner.

For a slower walkthrough, read Quick Start.

Both paths produce the same deterministic assets. The AI agent is used for judgment and writing, not for inventing a different rendering system.

All public profile content lives in profile.config.json. The included profile.schema.json provides editor hints and documents valid values.

{
  "profile": {
    "name": "Your Name",
    "username": "yourusername",
    "headline": "AI Engineer & Product Builder"
  },
  "appearance": {
    "palette": "signal"
  }
}

Available palettes are signal, ocean, and solar. See Customization before changing layout code.

transparent portrait
        ↓
alpha validation and automatic trim
        ↓
grayscale sampling and edge-aware ASCII conversion
        ↓
responsive animated SVGs
        ↓
manifest + generated Profile README

The rendering happens locally through sharp. No portrait is uploaded to an image service.

.
├── profile.config.json       # Public profile content
├── profile.schema.json       # Configuration contract
├── PROMPT.md                 # AI-agent personalization workflow
├── assets/hero/              # Generated SVGs and manifest
├── docs/                     # Instructions preserved after README generation
├── scripts/                  # Setup, rendering, README, activity, validation
└── .github/workflows/        # Validation and optional activity automation

The source portrait is intentionally excluded from generated output. Common source filenames and the input/ directory are ignored by Git. Always inspect git status before committing. Read Privacy for the full checklist.

Most issues are caused by a non-transparent image, a repository with the wrong name, overly long hero labels, or old GitHub image cache. Start with Troubleshooting.

Created by Wildan Syukri Niam. The original design was developed for an AI Researcher and Web3 Builder profile, then rebuilt as a configurable public starter kit.

MIT. You can use, modify, and publish your generated profile. A star or attribution is appreciated, but not required.