GitPilot MCP

GitPilot is a stateful AI engineering control plane for GitHub. It connects issues, approved local code, durable project memory, and auditable verification runs through MCP tools and a web dashboard.

Capabilities

• List owned, collaborator, and organization repositories available to the connected GitHub identity.
• Create, update, label, comment on, close, and reopen issues.
• Recall repository knowledge across AI sessions.
• Retrieve ranked code snippets within fixed token budgets.
• Read bounded file ranges and apply exact-match edits.
• Run only manifest-derived verification commands.
• Require successful verification before completing an AI fix run.
• Keep an append-only history of context, reads, edits, checks, and completion.
• Connect a repository's own AI provider and generate a structured patch proposal, apply it only on explicit approval, verify it, and publish it as a draft pull request — never on a protected branch, never without a second explicit approval to publish.
• Optionally let GitPilot retry automatically after a failed verification (up to a bounded attempt count), carrying forward only the failure, not the whole repository — still stops for human review on a high-risk or low-confidence proposal, and never publishes on its own.
• Select a repository-scoped manual no-AI mode that blocks provider calls while retaining bounded evidence, exact edits, isolated branches, allow-listed verification, audit history, and draft-PR publishing — always one click away, even after a billing, quota, or credential failure on the AI path.

Setup

cd /d "C:\Projects - Building\GithubPilotMCP"
.venv\Scripts\activate.bat
pip install -r requirements.txt
copy .env.example .env

Start the dashboard and paste a GitHub personal access token into Connect repository & brain. On a loopback-only local install, GitPilot creates a private persisted vault key in data/.gitpilot-master-key, validates the token, encrypts it at rest, and never returns it to the browser. Production, staging, and network-exposed deployments must set GITPILOT_MASTER_KEY through secure secret storage. As a bootstrap alternative, set GITHUB_TOKEN in .env.

Prefer a fine-grained token with access only to intended repositories. Use Metadata read, Contents read/write, Issues read/write, and Pull requests read/write when you want the complete diagnose, patch, and draft-PR workflow. GitHub may require the repository owner or organization administrator to approve access; GitPilot cannot bypass that approval.

Map approved local repositories for code operations:

GITPILOT_CODE_ROOTS=my-repo=C:\path\to\my-repo

Separate multiple mappings with semicolons. GitPilot lists all repositories available to the token, but it can read or edit code only in explicitly mapped workspaces.

Setup Doctor

Before registering GitPilot with Claude, check that everything is configured correctly:

python setup_doctor.py

Every check prints a plain-language status, an exact recovery step if something is wrong, and machine-readable details. It never prints a token value. The doctor recognizes both encrypted dashboard connections and GITHUB_TOKEN, then verifies Python, dependencies, GitHub authentication, repository access, SQLite, code workspaces, MCP readiness, the dashboard port, and Claude CLI registration readiness.

Dashboard

python dashboard.py

Open http://127.0.0.1:8765. Keep this interface on localhost or place it behind authenticated TLS.

The Log in control provides native email/password accounts without requiring Google. Account creation asks for the GitHub profile name, not a repository. Each account receives a unique customer ID. Passwords are salted and one-way hashed with scrypt; GitHub and AI credentials continue to be encrypted with GITPILOT_MASTER_KEY and are scoped to that customer ID. Customers can also create revocable gp_live_... GitPilot API keys from Account & API access. The plaintext API key is displayed once and only its SHA-256 hash is stored.

GitPilot never collects a GitHub username/password combination or a GitHub OTP. With a configured GitHub App, account creation continues to GitHub's installation screen so the customer chooses the exact repositories and permissions. With OAuth configured, GitPilot redirects to GitHub's authorization-code flow with state validation and PKCE; GitHub handles sign-in and two-factor authentication on github.com, then returns an authorization token. A validated personal access token remains the local fallback. The verified GitHub identity replaces any typed profile typo, and GitPilot lists only repositories that GitHub says the connection can access.

Repository selection happens after the connection is verified. The customer can run Select repositories again later after creating a repository, accepting an invitation, or expanding a token/App installation. Separate-owner and organization repositories remain subject to GitHub's approval rules.

Local guest preview remains available by default. For a deployed customer service, set GITPILOT_REQUIRE_ACCOUNT_LOGIN=true, configure a persistent GITPILOT_SESSION_SECRET, set GITPILOT_HTTPS_ONLY=true, and terminate traffic through HTTPS. Do not create Python or configuration files containing one customer's secrets; credential records belong in the encrypted, owner-scoped database vault.

For a reliable presentation without depending on venue connectivity or a live GitHub account, open http://127.0.0.1:8765/?demo=1. Demo mode is clearly labeled and uses simulated repository, issue, retrieval, memory, model, cost, GitHub connection, AI provider connection, and Brain Profile data. The normal URL always uses real configured services.

Connect repository and select your brain

Click Connect repository & brain to open the setup wizard: paste and validate a GitHub token, select any accessible owned/collaborator/organization repository, choose DeepSeek, Anthropic, OpenAI-compatible/local, Google Gemini, or xAI Grok, connect the customer's own provider key, choose a model, set token and cost limits, and review everything before activating. This is BYOK (bring your own key): GitPilot never supplies a shared developer key, never falls back to the operator's key, and never shares one customer's credential with another customer. Provider usage and charges belong to the customer account that issued the key. The access checker explains when a separate owner or organization must approve access, and the wizard can accept a pending repository invitation after GitHub issues it. A configured GitHub App remains an optional additional connection mode. See docs/BRAIN.md for the full architecture, data model, and threat model.

At workflow selection, choose Manual / no AI to operate without an AI credential or provider call. This choice is stored independently for each repository and enforced by the backend. Switching back to AI requires explicitly activating a valid repository Brain Profile.

Hosted AI access and chat subscriptions are separate products. ChatGPT Plus/Pro or Codex access does not automatically provide OpenAI Platform API billing for calls made by GitPilot, and a DeepSeek chat subscription does not fund the DeepSeek API. The wizard makes this distinction explicit. For no hosted-model charge, use Manual / no AI or connect an Ollama/vLLM-style local server through OpenAI-compatible / local. DeepSeek V4 Flash is the lowest-cost hosted option in the built-in catalog, but it still requires a DeepSeek Platform API key and available balance.

Users without an API key can choose Use external chat (copy/paste). This is a separate manual fallback, not a ChatGPT/Claude account connection: GitPilot cannot sign in to or operate the user's subscription. It builds a bounded, copy-ready prompt containing only the selected issue evidence and allow-listed verification commands. The user pastes that prompt into an external assistant, then pastes the returned JSON proposal back into GitPilot. The imported result is untrusted: it must pass the same file-scope, exact-match, patch-size, verification-command, proposal-hash, human-approval, isolated-branch, and test gates as an API-generated proposal. GitPilot makes no provider call and records zero model cost for this handoff.

Once a repository's brain is active, starting a guided fix from an issue walks it through evidence → diagnosis → patch proposal → approve & apply (isolated branch) → verify → approve & publish (draft PR) — every stage shown in the dashboard's pipeline panel, and every filesystem/GitHub write gated behind its own explicit human approval. See docs/BRAIN.md §16 for exactly what the AI can and cannot do at each stage.

Hosted multi-tenant login (optional, beta)

By default the dashboard runs in local, single-owner mode — no login, identical to today. To let multiple people log in with their own GitHub account instead:

1. Create a GitHub OAuth App at https://github.com/settings/developers. Set its Authorization callback URL to http://<your-host>/auth/callback.
2. Set GITHUB_OAUTH_CLIENT_ID and GITHUB_OAUTH_CLIENT_SECRET in .env from that app.
3. Generate a GITPILOT_MASTER_KEY (see .env.example) — this encrypts every logged-in user's GitHub token at rest. Never commit it or share it outside your deployment's secret storage.
4. Restart the dashboard. Visitors now see a "Log in with GitHub" screen.

Project memory and fix-run history are scoped to the logged-in user in hosted mode. Local code editing remains deliberately unavailable to hosted users because a hosted service cannot safely access a customer's disk; run the MCP client locally for code operations.

Native GitPilot accounts are independent from the optional GitHub OAuth flow. A customer can first create an email/password workspace and then paste a fine-grained GitHub personal access token into the repository wizard. OAuth can remain disabled for a local-only deployment.

For the strongest customer onboarding, configure a public GitHub App and set GITHUB_APP_ID, GITHUB_APP_SLUG, and GITHUB_APP_PRIVATE_KEY_PATH. GitHub Apps are preferred because customers choose specific repositories and the app receives fine-grained permissions and short-lived installation tokens. OAuth remains a supported fallback. An encrypted fine-grained personal access token remains available for local development where neither integration is configured.

Optional GITPILOT_INPUT_USD_PER_MTOK and GITPILOT_OUTPUT_USD_PER_MTOK values control the provider-neutral planning estimate shown before a run. Actual provider billing remains authoritative.

Claude MCP

Register once:

claude mcp add gitpilot -- "C:\Projects - Building\GithubPilotMCP\.venv\Scripts\python.exe" "C:\Projects - Building\GithubPilotMCP\server.py"

Example prompt:

Start an AI fix run for issue #12 in atlas-library-ai. Recall project memory, inspect only the ranked files, make the smallest safe edit, verify it, save the resolution, and only then close the issue.

The manual flow uses ai_start_issue_fix, ai_read_file, ai_edit_file, ai_verify_fix, and ai_complete_issue_fix. When a repository has an active Brain Profile, the guided-fix flow (ai_generate_patch_proposal, ai_approve_and_apply_patch, ai_verify_fix, ai_publish_fix) drives the same evidence-gathering and human-approval boundaries through an AI-authored patch instead of manual edits. Arbitrary shell commands are never accepted.

Manual exact edits are hashed for audit, applied only on a dedicated gitpilot/fix-* branch, and can use the same verified draft-pull-request publisher. AI-generated patches require the exact reviewed proposal hash; omitting it fails closed.

Docker

docker compose up --build

The image runs as a non-root user with a read-only filesystem. SQLite persists under data/ and approved code is mounted separately.

Test

python -m pytest -q

This runs the full offline suite only — every live-credential test is opt-in and skipped by default (tests/test_live_integration.py, tests/test_live_guided_fix_integration.py). See their module docstrings for exact setup instructions if you want to exercise a real GitHub App installation and a real AI provider end to end.

See docs/ARCHITECTURE.md for the memory model, state machine, provider boundaries, and production guidance, and docs/BRAIN.md for the GitHub App connection, AI provider vault, Repository Brain Profile, and guided-fix patch pipeline. Never commit .env or expose tokens in logs or screenshots.