GitHub Sync Agent

Automatically syncs every local project directory to its own GitHub repository.

For each project it will:

1. git init if not already a repo
2. Create the GitHub repo if it doesn't exist yet
3. Ensure the remote uses SSH
4. Stage + commit any uncommitted changes
5. Push to origin

Runs daily via a systemd user timer, and on-demand via CLI.

---

Installation

pip install github-sync-agent                  # CLI + tools (base)
pip install 'github-sync-agent[api]'           # + web chat UI & HTTP API
pip install 'github-sync-agent[mcp]'           # + MCP server (Cursor / Claude Desktop)
pip install 'github-sync-agent[llm]'           # + ask command (requires Ollama)
pip install 'github-sync-agent[api,mcp,llm]'  # everything

Prerequisites (all platforms):

• Python 3.10+
• git — git-scm.com
• gh (GitHub CLI) — cli.github.com

For ask command and web chat:

• Ollama running locally (ollama serve)
• A downloaded model: ollama pull gemma3:4b

First-time setup

github-sync init

The wizard will:

• Check git and gh are installed
• Authenticate with GitHub (gh auth login)
• Ask which folder to scan for projects
• Set up your SSH key automatically
• Verify SSH works (auto-fixes port 443 and ssh-agent if needed)
• Write a config file to ~/.config/github-sync/config.yaml

Setup will not complete until ssh -T git@github.com succeeds.

---

Usage

Service management

# Check all prerequisites and service status
github-sync doctor

# Start everything (Ollama + HTTP API / web chat)
github-sync start

# Stop everything
github-sync stop

# If Ollama was installed as a system service and start/stop fails:
sudo systemctl start ollama
sudo systemctl stop ollama

# Fine-grained control
github-sync start --no-ollama   # start API only (Ollama already running)
github-sync stop --no-ollama    # stop API only, leave Ollama running

Sync

# Sync all projects
github-sync sync

# Sync a single project
github-sync sync --project my-project

# Preview without making changes
github-sync sync --dry-run

# Show status of all projects
github-sync status

---

Shared tools layer

github_sync/tools.py defines the core operations used by the API, MCP server, ask command, and web chat:

Tool	Description
list_projects	List discoverable project directories
get_status	Git/remote/changes/GitHub status for all projects
sync_all	Sync every project (dry_run optional)
sync_project	Sync one project by name (dry_run optional)

Inspect and test from CLI:

github-sync tool list
github-sync tool run list_projects
github-sync tool run get_status
github-sync tool run sync_project --arg project=Agents --arg dry_run=true

Each tool returns JSON: {"ok": true/false, "message": "...", "data": {...}}.

---

MCP Server (Cursor / Claude Desktop)

Exposes the 4 tools above to any MCP host via stdio.

Install

pip install 'github-sync-agent[mcp]'

Register in Cursor

Add to ~/.cursor/mcp.json (create if it doesn't exist):

{
  "mcpServers": {
    "github-sync": {
      "command": "/path/to/.venv/bin/github-sync-mcp",
      "args": [],
      "env": {}
    }
  }
}

If you installed with pipx, the command is just github-sync-mcp.
With a venv, find the path with:

which github-sync-mcp
# or: github-sync doctor

Then reload Cursor (Ctrl+Shift+P → Reload Window). The 4 tools will appear and the AI can call them directly.

Run manually

github-sync-mcp

---

Ask command (natural language via Ollama)

Install and start Ollama first (see Local LLM below), then:

pip install 'github-sync-agent[llm]'

github-sync ask what is the status of my projects
github-sync ask are there any uncommitted changes
github-sync ask sync the Agents project
github-sync ask sync everything dry run

The agent calls the appropriate tool (get_status, sync_project, etc.), gets real data, and answers in plain English. No cloud — runs entirely on your machine.

Override model or URL:

github-sync ask --model llama3.2 --ollama-url http://localhost:11434 "sync all"

---

Web chat UI

pip install 'github-sync-agent[api,llm]'

# Start everything in one command
github-sync start
# → Open http://127.0.0.1:8741

# Or manually:
sudo systemctl start ollama   # start Ollama (system service)
github-sync serve             # start the web server

Features:

• Live project status strip (synced / unsynced / GitHub ✓)
• Chat interface — type naturally, press Enter
• Tool calls shown inline as collapsible cards
• Streaming responses from the local LLM
• Works entirely offline (no cloud)

---

HTTP API

Install API dependencies:

pip install 'github-sync-agent[api]'

Start the server:

github-sync serve
# → http://127.0.0.1:8741

Endpoints

Method	Path	Description
GET	/health	Health check (no auth)
GET	/tools	List available tools and JSON schemas
GET	/status	Sync status for all projects
POST	/sync	Sync all projects
POST	/sync/{project}	Sync one project

Optional body for POST: {"dry_run": false}

Examples

curl http://127.0.0.1:8741/health
curl http://127.0.0.1:8741/tools
curl http://127.0.0.1:8741/status
curl -X POST http://127.0.0.1:8741/sync
curl -X POST http://127.0.0.1:8741/sync/Agents

API authentication (optional)

Add to config.yaml:

api_key: "your-secret-key"

Then pass the key on every request (except /health):

curl -H "Authorization: Bearer your-secret-key" http://127.0.0.1:8741/status

Run as a systemd service

cp systemd/github-sync-api.service ~/.config/systemd/user/
systemctl --user enable --now github-sync-api.service

---

Configuration (~/.config/github-sync/config.yaml)

Generated by github-sync init. You can edit it at any time.

Key	Default	Description
github_user	(detected from gh auth)	Your GitHub username
projects_root	~/projects	Scans all subdirectories here
schedule_time	02:00	Daily run time
default_visibility	private	private or public for new repos
auto_commit_message	chore: auto-sync	Commit message for auto-commits
exclude	[]	Directory names to skip
log_file	~/.local/share/github-sync/github-sync.log	Log file path
log_level	INFO	DEBUG / INFO / WARNING / ERROR
api_host	127.0.0.1	API bind address
api_port	8741	API port
api_key	(empty)	Optional Bearer token for API auth
ollama_url	http://localhost:11434	Ollama base URL for ask and web chat
llm_model	gemma3:4b	Ollama model name
llm_timeout	120	Seconds to wait for LLM response

Excluding a project

exclude:
  - SomeProjectToSkip

---

Local LLM (Ollama + Gemma)

The agent can use a local LLM via Ollama. Gemma runs inside Ollama — you start/stop Ollama, not Gemma separately.

Install (WSL / Linux, once)

sudo apt-get install -y zstd
curl -fsSL https://ollama.com/install.sh | sh
ollama pull gemma3:4b

Start / stop Ollama

# Check if running
curl -s http://localhost:11434 && echo "Ollama is running"

# Start (systemd — typical after install)
sudo systemctl start ollama
sudo systemctl enable ollama    # optional: start on boot

# Stop
sudo systemctl stop ollama

# Start manually (foreground — Ctrl+C to stop)
ollama serve

On WSL with user systemd:

systemctl status ollama
systemctl start ollama
systemctl stop ollama

Use the model

# Interactive chat
ollama run gemma3:4b

# One-shot prompt
ollama run gemma3:4b "Hello"

# List downloaded models
ollama list

Quick reference

Action	Command
Is it running?	curl http://localhost:11434
Start (service)	sudo systemctl start ollama
Stop (service)	sudo systemctl stop ollama
Start (manual)	ollama serve
Stop (manual)	Ctrl+C
Chat with Gemma	ollama run gemma3:4b

Ollama listens on http://localhost:11434 — used by github-sync ask and the web chat UI.

---

License

MIT