Code Archaeologist

Every repository has a story. Unearth it.

Code Archaeologist is a developer tool that turns a public GitHub repository into a readable orientation brief. It is designed for the moment you open an unfamiliar codebase and need to understand its shape before you start reading code.

What it does

• Fetches live public GitHub repository metadata and language data.
• Maps the visible top-level repository structure.
• Detects technology, package-management, CI, container, test, and monorepo clues from repository files.
• Creates an automated Repository Story from evidence in the live repository.
• Calculates a transparent health score from activity, documentation, licensing, automation, tests, and community interest.
• Suggests a practical first step for exploring the codebase.
• Includes guided questions for beginning, architecture, running, and repository health.

The Repository Story and guided answers are currently rule-based, evidence-driven summaries. They do not claim to understand code they have not read, and they do not require an API key.

Live demo

The public website is published with GitHub Pages at tam2vec.github.io/Code-Archaeologist.

Run locally

You need Node.js 18 or newer.

git clone https://github.com/tam2vec/Code-Archaeologist.git
cd Code-Archaeologist/server
npm install
npm start

Open http://localhost:3000. The Express server serves both the interface and API.

To run the analyzer check:

npm test

Deploy free with GitHub Pages

The repository includes a GitHub Actions workflow that publishes the frontend folder to GitHub Pages. It works for public repositories on GitHub Free.

1. In the GitHub repository, open Settings → Pages.
2. Under Build and deployment, choose GitHub Actions as the source.
3. Push changes to main; GitHub publishes the site automatically.

The deployed version calls GitHub's public API directly in the browser. Private repositories are not supported, and GitHub can temporarily limit very heavy use.

Project structure

frontend/                 Interface and dashboard rendering
server/server.js          API routes and server setup
server/services/github.js GitHub API client and URL validation
server/services/analyzer.js Evidence-driven repository analysis

Constraints

The app analyses public GitHub repositories. GitHub’s unauthenticated API rate limit can temporarily limit heavy use. A future version can add optional authenticated requests and an LLM-backed follow-up question feature.