Gitworthy

The decision layer before a coding agent starts work.

Gitworthy helps coding agents scout, rank, and preflight software work before they spend cycles implementing it. It finds the strongest candidates, checks whether the work is already handled or blocked, and returns evidence-backed ACT, VERIFY, or SKIP decisions for each target.

MCP setup · CLI · Agent workflow · Verdicts · Troubleshooting · Case studies · Roadmap · Contributing

Why 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 main but 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 hunt to build a short ranked queue. Read each candidate's worth_check; hunt does not produce one global verdict. Treat ACT as a queue candidate, perform the named checks on VERIFY, and remove SKIP candidates. Before implementing a selected target, rerun worth_check and 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

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.

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 SKIP requires definitive evidence.
• Failed mandatory checks cap the result at VERIFY.
• Every real result includes meaningful checked and not_checked fields.
• 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