About

GitSocial stores issues, pull requests, comments, etc. in the git repository itself, and can push it to an S3 bucket you own as a git remote and a static site, like GitSocial.org.

Each item is a commit with GitMsg trailers on a gitmsg/* branch: it moves with git push and git fetch. The CLI and TUI can create and browse them (demo), the timeline shows items from followed repositories, and one command mirrors a forge project into a bucket:

gitsocial mirror https://github.com/owner/repo s3://<endpoint>/<bucket>/<prefix>

Installation

macOS / Linux with Homebrew

brew trust gitsocial-org/tap
brew install gitsocial-org/tap/gitsocial

Or using installation script

curl -fsSL https://gitsocial.org/install.sh | sh

Windows

scoop bucket add gitsocial https://github.com/gitsocial-org/scoop-bucket.git
scoop install gitsocial

Go

go install github.com/gitsocial-org/gitsocial/cli/gitsocial@latest

Or download a binary from releases.

Quick Start

Mirror a project

gitsocial mirror https://github.com/owner/repo s3://<endpoint>/<bucket>/<prefix> --url https://your-domain/

--url is the site's public address. mirror asks for the bucket credentials on first run; public access and the domain are one-time provider-dashboard steps. On a large repository try -n 100 first (all flags).

Explore a repository in the terminal

Clone it from GitHub or any host, then from the project directory:

gitsocial import     # import issues, PRs, etc. from GitHub or GitLab
gitsocial tui        # explore in the terminal

Host your own repository on a bucket

gitsocial config credentials set s3.example.com    # paste the access + secret key
gitsocial remote add s3://s3.example.com/mybucket/myrepo --default --site
gitsocial push

Anyone can then fetch it with gitsocial clone s3://s3.example.com/mybucket/myrepo, or with plain git clone from the bucket's public URL.

Documentation

Concepts

Document	Description
GitMsg Protocol	Core message format, headers, refs, versioning
S3 Remote	Buckets as git remotes, canonical URLs
Static Site	Repo website served from the bucket: timeline, issues, PRs, releases, code
Identity Verification	Decentralized trust model, attestation sources, caching
Notifications	Notification types, scopes, and triggers

Extensions

Document	Description	Spec
Social	Posts, comments, lists, timeline, followers	GitSocial
PM	Issues, milestones, sprints, labels, boards	GitPM
Review	Pull requests, feedback, forks, version tracking, cross-forge scenarios	GitReview
Release	Releases, artifacts, checksums, signatures, SBOM	GitRelease
Memo	Tiered memos for knowledge as commits	—

Clients

Document	Description
Agent Skill	AI-assisted workflows for Claude Code, Cursor, and other agents
TUI	Per-view layout diagrams (see also keybindings)
CLI	Commands, flags, output formats
JSON-RPC	Client integration over stdio

Contributing

Platform issues and PRs are disabled on all mirrors. GitSocial uses its own tools for collaboration.

Getting Started

1. Install GitSocial (see Installation)
2. Fork the repository on any host (GitHub, GitLab, Codeberg, or self-hosted)
3. Clone your fork: git clone https://your-host.com/you/gitsocial
4. Read Architecture for system design, packages, and cache layout

Submitting Pull Requests

git checkout -b feature/my-change         # make changes, commit

gitsocial review pr create \
  --base main \
  --head feature/my-change \
  "Short description of change"

git push origin feature/my-change         # push your branch
gitsocial push                            # push PR metadata

After your first push, request fork registration in the Matrix room so maintainers can discover your PRs and issues.

See Review for the full cross-forge PR workflow.

Reporting Bugs & Requesting Features

gitsocial pm issue create "Bug: description"
gitsocial push

For quick questions or discussion, use the Matrix room.

License

MIT