Git-Steer: A Self-Hosting GitHub Autonomy Engine
TL;DR
git-steer is a Model Context Protocol (MCP) server that gives you 100% autonomous control over your GitHub account through natural language. But what makes it unique isn’t what it does—it’s what it doesn’t do.
- Zero local code: No repos cloned to your machine
- Keychain only: Just GitHub App credentials stored locally
- Git as database: All state lives in a private repo
- Actions as compute: Code changes happen in ephemeral cloud workers
Your PC or Mac becomes a steering wheel. GitHub becomes the engine.
Git-Steer Series:
- Introduction (this post) - Architecture and philosophy
- Setup Guide - Step-by-step installation
- Advanced Patterns - Custom workflows and extensions
The Problem: Local Development Clutter
Every developer knows this pattern:
cd ~/Projects
ls -la
# 47 directories, 12GB of node_modules,
# half of them you haven't touched in monthsWhen you manage multiple repositories—fixing security vulnerabilities, updating dependencies, creating PRs—you end up with a graveyard of cloned repos, stale branches, and forgotten package-lock.json files.
What if your local machine could orchestrate all of this without storing any of it?
The Vision: Bare Tin Foil
We call the architecture “Bare Tin Foil”—clean, minimal, no encryption overhead. Just pure git-as-database.
┌─────────────────────────────────────────────────────────────────┐
│ YOUR MAC │
│ │
│ Keychain: │
│ - GitHub App private key │
│ - App ID / Installation ID │
│ │
│ $ npx git-steer │
│ │ │
│ ├─► Pulls itself from ry-ops/git-steer │
│ ├─► Pulls state from ry-ops/git-steer-state │
│ ├─► Runs MCP server in-memory │
│ └─► Commits state changes back on shutdown │
│ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ GITHUB │
│ │
│ ry-ops/git-steer (source of truth for code) │
│ │ │
│ ry-ops/git-steer-state (private repo) │
│ ├── config/ │
│ │ ├── policies.yaml (branch protection templates) │
│ │ ├── schedules.yaml (job definitions) │
│ │ └── managed-repos.yaml (what git-steer controls) │
│ ├── state/ │
│ │ ├── jobs.jsonl (job history, append-only) │
│ │ ├── audit.jsonl (action log) │
│ │ └── cache.json (rate limits, etags) │
│ └── .github/workflows/ │
│ └── heartbeat.yml (scheduled triggers) │
│ │
└─────────────────────────────────────────────────────────────────┘Your PC or Mac has exactly four things:
- GitHub App ID (in Keychain)
- Installation ID (in Keychain)
- Private Key (in Keychain)
- Claude Desktop config pointing to git-steer
That’s it. No config files. No dotfiles. No ~/.git-steer. No cloned repos.
How Code Changes Work
This is where it gets interesting. When you ask git-steer to fix security vulnerabilities or make other code changes, it dispatches a GitHub Actions workflow instead of cloning code locally:
┌─────────────────────────────────────────────────────────────────┐
│ YOUR MAC (MCP triggers intent) │
│ │
│ You: "Fix security vulnerabilities in cortex" │
│ │ │
│ ▼ │
│ Claude → git-steer MCP: security_fix_pr(repo: "cortex") │
│ │ │
│ └─► Dispatches workflow to GitHub Actions │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ GITHUB ACTIONS (ephemeral compute) │
│ │
│ .github/workflows/security-fix.yml: │
│ - Checkout target repo │
│ - Update dependencies │
│ - npm install / uv lock │
│ - Run tests │
│ - Create branch, commit, push │
│ - Open PR │
│ - Report status back to git-steer-state │
└─────────────────────────────────────────────────────────────────┘Your PC or Mac stays clean. No node_modules. No Python venvs. No lock files. Just pure orchestration.
Comparison: git-steer vs ArgoCD
If you’re familiar with GitOps, you might be wondering how this compares to tools like ArgoCD. They’re philosophically related but solve different problems:
| Aspect | ArgoCD | git-steer |
|---|---|---|
| What it manages | Kubernetes clusters | GitHub itself |
| Direction | Git → K8s (pull) | Mac → GitHub API (push) |
| Source of truth | Git repos (K8s manifests) | Git repos (state + code) |
| Target | K8s resources (Deployments, Services) | GitHub resources (repos, PRs, branches) |
| Compute | Runs in-cluster (controller pod) | GitHub Actions (ephemeral) |
| Sync model | Continuous reconciliation | On-demand orchestration |
ArgoCD says: “Git describes what Kubernetes should look like.”
git-steer says: “Mac orchestrates what GitHub should do.”
They’re complementary—you could use git-steer to manage the Git repos that ArgoCD watches.
MCP Tools Available
git-steer exposes a comprehensive set of tools through the Model Context Protocol:
Repository Management
repo_list- List all accessible repositoriesrepo_create- Create new repo (optionally from template)repo_archive- Archive a repositoryrepo_delete- Permanently delete (requires confirmation)repo_commit- Commit files directly via API (no local clone)repo_read_file- Read file content from a reporepo_list_files- List files in a directory
Branch Operations
branch_list- List branches with staleness infobranch_protect- Apply protection rulesbranch_reap- Delete stale/merged branches
Security
security_scan- Scan repos for vulnerabilities with fix infosecurity_fix_pr- Dispatch workflow to fix vulnerabilitiessecurity_alerts- List Dependabot/code scanning alertssecurity_dismiss- Dismiss alert with reasonsecurity_digest- Summary across all managed repos
GitHub Actions
actions_workflows- List workflowsactions_trigger- Manually trigger a workflowactions_secrets- Manage Actions secretsworkflow_status- Check status of dispatched workflows
Real-World Example: Security Sweep
Here’s what a security sweep looks like with git-steer:
You: "Scan all my repos for security vulnerabilities"
Claude: [calls security_scan with repo="*"]
Scanning 30 repos...
Found 70 vulnerabilities across 12 repos
- 3 critical (form-data, jsonpath-plus, qdrant-client)
- 15 high (python-multipart, urllib3, pyasn1)
- 52 medium/low
You: "Fix all the critical ones"
Claude: [calls security_fix_pr for each affected repo]
Dispatching security-fix workflow...
- cortex-docker: workflow dispatched (job-id: fix-cortex-docker-1706...)
- cortex-platform: workflow dispatched
- cortex: workflow dispatched
You: "Check the status"
Claude: [calls workflow_status]
security-fix workflow runs:
- #1234: completed (success) - cortex-docker
- #1235: completed (success) - cortex-platform
- #1236: in_progress - cortexThree PRs created, dependencies updated, lock files regenerated—all without a single git clone on your machine.
Why This Architecture?
1. Security
Your machine has credentials, not code. If your laptop is compromised, attackers get GitHub App credentials (revocable) but not 30 repos worth of source code, secrets in .env files, or cached credentials.
2. Portability
Everything lives in GitHub. Switch to a new Mac? Install Claude Desktop, run npx git-steer init, authenticate, done. No syncing dotfiles or cloning repos.
3. Scalability
GitHub Actions provides unlimited ephemeral compute. Need to update 100 repos? Dispatch 100 workflows. Your PC or Mac’s CPU stays idle.
4. Auditability
Every action is logged to git-steer-state/state/audit.jsonl. Git provides history. You have a complete record of every operation, who triggered it, and what changed.
5. Simplicity
No Redis. No Postgres. No Docker. Just Git and GitHub Actions. Debug with cat and jq. Understand the entire system by reading a few TypeScript files.
Adapting to Other Projects
The “Bare Tin Foil” pattern isn’t specific to GitHub management. You can apply it to any domain:
| Domain | Local (Steering Wheel) | Remote (Engine) |
|---|---|---|
| GitHub | git-steer MCP | GitHub API + Actions |
| Kubernetes | kubectl MCP | K8s API + Jobs |
| Cloud Infra | terraform MCP | Terraform Cloud |
| Databases | db-admin MCP | Cloud Functions |
The pattern:
- Credentials only locally (Keychain, env vars)
- State in a versioned store (Git repo, S3, etc.)
- Compute in ephemeral workers (Actions, Lambda, Cloud Run)
- Orchestration via MCP (natural language → API calls)
Getting Started
# First-time setup
npx git-steer init
# This will:
# 1. Create a GitHub App with required permissions
# 2. Install it to your account
# 3. Create a private git-steer-state repo
# 4. Store credentials in macOS Keychain
# Add to Claude Desktop config
# ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"git-steer": {
"command": "npx",
"args": ["git-steer"]
}
}
}Then just talk to Claude:
“List all my repos” “Show me security alerts across all projects” “Create a new repo called ‘my-project’ from my template” “Delete all branches older than 60 days in cortex, except main”
What’s Next
This is the first post in a series about git-steer:
- This post: Introduction and architecture
- Setup Guide: Step-by-step installation
- Advanced Patterns: Custom workflows, multi-repo operations, extending git-steer
Conclusion
git-steer represents a shift in how we think about developer tooling:
Old model: Clone repos locally → Make changes → Push → Repeat for each repo
New model: Describe intent → MCP dispatches work → Cloud executes → Results appear
Your local machine becomes what it should be: a thin client for orchestrating work, not a warehouse for storing code.
The source is open. The architecture is documented. The future is autonomous.
Repository: github.com/ry-ops/git-steer
Stack: TypeScript, MCP SDK, GitHub API, GitHub Actions
License: MIT
Questions? Issues? PRs welcome at github.com/ry-ops/git-steer
Explore git-steer on GitHub
Check out the source code, documentation, and contribute to the project.