	Name
	.nsite
	docs
	public
	src
	.gitignore
	eslint.config.js
	index.html
	package-lock.json
	package.json
	README.md
	reference-ngit-relay
	tailwind.config.js
	tsconfig.app.json
	tsconfig.json
	tsconfig.node.json
	vite.config.ts

🌳 Treegaze

A modern, decentralized Git repository explorer powered by Nostr. Discover, browse, and interact with Git repositories shared over the Nostr network without relying on centralized platforms.

✨ Features

🌐 Decentralized Discovery

Browse repositories shared via Nostr network
Follow developers and discover their latest projects
Real-time updates through Nostr relay connections
No central authority - repositories are announced by their maintainers

📁 Repository Browsing

File tree navigation with familiar GitHub-like interface
Syntax highlighting for code files
README rendering with full Markdown support
Branch switching with all branches from repository state events
Breadcrumb navigation for easy directory traversal
Commit history with relative timestamps and full commit details
Interactive tooltips showing complete date/time information

🚀 One-Click Cloning

Browser-based cloning using isomorphic-git
Persistent storage with IndexedDB for offline access
Smart caching - repositories stay cloned between sessions
CORS proxy support for repositories with access restrictions

🔗 Nostr Integration

NIP-34 compliant - follows Nostr git repository specifications
Multi-relay support for improved reliability
State synchronization across repository maintainers
Extension-based login (nos2x, Alby) or private key import

🛠️ Technology Stack

Frontend: React 18 + TypeScript + Vite
Styling: Tailwind CSS with custom design system
Git Operations: isomorphic-git + LightningFS
Nostr: @nostr-dev-kit/ndk
Markdown: react-markdown + github-markdown-css
State Management: Zustand
Routing: React Router v6

🚀 Getting Started

Prerequisites

Node.js 18+ and npm
A Nostr extension (nos2x, Alby) or private key for authentication

Installation

Clone the repository
```
git clone <repository-url>
cd treegaze
```
Install dependencies
```
npm install
```
Start development server
```
npm run dev
```
Open in browser
```
http://localhost:5173
```

Production Build

npm run build
npm run preview

📖 How It Works

Repository Discovery

Announcements: Developers publish repository announcements (NIP-34) to Nostr relays
Discovery: The explorer fetches these announcements and displays available repositories
Following: Users can follow specific developers to see their repositories

Repository Access

State Events: Repository maintainers publish state events containing branch and commit information
Clone URLs: Repositories include clone URLs (HTTP/HTTPS) for fetching code
Browser Cloning: The app clones repositories directly in the browser using isomorphic-git

Data Flow

Nostr Relays → Repository Announcements → Repository List
     ↓
Repository State Events → Branch Information → File Tree
     ↓
Clone URLs → Browser Git Client → Local Storage → File Browsing

🏗️ Architecture

Core Components

NostrManager: Handles all Nostr protocol interactions
GitManager: Manages git operations and repository storage
AppStore: Zustand-based global state management
RepositoryView: Main repository browsing interface

Key Features Implementation

Consistent Navigation

URL-based routing ensures direct links work correctly
State synchronization between URL params and global store
Filesystem detection identifies previously cloned repositories

Smart Caching

Memory cache for active session performance
Persistent storage in IndexedDB for cross-session access
Automatic discovery of existing repositories on page load

Branch Management

State event parsing extracts branch information from Nostr
Real-time updates when maintainers publish new states
Multi-maintainer support aggregates information from all contributors

🔧 Configuration

Default Relays

[
  'wss://relay.damus.io',
  'wss://nos.lol', 
  'wss://relay.snort.social',
  'wss://relay.primal.net'
]

Custom Relay Configuration

Users can configure custom relays through the settings interface for connecting to specific Nostr networks.

🛡️ Security & Privacy

No central server - runs entirely in the browser
Local storage only - repositories are stored locally in IndexedDB
Relay diversity - connects to multiple relays for redundancy
Extension-based auth - uses existing Nostr browser extensions when available

🤝 Contributing

Development Setup

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and test thoroughly
Commit with descriptive messages: git commit -m 'Add amazing feature'
Push to your branch: git push origin feature/amazing-feature
Open a Pull Request

Code Style

TypeScript for type safety
ESLint + Prettier for code formatting
Component-based architecture with clear separation of concerns
Descriptive naming and comprehensive comments

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Nostr Protocol - For enabling decentralized communication
NIP-34 - Git repository specification for Nostr
isomorphic-git - For browser-based git operations
Nostr development community - For tools and specifications

🐛 Issues & Support

Bug reports: Please use the GitHub Issues tab
Feature requests: Open an issue with the "enhancement" label
Questions: Join the Nostr developer community discussions

Built with ❤️ for the decentralized future

Explore code without boundaries. No servers, no gatekeepers, just pure peer-to-peer repository sharing.

README.md