GitStory is a small CLI tool that turns any Git repository (local path or GitHub URL) into an entertaining narrative using an LLM. It can generate cinematic retellings, Shakespearean monologues, anime-style epics, or even launch voice narration for the story.

This repo was bootstrapped with Bun and is intended as a compact hackathon project CodeCraze.

• Generate human-readable stories from a repo's commit history and messages.
• Multiple "styles": cinematic (default), shakespeare, anime, voice.
• Optional timeline view that highlights milestones and key commits.
• Voice narration mode that plays an audio narration and prints the text.

• Bun (tested with bun v1.2.21; newer versions should work)
• Internet access to call an LLM API or fetch a remote GitHub repo
• OpenRouter API key
• Create a .env file and add OPENROUTER_API_KEY=

1. Install dependencies:

bun install

2. Run against a GitHub repo or local path and pick a style:

# cinematic (default)
bun run src/cli.ts https://github.com/user/repo

# Shakespearean style
bun run src/cli.ts . --style shakespeare

# Anime style with timeline
bun run src/cli.ts /path/to/local/repo --style anime --timeline

# Voice narration mode (launches audio)
bun run src/cli.ts . --style voice

Options

• [repo] — GitHub URL or local path (default: .)
• --style —> Output style. Supported values: cinematic, shakespeare, anime, voice. Default: cinematic.
  • voice will launch audio narration and then print the story.
• --timeline — If provided, the CLI will also generate a commit timeline with milestones.

bun run src/cli.ts https://github.com/user/repo --style voice

bun run src/cli.ts https://github.com/user/repo --timeline

bun run src/cli.ts https://github.com/user/repo --style anime

bun run src/cli.ts https://github.com/user/repo --style shakespeare

1. The CLI analyzes the provided repo (local or remote), extracts commits and metadata.
2. It summarizes commits and groups milestones.
3. The summary is fed to an LLM prompt tailored to the selected style to produce a narrative.
4. If --style voice is used, the generated text is sent to the voice player which attempts to play narration.

• Entry point: src/cli.ts
• Key modules: src/story/generator.js (story generation) and src/voice/player.ts (voice playback).
• The CLI uses: commander (args), ora (spinner), boxen and chalk for styled console output.
• To test locally, run the CLI against small repositories to keep LLM payloads small.

• If the spinner never completes, check network connectivity (LLM or remote repo fetch).
• Voice mode depends on audio libraries and system audio; ensure Bun has permission to access audio devices.
• If a remote repo is used, ensure the URL is publicly accessible or provide credentials as needed (not currently implemented).

• This project is a Bun-based CLI. You can ship it as a Bun script or wrap it as an npm package if desired. For a hackathon demo, running with bun run src/cli.ts is sufficient.

GitStory turns the history of any codebase into a memorable story. For CodeCraze we present a playful CLI that summarizes the soul of a project—its ups, downs, and breakthroughs—into cinematic or stylized narratives, and optionally narrates it aloud. Great for intros, demos, or giving your repo a voice.

• Open issues and PRs are welcome. Keep changes focused and small.
• If adding new styles, add a corresponding prompt in src/story/generator.js.

• Add better tags
• Pacakage and publish as npm package.
• And more...

[MIT]

• Built with Bun and small open-source packages (commander, ora, boxen, chalk).
• LLM and audio backends are pluggable; credit openrouter.

Contact : DeadpoolX7