Why GitSocial

Git solved distributed collaboration for code. GitSocial extends it beyond code, making your data portable and independent.

How It Works

All collaboration data (posts, issues, PRs, etc.) is stored in your git repository as git commits with structured trailers on gitmsg/* branches, syncing via git fetch and git push. Activity from other repositories appears in your timeline when you add them to your lists.

Installation

macOS / Linux:

brew install gitsocial-org/tap/gitsocial
# or
curl -fsSL https://raw.githubusercontent.com/gitsocial-org/gitsocial/main/install.sh | sh

If macOS blocks the binary ("cannot verify developer"), run:

xattr -d com.apple.quarantine $(which gitsocial)

Windows:

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

Go:

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

Or download a binary from Releases.

Quick Start

Clone your project from GitHub, GitLab, or any host, then from your project directory:

gitsocial import         # imports issues, PRs, releases, discussions
gitsocial tui            # explore in the terminal

Documentation

Concepts

Document	Description
GitMsg Protocol	Core message format, headers, refs, versioning
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

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