SourceHub

A single-operator, self-hosted software forge with native Git Desktop source control, local CI actions runner, and an autonomous AI coding agent — running entirely on your own hardware.

📖 Overview

SourceHub turns any directory of local git repositories (default: ~/Dev) into a comprehensive, high-performance development forge served on your machine (localhost by default; LAN only if you intentionally rebind).

Designed specifically for solo developers, single operators, and agentic AI pair programming, SourceHub replaces both GitHub and GitHub Desktop without relying on external cloud infrastructure, subscriptions, or telemetry:

🖥️ Full Source Control Workbench — Hunk-level staging, discard, auto-fill commits, undo commit, stash management, branch switching, and remote sync.
Autonomous AI Coding Agent ("Helper") — Async task execution using local Ollama models. The agent snapshots the repository, ranks relevant files, writes code in an isolated git worktree, commits changes with audit trailers, opens PRs, runs reviews, and even addresses review comments automatically.
🔀 Pull Requests & Code Review — Full PR lifecycle backed by Node's built-in SQLite, featuring pre-flight merge conflict detection, squash/rebase/merge strategies, CI check gating, post-merge issue auto-closing, and branch pruning.
⚡ Local Actions CI Runner — Executes .sourcehub/workflows/*.yml locally with live step-by-step logs, status indicators, and duration tracking.
📋 Issue Tracker — Built-in issue lifecycle with one-click "Assign to Agent" handoff.
🌐 Git Smart HTTP Wire Protocol — Built-in Smart HTTP server allows standard git clone http://<host>:5177/git/<repo>.git over localhost and LAN.
🔒 Secrets, Keys & Webhooks — Encrypted repository/global secrets vault, SSH user & deploy keys registry, hashed Personal Access Tokens (enforced), optional SOURCEHUB_TOKEN shared secret for LAN, and outbound webhooks with optional HMAC signing and live ping testing.
🎨 14 Themes & Profile Customization — Matrix Neon (default), Cyber Amber, Tokyo Night, Dracula, OLED Black, and more, alongside persistent operator profile settings stored in SQLite.
🚀 Zero Web Framework Overhead — Powered by Node 22+ built-in node:http and node:sqlite, eliminating bloated web frameworks and native C++ binary dependencies.

Screenshots

1 — The Hook · Helper agent

Prompt a coding task, pick a local Ollama model, and watch the run move through Queued → Ready with an audit trail.

2 — The Classic Workflow · Desktop

Hunk staging, live diffs, and commit/push for day-to-day source control.

3 — The Proof · Pull requests

Full PR lifecycle on the local forge — merge strategies, CI gating, and Smart HTTP-backed repos.

⚡ Architecture

┌────────────────────────────────────────────────────────────────────────┐
│                               Surfaces                                 │
│    Web Browser (LAN / Local)  │  Desktop App Launcher  │  Git CLI      │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ HTTP / REST / Git Smart HTTP
┌───────────────────────────────────▼────────────────────────────────────┐
│                    SourceHub Standalone Daemon                         │
│  Native Node 22+ HTTP Server (node:http)  │  No Express / No Fastify   │
├────────────────────────────────────────────────────────────────────────┤
│  • Git Service (Native CLI runner)        • Working Copy Status        │
│  • Hunk Staging / Apply Patch Engine      • Smart HTTP (Upload Pack)   │
│  • Pull Request & Merge Pre-flight        • Local Actions CI Runner    │
│  • AI Helper Service (Ollama Worktrees)   • Outbound Webhook Dispatch  │
├────────────────────────────────────────────────────────────────────────┤
│                      Storage & Execution Layer                         │
│  • Built-in SQLite (node:sqlite)  → ~/.sourcehub/sourcehub.db          │
│  • Repositories Directory         → ~/Dev/*                            │
│  • Isolated Agent Worktrees       → ~/.sourcehub/worktrees/*           │
│  • Local Ollama Daemon            → http://localhost:11434             │
└────────────────────────────────────────────────────────────────────────┘

✨ Features in Detail

🖥️ Desktop (Source Control Workbench)

Live Status Monitoring: Tracks modified, added, deleted, renamed, and untracked files with ahead/behind commit indicators and upstream tracking.
Hunk-Level Staging: Interactive unified diff view allowing staging or unstaging of individual hunks via native git apply --cached.
Auto-Fill Commit Fields: Generates concise, conventional commit summaries and descriptions by analyzing staged diffs.
Safe Operations: Discard changes per file, selection, or all working changes at once; undo last commit (git reset --soft HEAD~1).
Branch Management: Quick branch switcher, new branch modal with base branch selection, and active branch deletion protection.
Stash Drawer: Save working state to stash with custom messages, pop, apply, or drop stashes.
Remote Synchronization: Manage multiple remotes (add, edit, remove), fetch, pull, and push with automatic upstream tracking setup, plus assisted GitHub remote integration.

AI Agent — Helper

Helper is an asynchronous repository agent designed for autonomous code development:

Context Snapshotting & File Ranking: Rather than naive full-repo dumps, SourceHub uses semantic scoring to prioritize and rank relevant tracked files alongside branch diffs, tree structure, and commit history.
Isolated Worktrees: The agent performs all edits inside dedicated git worktrees (~/.sourcehub/worktrees/<run-id>), preventing interference with your active workspace.
Robust Code Parsing: Parses both structured multi-file blocks (<<<FILE: path>>>...<<<END_FILE>>>) and standard markdown headers.
Audit Trailers: Commits are authored using your operator identity with a transparent audit trailer: SourceHub-Agent-Run: <run-id>.
PR Lifecycle Integration:
- Autonomous PR Creation: Opens a PR with AI-generated titles and descriptions.
- Automated PR Review: Performs line-by-line automated code review on PR diffs.
- Address Review Comments: The agent reads reviewer feedback, checks out the branch, implements the requested changes, commits them, and replies to comment threads.
Ollama Integration: Seamless model discovery from localhost:11434 or custom endpoints, pre-configured for models like glm-5.3-flash:cloud, llama3, deepseek-coder, qwen, and more.

🔀 Pull Requests & Code Review

Rich Diff Viewer: Side-by-side and unified diff views with syntax highlighting.
Pre-Flight Conflict Engine: Checks mergeability against target branches in real time before attempting a merge.
3 Merge Strategies: Support for Squash and Merge, Rebase and Merge, and Create a Merge Commit.
CI Check Gating: Protects target branches by requiring passing Actions CI runs prior to merge.
Post-Merge Automation: Automatically closes linked issues (e.g., #1, Closes #4) and prunes deleted feature branches.
Line & File Comments: Real conversation threads on pull requests.

⚡ Local Actions (CI Runner)

Declarative Workflows: Reads workflow definitions from .sourcehub/workflows/*.yml.
Real Local Execution: Runs workflow run: steps as shell commands on the host user — treat workflow YAML as trusted code.
Audit & History: Real-time log capture, exit code recording, execution timestamps, and run durations.
Event Triggers: Dispatches automatically on push, pull_request, agent_run, or manual UI dispatch.

🌐 Git Smart HTTP Wire Protocol

Clone and fetch directly with standard Git CLI tools:

# Loopback (no SOURCEHUB_TOKEN): unauthenticated local use
git clone http://localhost:5177/git/my-repo.git

# LAN / shared secret: pass token via HTTP Basic (password field) or configure git credential helper.
# Preferred: Authorization Bearer / X-SourceHub-Token on API; for git CLI use:
git -c http.extraHeader="Authorization: Bearer $SOURCEHUB_TOKEN" clone http://<lan-ip>:5177/git/my-repo.git
# or with a PAT:
git -c http.extraHeader="Authorization: Bearer sh_pat_…" clone http://<lan-ip>:5177/git/my-repo.git

Dynamic LAN IP detection displayed in the repository clone drawer when the server is reachable on the LAN.

🔒 Security, Keys & Webhooks

Encrypted Secrets Vault: Store repository-scoped and global secrets with masked values for CI and agent workflows.
Keys Management: Register and manage SSH user keys and deploy keys (fingerprints stored for display).
Operator Shared Secret (SOURCEHUB_TOKEN): When set, required for all /api/* and /git/* requests via Authorization: Bearer <token> or X-SourceHub-Token: <token>. Binding non-loopback (0.0.0.0 / LAN IP) without this env var causes the server to refuse to start.
Personal Access Tokens (PATs): Real tokens (sh_pat_…) — SHA-256 hashed in SQLite; full token returned once on create; list UI shows prefix/last4 only. Accepted as Bearer credentials on API and Smart HTTP.
Auth acceptance order:
1. Valid SOURCEHUB_TOKEN, OR
2. Valid PAT, OR
3. Unauthenticated only when bind is loopback and SOURCEHUB_TOKEN is unset.
Browser SPA: Settings → Access Tokens stores the operator token or PAT in localStorage and sends it on every same-origin fetch.
Outbound Webhooks: Dispatch event notifications; HMAC SHA-256 signatures (X-SourceHub-Signature-256) are attached when a webhook secret is configured. Built-in ping test tools included.
CI sandboxing (pragmatic): Workflow run: steps execute via execFile('/bin/bash', ['-c', …]) with sanitized env (no full process.env dump), repo cwd, timeout/maxBuffer, and a light dangerous-pattern guard. Workflow YAML is trusted operator content — not a multi-tenant sandbox.

🎨 Themes & Profile Customization

SourceHub features 14 tailored themes designed for readability and style:

⚡ Matrix Neon (Default — Obsidian black with vivid electric green)
📟 Cyber Amber (Phosphor VT220 amber on onyx)
🗼 Tokyo Night (Midnight indigo with vibrant cyan & violet)
☕ Catppuccin Mocha (Warm pastel & lavender dark)
🎨 Monokai Pro (Charcoal with vivid yellow & lime)
🌊 Solarized Dark (Deep marine teal & amber)
🌙 High Contrast Dark (Ultra-crisp dark & azure)
🌑 GitHub Dark (Classic dimmed charcoal)
🌌 Midnight OLED (True 0x000 black)
🧛 Dracula (Iconic purple & cyan palette)
❄️ Nord Frost (Arctic blues & frost slate)
🌆 Synthwave 84 (Neon pink & cyan glow)
☀️ High Contrast Light (Clean, crisp daylight)
📜 Warm Sepia (Warm parchment paper tone)

Persist your operator profile (name, username, email, bio, initials, avatar gradient, and theme) across reloads in SQLite.

🚀 Quick Start

Prerequisites

Node.js 22.0.0+ (Required for native node:sqlite)
Git 2.30+ installed on the system path
(Optional) Ollama installed and running (ollama serve) for AI Helper capabilities

Installation

Option 1: Pre-Built Debian Package (.deb)

Pre-compiled packages for Debian, Ubuntu, and Linux Mint are available in the releases/ directory:

# Install package
sudo dpkg -i releases/sourcehub_0.1.3_amd64.deb

# Launch SourceHub (opens in default browser)
sourcehub

Option 2: Install from Source

# Clone the repository
git clone https://github.com/Nick040791/SourceHub.git
cd SourceHub

# Install frontend and server dependencies
npm install

Running in Development

npm run dev

Visit http://localhost:5177 in your browser.

Building & Running the Production Daemon

SourceHub includes a standalone production HTTP server powered by native node:http:

# Build the React 19 frontend
npm run build

# Start the standalone server
npm run serve

Installing as a Systemd User Service

Run SourceHub automatically on login as a background service:

./scripts/install-service.sh

Manage the service with standard systemd commands:

# Check status
systemctl --user status sourcehub.service

# View live logs
journalctl --user -u sourcehub.service -f

# Stop or restart
systemctl --user stop sourcehub.service
systemctl --user restart sourcehub.service

# Uninstall service
./scripts/uninstall-service.sh

Desktop Application Launcher

A pre-configured launcher script is available in bin/:

./bin/launch-sourcehub.sh

This checks if the SourceHub daemon is running, starts it if necessary, and opens the hub in your default browser.

⚙️ Configuration & Environment Variables

Variable	Default	Description
`PORT`	`5177`	Port for the HTTP server to listen on.
`HOST`	`127.0.0.1`	Bind address for the production daemon / Vite / packaged service (`assets/sourcehub.conf`). Use `0.0.0.0` only with `SOURCEHUB_TOKEN` set — the server refuses non-loopback binds without it.
`SOURCEHUB_TOKEN`	(unset)	Operator shared secret. When set, required for `/api/` and `/git/`. Required to bind beyond loopback.
`SOURCEHUB_REPOS_DIR`	`~/Dev`	Base directory containing git repositories to discover and manage.
`SOURCEHUB_DATA_DIR`	`~/.sourcehub`	Directory storing SQLite database (`sourcehub.db`), worktrees, and logs.
`NODE_ENV`	`development`	Set to `production` when serving static frontend bundles.

Threat model (single-operator forge): Default bind is 127.0.0.1 for both production and npm run dev. Loopback + unset SOURCEHUB_TOKEN allows unauthenticated local use. For LAN exposure: set a strong SOURCEHUB_TOKEN (e.g. openssl rand -hex 32), bind HOST=0.0.0.0, and paste the same token (or a PAT) into Settings → Access Tokens so the SPA can authenticate. Anyone who can reach the bind address without a valid shared secret or PAT cannot use the API or Smart HTTP.

AI provider settings (Ollama URL, default model) and user profile preferences can be configured directly in the Settings tab and Profile Modal within the web interface.

📁 Repository Structure

SourceHub/
├── bin/
│   └── launch-sourcehub.sh     # Desktop launcher script
├── public/
│   └── sourcehub.svg           # High-contrast logo & icon assets
├── scripts/
│   ├── install-service.sh      # Systemd user service installer
│   └── uninstall-service.sh    # Systemd user service uninstaller
├── server/
│   ├── auth.ts                 # Shared secret + PAT auth & workflow env helpers
│   ├── agentService.ts         # Autonomous AI coding agent & worktree manager
│   ├── db.ts                   # Built-in SQLite database initialization (node:sqlite)
│   ├── gitService.ts           # Git CLI operations, Smart HTTP, and diff engines
│   ├── index.ts                # Production standalone daemon (node:http)
│   ├── vitePluginGitApi.ts     # API route handlers & development middleware
│   ├── webhookService.ts       # Outbound HMAC-signed webhook dispatcher
│   └── workflowService.ts      # Local Actions CI runner engine
├── src/
│   ├── components/
│   │   ├── actions/            # CI workflow execution views & log viewers
│   │   ├── agents/             # Helper AI session launcher & run tracker
│   │   ├── code/               # Tree browser, blob viewer, & doc preview
│   │   ├── desktop/            # Source control workbench (hunks, commit, stash)
│   │   ├── issues/             # Issue list, details, and agent assignment
│   │   ├── layout/             # App header, repo header, and hamburger menu
│   │   ├── pr/                 # PR comparison, diffs, reviews, and merge controls
│   │   ├── profile/            # Profile settings modal & 14 theme selectors
│   │   └── settings/           # Secrets, tokens, keys, webhooks, and AI config
│   ├── services/               # Frontend API client
│   ├── types/                  # Shared TypeScript interfaces
│   ├── App.tsx                 # Root application component
│   └── index.css               # Tailwind CSS & custom theme definitions
├── package.json
├── tailwind.config.js
└── vite.config.ts

🤝 Contributing & Local Development

SourceHub is built with simplicity and autonomy in mind:

No Heavy Frameworks: The backend is pure Node.js. When adding API endpoints or git operations, keep them fast, deterministic, and dependency-light.
Keep Everything Local: Do not introduce required dependencies on cloud services or external APIs.

Code Style: Follow TypeScript standards and ensure code passes type-checking:

npm run typecheck   # client (tsconfig.json) + server/tests (tsconfig.server.json)
npm test
npm run build       # runs typecheck, then vite build

📄 License

Designed and maintained for single-operator autonomy.

Navigation Menu

Repository navigation

About

Repository files navigation

SourceHub

📖 Overview

Screenshots

⚡ Architecture

✨ Features in Detail

🖥️ Desktop (Source Control Workbench)

AI Agent — Helper

🔀 Pull Requests & Code Review

⚡ Local Actions (CI Runner)

🌐 Git Smart HTTP Wire Protocol

🔒 Security, Keys & Webhooks

🎨 Themes & Profile Customization

🚀 Quick Start

Prerequisites

Installation

Option 1: Pre-Built Debian Package (.deb)

Option 2: Install from Source

Running in Development

Building & Running the Production Daemon

Installing as a Systemd User Service

Desktop Application Launcher

⚙️ Configuration & Environment Variables

📁 Repository Structure

🤝 Contributing & Local Development

📄 License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.sourcehub/workflows		.sourcehub/workflows
assets		assets
bin		bin
public		public
releases		releases
scripts		scripts
server		server
src		src
test		test
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
tsconfig.server.json		tsconfig.server.json
vite.config.ts		vite.config.ts

Latest commit

History

Folders and files

Repository files navigation

SourceHub

📖 Overview

Screenshots

⚡ Architecture

✨ Features in Detail

🖥️ Desktop (Source Control Workbench)

AI Agent — Helper

🔀 Pull Requests & Code Review

⚡ Local Actions (CI Runner)

🌐 Git Smart HTTP Wire Protocol

🔒 Security, Keys & Webhooks

🎨 Themes & Profile Customization

🚀 Quick Start

Prerequisites

Installation

Option 1: Pre-Built Debian Package (.deb)

Option 2: Install from Source

Running in Development

Building & Running the Production Daemon

Installing as a Systemd User Service

Desktop Application Launcher

⚙️ Configuration & Environment Variables

📁 Repository Structure

🤝 Contributing & Local Development

📄 License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages