Repo Prompt Generator

Why learn this

Every AI coding agent — Claude Code, Codex CLI, Cursor, Windsurf — relies on a context file (CLAUDE.md, AGENTS.md, .cursorrules) to understand a project before making changes. Manually writing these files is tedious and error-prone. Automating the generation from GitHub metadata turns a 15-minute chore into a 2-second operation, and ensures every prompt captures the project's actual structure, not a stale description.

What you built and why this way

GitHub public API vs authenticated. Using api.github.com without auth is deliberately chosen to keep the tool zero-setup — anyone with a browser can use it. The tradeoff: unauthenticated requests are rate-limited to 60/hour per IP. For a client-side tool that serves many users, this is acceptable because each user has their own IP and the page caches results in-memory for the session. The Accept: application/vnd.github.v3+json header requests the default REST API v3 payload.

Three parallel API calls. The tool fires GET /repos/{owner}/{repo}, GET /repos/{owner}/{repo}/languages, and GET /repos/{owner}/{repo}/readme simultaneously via Promise.all(). This cuts total time to roughly the slowest single request (~200-600ms). The languages endpoint returns byte counts per language, which we normalize into percentages. The readme body is base64-encoded — atob() decodes it for description extraction.

Config file probing with fallback. After the main fetch, the tool probes for critical config files (package.json, requirements.txt, Cargo.toml, go.mod, Makefile, Dockerfile, etc.) via individual GET /repos/{owner}/{repo}/contents/{path} calls. Each probe is wrapped in a try-catch so a 404 on one file doesn't block the rest. The detected files inform build commands, test commands, and dependency lists in the generated prompt.

URL parsing flexibility. The parseGitHubUrl() regex accepts github.com/owner/repo, github.com/owner/repo.git, and github.com/owner/repo/tree/branch variants. The .git suffix and trailing path segments are stripped to get the clean owner/repo pair.

Key concepts

• Promise.all() — Fires multiple fetch() calls in parallel. One rejection rejects the whole group, so wrap fragile probes in individual try-catch
• atob() / btoa() — Base64 decode/encode in browsers. GitHub's contents API returns content as base64 with encoding: "base64"
• GitHub API X-RateLimit-Remaining header — Check via response.headers.get() to surface rate-limit warnings. Available on every API response
• GitHub's languages endpoint — Returns { "Python": 45000, "JavaScript": 12000 } — raw byte counts that we normalize to percentages

Alternative approaches

• Authenticated API — Passing a Authorization: token ghp_xxx header raises the rate limit to 5,000/hour and gives access to private repos. Tradeoff: users must paste a token, adding friction and security concerns
• Local git clone + analysis — Clone the repo and analyze it locally with file-system APIs. Unlimited analysis but adds clone time and disk usage. Good for a CLI tool, impractical for a web page
• GraphQL API — GitHub's GraphQL v4 endpoint lets you fetch repo metadata, languages, and README in a single query. More efficient but the query syntax is more complex. v3 REST is easier to debug and teach

Browser compatibility

• fetch() API: supported in all browsers since Chrome 42, Firefox 40, Safari 10.1. No polyfill needed for modern browsers
• Promise.all() and async/await: supported in Chrome 55+, Firefox 52+, Safari 10.1+. Transpile if targeting IE11
• atob(): supported in all browsers since IE10+. Handles ASCII and UTF-8 (use decodeURIComponent + escape for full Unicode)
• navigator.clipboard.writeText(): supported in Chrome 66+, Firefox 63+, Safari 13.1+. Falls back to execCommand('copy') for older browsers

Performance notes

• Three parallel API calls complete in ~200-600ms total on a typical connection. Config file probing adds ~100-400ms depending on how many files exist
• The generated prompt is constructed entirely in-memory — no DOM operations during the build phase. The textarea is updated in a single assignment
• GitHub API responses are cached in a Map keyed by owner/repo so re-generating with a different format preset doesn't re-fetch

Common pitfalls

• Rate limiting on shared IPs — Office/college networks share a single IP, so 60 requests/hour can be exhausted by multiple users. The tool detects X-RateLimit-Remaining: 0 and shows a clear message. Adding a personal access token field would resolve this
• Large README files — The README API returns up to 1MB of base64 content. Some READMEs contain embedded images as base64 data, making decoding slow. The tool caps README extraction to the first 500 characters
• Monorepo structure — A monorepo with a root package.json and ten workspace package.json files can overwhelm the config probe. The tool limits probing to root-level files only

Next up

Step 2 adds the prompt generation engine that transforms the fetched metadata into structured CLAUDE.md, AGENTS.md, and .cursorrules formats. Jump to Step 2 →

Why learn this

A well-structured agent prompt is the difference between an AI that "gets" your project and one that hallucinates its way through a codebase. Each format — CLAUDE.md, AGENTS.md, .cursorrules — has a distinct audience and convention. The generation engine maps the same raw metadata (repo name, description, languages, dependencies, build commands, project structure) into the right structure for each format, preserving the conventions that AI agents expect.

What you built and why this way

Three template functions, one data source. Instead of building three separate generation pipelines, the tool normalizes all fetched data into a single RepoData object then passes it to format-specific renderers: generateClaudeMD(), generateAgentsMD(), and generateCursorRules(). This keeps the data fetching logic decoupled from the presentation templates — adding a fourth format (e.g., .windsurfrules) is just one more function.

Build command inference vs explicit detection. Not every repo has a Makefile or scripts.build in package.json. The engine uses a heuristic pipeline: check package.json scripts, then Makefile targets, then Cargo.toml/ go.mod conventions, and finally falls back to language-typical commands (e.g., python -m pytest for Python repos). The fallback is surfaced with a "probable" label so the agent knows the command is inferred, not authoritative.

CLAUDE.md format (standard). Starts with a project overview and description, then a "## Commands" section with build/test/lint/run commands, then "## Tech Stack" with languages and key libraries, then "## Project Structure" with notable directories. Claude Desktop and Claude Code both read this format natively. The instruction block at the bottom tells Claude how to behave — concise responses, focus on current task, use existing patterns.

AGENTS.md format (agent-oriented). Mirrors the style used in the hermes-agent project and other agent frameworks. Adds "## Agent Memory" and "## Conventions" sections that give the agent explicit guidance on code style, commit messages, and architectural patterns. More verbose than CLAUDE.md but more prescriptive for autonomous agents that operate without human oversight.

.cursorrules format (YAML-like). Uses the conventions Cursor IDE expects — a YAML-like preamble with You are an expert in... followed by ## Tech Stack, ## Commands, and ## Rules sections. The rules section includes project-specific conventions expressed as "always" and "never" statements. Cursor injects this file into the system prompt context for every chat.

Key concepts

• Template literals — `string ${expression}` in JavaScript builds the prompt string with interpolated data. Each template function returns a plain string
• Heuristic inference — When explicit data is missing, the engine uses patterns like has("pytest") || has("unittest") => "pytest" to guess the test command. These are labeled as inferred so the user can verify
• Section ordering — Different agents prioritize different sections. Claude prefers commands first (most actionable), agents prefer conventions (most behavioral), Cursor prefers tech stack (most contextual)

Alternative approaches

• LLM-generated prompts — Send the raw repo data to an LLM and ask it to write the CLAUDE.md. More natural language but adds cost, latency, and unpredictability — the LLM might invent build commands or dependencies. Deterministic templates are safer for tool-generated files
• File-based template loading — Load .md templates from a server or git repo. More flexible for updating formats without redeploying the page. Tradeoff: adds a network dependency and latency to prompt generation
• User-customizable sections — Let users add/remove/reorder sections before copying. More flexible but adds UI complexity. The current three-preset approach covers the most common use cases

Browser compatibility

• Template literals (`${}`): supported in Chrome 41+, Firefox 34+, Safari 9+. No transpilation needed for modern browsers
• Array.map().join('') for list construction: supported in all browsers since IE9+. Combined with template literals for readable section generation
• Object.keys() and Object.entries(): entries() needs Chrome 54+, Firefox 47+, Safari 10.1+. keys() works everywhere

Performance notes

• Prompt generation is pure string manipulation — runs in ~0.1ms for a typical repo. The three format renderers share the same data object
• The prompt text is written to a <textarea> via value = ... — a single DOM write. No incremental rendering needed
• Format switching (CLAUDE.md → AGENTS.md) doesn't re-fetch data — the cached RepoData is re-rendered through the new template function

Common pitfalls

• Markdown collision in generated output — A project description containing characters like *, _, or # can break the generated markdown. The engine escapes these in inline positions but preserves them in code blocks
• Overlong prompts — A monorepo with 40 dependencies produces a very long CLAUDE.md. The engine caps dependency lists at 20 entries with a "and N more..." note. The full list is a readability vs completeness tradeoff
• Inferred commands that are wrong — The fallback heuristic guesses pytest for Python repos but the project might use unittest or nose. The "(inferred)" label alerts the user to verify before committing the file

Next up

Both steps complete! Try the interactive tool below to generate a prompt for any public GitHub repo.