Helps coding agents scout, rank, and preflight software tasks to avoid redundant or blocked open-source contributions.
Also known as trippyogi/gitworthy
- Stars
- 2
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- 0.3.6
- Last commit
- Nov 9, 2026
- License
- MIT
What is Gitworthy MCP?
Gitworthy helps coding agents scout, rank, and preflight software tasks to avoid redundant or blocked open-source contributions. It exposes 8 tools, such as branch_scan, issue_vs_main, release_gap.
Summary generated from the project's README
About Gitworthy MCP server
Gitworthy acts as a decision layer for coding agents to evaluate open-source tasks before they begin implementation. It helps prevent wasted effort by identifying if a software issue is already being addressed by another contributor, exists on an unlinked branch, or has already been resolved in the main codebase. This tool is designed for developers using MCP clients like Cursor, ChatGPT, or Hermes to automate the scouting and ranking of repository issues.
Users can set up the server locally via stdio using npx or deploy it as a streamable HTTP service for cloud-based agents. The system requires a GitHub token to function, with fine-grained permissions for reading issues providing the most accurate results. It operates through two primary modes: a scout lane for discovering and ranking candidates, and an execute lane for rechecking and implementing selected targets. By returning structured verdicts, it ensures agents do not work on redundant or blocked tasks.
What you can do with it
- 1Scout for new contributionsAn agent can use the hunt command to find and rank a shortlist of high-quality issues within a specific repository.
- 2Avoid redundant pull requestsThe tool identifies if a fix already exists in an active pull request or an unlinked branch to prevent duplicate work.
- 3Automate contribution policy complianceAgents can verify if a repository requires specific assignments or follows certain rules before accepting work.
Written from the project's README. Every use case is checked against a quote from it.
How to install Gitworthy MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Gitworthy MCP in Claude Code
$ claude mcp add --env 'GITHUB_TOKEN=<YOUR_GITHUB_TOKEN>' gitworthy -- npx -y gitworthy mcpInstall Gitworthy MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"gitworthy": {
"command": "npx",
"args": [
"-y",
"gitworthy",
"mcp"
],
"env": {
"GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>"
}
}
}
}Install Gitworthy MCP in VS Code
.vscode/mcp.json
{
"servers": {
"gitworthy": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"gitworthy",
"mcp"
],
"env": {
"GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>"
}
}
}
}Install Gitworthy MCP in VS Code CLI
$ code --add-mcp '{"name":"gitworthy","type":"stdio","command":"npx","args":["-y","gitworthy","mcp"],"env":{"GITHUB_TOKEN":"<YOUR_GITHUB_TOKEN>"}}'Install Gitworthy MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"gitworthy": {
"command": "npx",
"args": [
"-y",
"gitworthy",
"mcp"
],
"env": {
"GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>"
}
}
}
}Install Gitworthy MCP in Codex
$ codex mcp add gitworthy --env 'GITHUB_TOKEN=<YOUR_GITHUB_TOKEN>' -- npx -y gitworthy mcpInstall Gitworthy MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.gitworthy] command = "npx" args = ["-y", "gitworthy", "mcp"] [mcp_servers.gitworthy.env] GITHUB_TOKEN = "<YOUR_GITHUB_TOKEN>"
Install Gitworthy MCP in Gemini CLI
$ gemini mcp add -s user -e 'GITHUB_TOKEN=<YOUR_GITHUB_TOKEN>' gitworthy npx -- -y gitworthy mcpInstall Gitworthy MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"gitworthy": {
"command": "npx",
"args": [
"-y",
"gitworthy",
"mcp"
],
"env": {
"GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for gitworthy 0.3.6 in an isolated container with no network and no keys. It answered and listed 8 tools.
Gitworthy MCP tools 8
Read from the server with tools/listbranch_scanissue_vs_mainrelease_gapdupe_clusterlinked_workcontrib_policyworth_checkscan
Configuration
GITHUB_TOKENSecretGitHub personal access token (fine-grained, read-only public repos). Optional; raises API rate limit from 60 to 5000 requests/hour.
GITWORTHY_MCP_TOKEN
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabletrippyogi/gitworthy is public and reachablegithub.com/trippyogi/gitworthy ↗Pass
- Package names this repository as its sourcegitworthy names trippyogi/gitworthy as sourcenpmjs.com/package/gitworthy ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/trippyogi/gitworthy ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from gitworthyPass
- No critical advisory in the package or its dependencies122 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubWhy Gitworthy
Coding agents make implementation cheap. Choosing the wrong task is still expensive.
An issue can look open while:
- a fix already exists on an unlinked branch;
- another contributor has an active pull request;
- the change landed on
mainbut has not been released; - the repository requires assignment before accepting work;
- a duplicate or abandoned implementation already contains the answer.
Gitworthy performs that preflight before a human or agent spends the next unit of work.
How agents use Gitworthy
The agent owns the loop. Gitworthy is the MCP decision engine it calls to scout and validate work.
Contribution goal, repository, or organization
│
▼
Cursor / ChatGPT / Hermes / agent
│
Gitworthy MCP
│
▼
policy → scan → rank → preflight
│
┌────────┼────────┐
▼ ▼ ▼
ACT VERIFY SKIP
queue it inspect drop it
│
▼
optional `portfolio`
(mode + dispatch, not a new verdict)
│
▼
Ranked candidate shortlist
│
▼
Select a candidate
│
▼
recheck → reproduce → implement → review
There are two distinct lanes:
- Scout lane: discover, filter, rank, preflight, and return a shortlist.
- Execute lane: select, record intent, recheck fresh state, reproduce, implement, review, and submit through the repository's allowed contribution path.
ACT means “worth considering,” not “start coding blindly.” Scout results go stale, so Gitworthy should be run again when an agent actually claims or begins a target.
See docs/AGENT_WORKFLOW.md for the complete agent policy, tool-selection guide, and scout-to-execute handoff.
Use it with Cursor, ChatGPT, Hermes, or any MCP client
Local stdio (desktop / agent VM)
{
"mcpServers": {
"gitworthy": {
"command": "npx",
"args": ["-y", "gitworthy@latest", "mcp"],
"env": {
"GITHUB_TOKEN": "github_pat_..."
}
}
}
}
Streamable HTTP (Cloud Agents / mobile / iPad)
Run or deploy the same engine over HTTP and point the client at a URL:
export GITWORTHY_MCP_TOKEN="$(openssl rand -hex 32)"
export GITHUB_TOKEN="github_pat_..."
npx -y gitworthy@latest mcp --http --host 127.0.0.1 --port 8787
{
"mcpServers": {
"gitworthy": {
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer ${env:GITWORTHY_MCP_TOKEN}"
}
}
}
}
Non-loopback binds require GITWORTHY_MCP_TOKEN. Keep GITHUB_TOKEN on the server. Full deploy and Cloud Agent notes: docs/HTTP_MCP.md. Tool descriptions, annotations, and structured results: docs/MCP.md. Portable Agent Plugins packaging (skill + MCP): docs/AGENT_PLUGINS.md.
Give the agent a policy like this:
Use Gitworthy before investing in external repository work. Use
huntto build a short ranked queue. Read each candidate'sworth_check;huntdoes not produce one global verdict. TreatACTas a queue candidate, perform the named checks onVERIFY, and removeSKIPcandidates. Before implementing a selected target, rerunworth_checkand follow the repository's contribution policy.
The token only needs read access to public repositories. For the most accurate linked-work detection, use a classic PAT or a fine-grained token with Issues: Read so Gitworthy can see timeline cross-references. Weaker tokens still work, but missing visibility is reported in not_checked.
Try it in 30 seconds
Check that your environment is ready:
npx -y gitworthy@latest doctor --json
Evaluate a specific issue:
npx -y gitworthy@latest check owner/repo#123
Render a deterministic handoff brief from a stored decision:
npx -y gitworthy@latest brief decision_abc123 --format markdown --out brief.md
Brief generation is read-only over the local store and never calls GitHub, npm, or an LLM. Stored decisions are considered stale after 24 hours; stale briefs warn and recommend recheck.
Scout and preflight a short list of contribution targets:
npx -y gitworthy@latest hunt owner/repo --json
npx -y gitworthy@latest hunt openclaw --max-checks 3 --json
Use @latest for exploration. Pin a version in repeatable agent workflows and CI.
What hunt actually returns
hunt is a bounded funnel, not a bulk verdict command:
contribution policy
↓
scan repository or organization
↓
rank issue quality and optional skill fit
↓
remove obvious land-only, assigned, weak, or known-SKIP rows
↓
run worth_check on only the best few candidates
↓
return candidates with individual verdicts and evidence
The agent should read each hunt_candidate.worth_check. Gitworthy intentionally avoids running an expensive full preflight on every issue returned by a broad scan.
ACT, VERIFY, or SKIP
| Verdict | Scout behavior | Execution behavior |
|---|---|---|
| ACT | Add it to the ranked queue after reading evidence. | Recheck before claiming or implementing; proceed only if fresh state and policy still allow it. |
| VERIFY | Surface it with the unresolved checks named. | Resolve those checks before forking or making a public claim. |
| SKIP | Remove it from the queue. | Do not begin parallel work; inspect the cited work or choose another target. |
A verdict is not a vibes-based score. Gitworthy returns structured evidence, the checks it completed, and the checks it could not complete.
A real preflight
A target issue in block/buzz appeared open, but a prior implementation already existed in a pull request using nearly the same title.
Target: block/buzz#1659
Verdict: VERIFY
Disposition: review
Evidence:
- An implementation exists in PR #1675.
- The pull request is linked work, not a duplicate issue.
Next action:
Inspect the current implementation before starting parallel work.
That case also exposed a false-positive path in duplicate detection: GitHub's issues API includes pull requests. The fix became a regression test and calibration case.
More real contribution sessions are documented in CASE_STUDIES.md.
How it works
Gitworthy combines bounded checks that answer different ways a task can be unsafe or wasteful to start.
| Check | What it protects against |
|---|---|
| Linked work | Existing pull requests, assignments, referenced commits, and prior attempts |
| Branch scan | Work already present on unlinked remote branches |
| Issue vs. main | Fixes that landed while the issue remained open |
| Release gap | Changes on main that are not in the published package |
| Contribution policy | Claim requirements, assignment rules, and repositories that do not accept pull requests |
| Duplicate analysis | Related or previously reported issues |
| Scan / org scan | Unranked issue tracker noise |
| Hunt | Wasteful broad checking by narrowing candidates before expensive preflight |
The CLI and MCP server are thin adapters over the same TypeScript core.
Trust model
Gitworthy is designed to be useful without pretending to know more than it checked.
- Heuristic evidence cannot independently create a hard
SKIP. - Hard
SKIPrequires definitive evidence. - Failed mandatory checks cap the result at
VERIFY. - Every real result includes meaningful
checkedandnot_checkedfields. - Human-readable prose is never parsed to decide the verdict.
- Target repositories and packages are treated as hostile input.
- Telemetry is off by default. The MCP path emits no telemetry.
- Scout results are not treated as permanent; execution requires fresh revalidation.
ACT does not mean “blindly start coding.” Read the evidence, disposition, reasons, linked work, and repository policy before investing.
Agent-native output
Every core result includes a structured envelope:
{
"verdict_summary": "one sentence",
"evidence": [],
"signals": [],
"checked": [],
"not_checked": [],
"cached": false,
"fetched_at": "2026-01-01T00:00:00.000Z"
}
signals is the load-bearing input to the decision policy. checked and not_checked are part of the result, not footnotes.
Common commands
gitworthy check owner/repo#123 [--npm-package name] [--json]
gitworthy hunt owner/repo [--manifest path] [--max-checks 3] [--json]
gitworthy portfolio owner/repo [--max-items 10] [--json]
gitworthy prs owner/repo [--json]
gitworthy ci-triage --head-check test:failure --base-check test:success [--json]
gitworthy history owner/repo --path src/core/hunt.ts [--json]
gitworthy opportunity-ingest --source hermes-eval --id case-9 [--json]
gitworthy scan owner/repo [--label "help wanted"] [--json]
gitworthy org owner [--manifest path] [--max-repos 8] [--json]
gitworthy policy owner/repo [--json]
gitworthy init [--user] [--repo] [--json]
gitworthy config validate [--path path] [--manifest path] [--json]
gitworthy config show --effective [--json]
gitworthy profile show [--json]
gitworthy related owner/repo [issue] [--json]
gitworthy ledger show owner/repo#123 [--json]
gitworthy doctor [--json]
gitworthy mcp
gitworthy mcp --http [--host 127.0.0.1] [--port 8787] [--stateless]
Exit codes for check:
0— ACT10— VERIFY20— SKIP1— error
See SKILL.md for the strict contribution gates and docs/AGENT_WORKFLOW.md for the explanatory workflow guide.
Documentation
| Doc | Topic |
|---|---|
| docs/AGENT_WORKFLOW.md | Scout vs execute, tool selection |
| docs/VERDICTS.md | ACT / VERIFY / SKIP and dispositions |
| docs/CLI.md | CLI reference and exit codes |
| docs/MCP.md | MCP tools, annotations, structured results |
| docs/AGENT_PLUGINS.md | Agent Plugins v1 packaging (skill + MCP) |
| docs/HTTP_MCP.md | Streamable HTTP MCP |
| docs/CONFIG.md | Config, manifests, profiles |
| docs/DATA.md | Local store, outcomes, captures |
| docs/EVALS.md | Frozen / live / private eval |
| docs/CORPUS.md | Corpus taxonomy (pass rate vs precision) |
| docs/CORPUS_CONTRIB.md | How to grow Track O vs Track F |
| docs/TRACK_O.md | Outcome calibration (Track O; not a release gate) |
| docs/BETA.md | Design-partner beta (GW-034) |
| docs/SECURITY_MODEL.md | Trust boundaries |
| docs/TROUBLESHOOTING.md | Doctor-driven remediation |
| docs/COMPATIBILITY.md | Pre-1.0 contract policy |
| docs/PERFORMANCE.md | Counters and budgets |
| docs/RANKING.md | Ranking contract |
| docs/RELEASE_1.0.md | 1.0 gate checklist |
Configuration
GITHUB_TOKEN/GH_TOKENenables authenticated GitHub REST checks.- Config files are data-only JSON. Gitworthy reads user config from
~/.gitworthy/config.jsonand repository-local config from.gitworthy/config.json. - Precedence is: CLI/MCP input,
GITWORTHY_*environment variables, repository config, user config, built-in defaults.gitworthy config show --effective --jsonincludes provenance for each effective value. - Create a secret-free skeleton with
gitworthy init --repoorgitworthy init --user. Validate withgitworthy config validate. - Skill profiles (
profilein config or--skill-profile) can includelanguages,topics,preferred_ecosystems, and avoid lists; they affect scan/hunt ranking inputs only, never hard verdict policy. - Target manifests (
--manifest pathormanifest_pathin config) can list repos/orgs, include/exclude filters, per-repo npm package mappings, and target-specific overrides. Ambiguous npm package mappings are rejected. Include/exclude filters are validated and carried as manifest metadata in GW-019; full filtering consumption is deferred to GW-027. - Tokens and credentials are never persisted in config or manifests; use environment variables such as
GITHUB_TOKEN/GH_TOKEN. GITWORTHY_MCP_TOKENis the bearer secret for Streamable HTTP MCP (required for non-loopback binds).GITWORTHY_CACHE_DIRoverrides the cache under~/.gitworthy/cache.GITWORTHY_LEDGER_DIRoverrides local scout history under~/.gitworthy/ledger.GITWORTHY_TELEMETRY=onplusGITWORTHY_POSTHOG_KEYrequests optional telemetry.
Optional PostHog telemetry also requires a user-installed posthog-node package. If it is missing, Gitworthy warns once and continues with telemetry disabled.
Without a GitHub token, checks that require GitHub REST return structured errors or explicit not_checked entries. Checks that can use public git or npm endpoints still run.
Current status
Gitworthy is pre-1.0 and actively hardening its decision contract, hostile-input handling, local outcomes, evaluation corpus, and onboarding.
The 1.0 goal is a trustworthy, local-first CLI and MCP decision engine—not a hosted SaaS and not another coding agent.
See ROADMAP.md for the release ladder.
Where this is going
Gitworthy is becoming the agent-native readiness layer between task discovery and implementation:
- discover candidate work;
- rank the most promising targets;
- determine whether each is actually ready;
- return a machine-actionable next step;
- revalidate selected work before execution;
- record what happened;
- improve future decisions from real outcomes.
The open-source decision engine stays local-first and MIT licensed. Possible post-1.0 layers include shared outcome history, scheduled hunts, private-repository coordination, and an API for agent dispatch.
Contributing
Gitworthy is built from real cases where apparently open work turned out to be handled, blocked, or unsafe to start.
The most valuable contributions are:
- examples where Gitworthy made the wrong decision;
- repositories or ecosystems it cannot inspect correctly;
- Cursor, ChatGPT, Claude Code, Codex, OpenClaw, Hermes, or other agent integrations;
- improvements to evidence quality and failure reporting;
- new frozen evaluation cases;
- documentation that helps another person get a useful result quickly.
See CONTRIBUTING.md for development setup and trust requirements.
Requirements
- Node.js 22 or newer
- A GitHub token is strongly recommended for real hunts
Security
Report vulnerabilities privately using SECURITY.md or email security@gitworthy.com.
License
MIT
Gitworthy MCP questions
How do I add Gitworthy MCP to Claude Code?
Run claude mcp add --env 'GITHUB_TOKEN=<YOUR_GITHUB_TOKEN>' gitworthy -- npx -y gitworthy mcp in your terminal. Add --scope user to make it available in every project.
How do I add Gitworthy MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Gitworthy MCP provide?
It exposes 8 tools, including branch_scan, issue_vs_main, release_gap, dupe_cluster, linked_work.
What does an ACT verdict mean?
An ACT verdict means the task is worth considering, but it is not a command to start coding blindly; the agent should still recheck the state before implementing.
Does Gitworthy require specific GitHub permissions?
The token only needs read access to public repositories, though using a token with Issues: Read access provides more accurate linked-work detection.
What checks does Gitworthy perform to protect against wasteful work?
It performs several checks including linked work detection, branch scans, checking if fixes landed on main, release gap analysis, and contribution policy verification.