taken

taken?

taken? answers one question before you volunteer for a GitHub issue: is it already taken?

In plain terms, it checks an issue before you start work: is it still open to contributions, is anyone already on it, and is the repo responsive enough that your PR will get reviewed.

Try it without installing anything: the live console runs the real checks in your browser.

The catch it was built for: GitHub shows "linked a pull request" events in the issue timeline, but never in the comments. You can read every comment on an issue and still miss that someone already opened a PR for it. taken? checks the timeline, scans comments for people claiming the work, looks at assignees, reads CONTRIBUTING.md for AI contribution policies, and checks whether the repo is still active. Then it gives a verdict, GO, TAKEN, or CAUTION, with the evidence cited.

Requirements

• Python 3.10 or newer
• The GitHub CLI (gh), authenticated

taken? only makes read-only API calls through your own gh login. It never sees or stores tokens, and it never writes anything to GitHub.

Install

uv tool install taken-gh

Or with pipx:

pipx install taken-gh

Then:

taken owner/repo#123

A full issue URL works too:

taken https://github.com/owner/repo/issues/123

The verdict

TAKEN wins over CAUTION, which wins over GO.

• TAKEN: the issue is closed, an open PR links to it, or someone is assigned.
• CAUTION: a comment says someone wants it (soft claim, they may have moved on), a linked PR was merged but the issue is still open, the repo has an AI policy to respect, the repo looks inactive, or a beginner-friendly label sits alongside a long discussion thread or a design-level label (worth skimming before you start).
• GO: none of the above.

The claimant scan is a heuristic over comment text, not proof. The verdict always prints its evidence so you can judge for yourself.

Exit codes: 0 means GO, 1 means TAKEN, 2 means CAUTION, 3 means something broke (bad target or flag, no gh, API error).

A pull request number is an invalid issue target: it returns an error (exit 3 in the CLI), without a contribution verdict.

Examples

An issue with a PR already fixing it:

$ taken Exodus-Privacy/exodus#300 taken? Exodus-Privacy/exodus#300 verdict: TAKEN ... why:

• open PR #700 already covers this: https://github.com/Exodus-Privacy/exodus/pull/700

An issue someone is already assigned to:

$ taken chahe-dridi/vscode-agent-bell#200 taken? chahe-dridi/vscode-agent-bell#200 verdict: TAKEN ... why:

• assigned to: dk5488

A clean issue, with your own volunteering comment filtered out:

$ taken snowflakedb/snowflake-cli#3145 --me RogueAlg0 taken? snowflakedb/snowflake-cli#3145 verdict: GO ... why:

• no linked PRs, no assignees, no claimants, repo is active

Useful flags

• --json: print the full findings as JSON instead of the human summary
• --me LOGIN: ignore your own comments when scanning for claimants
• --no-cache: bypass the one-hour API response cache
• --rest: force the REST fetch path (the default is GraphQL for logged-in users)
• --health: maintainer report for one repo instead of a contributor verdict

taken --help lists everything.

Health reports warn when either the issue listing or the PR listing reaches its scan cap. With --health --json, truncated describes the issue listing and pr_scan_truncated describes the PR listing; stale PR counts may be incomplete when the latter is true.

Batch mode and repo scans

Give taken several targets and it prints one verdict line per target:

taken owner/repo#123 owner/repo#124 --me mylogin TAKEN owner/repo#123 assigned to: dk5488 GO owner/repo#124 no linked PRs, no assignees, no claimants, repo is active

A bare owner/repo scans the repo automatically: its open issues (most recently updated first, PRs excluded) are each checked:

taken django/django --label "good first issue" --limit 10

API responses are cached for one hour in ~/.cache/taken (override with TAKEN_CACHE_DIR), so repeated scans stay cheap.

The opt-in REST transport (TAKEN_TRANSPORT=httpx) preserves both JSON objects and arrays, including empty listings. Response ETags are cached alongside either shape: after expiry, a 304 Not Modified reuses the cached body and refreshes its TTL. The default subprocess transport is unchanged.

Discover mode

taken --discover finds contribution candidates across GitHub: it takes raw candidates from GitHub's issue search, runs taken's full verification on each one, and ranks the survivors. Only GO verdicts make the list, scored on the signal no aggregator filters on: maintainer responsiveness.

taken --discover --language python --min-contributors 3 --limit 10 6 octocat/hello-world#42 maintainer replied; updated 1d ago; repo pushed 0d ago 4 octocat/other-repo#7 updated 3d ago; repo pushed 2d ago

Each line explains its own score. Candidates are verified in parallel (8 workers by default; --jobs N tunes it).

MCP server

taken also ships as an MCP server, so coding agents can check issues with a tool call instead of shelling out to the CLI. Same setup: gh installed and authenticated, read-only API calls through your own login.

uvx --from "taken-gh[mcp]" taken-mcp

Three tools: check_issue, scan_repo, discover_candidates. Published in the official MCP Registry as io.github.RogueAlg0/taken.

Clients that request MCP progress receive updates while scan_repo checks issues and discover_candidates verifies candidates. The updates use the current request's progress channel; clients that do not request progress keep the same results. Discovery can finish before its total is reached when the best results are already decided.

Result completeness for machine callers

MCP scan_repo and discover_candidates responses include truncated, considered and returned, even for empty results. Discovery also reports verified, the number of candidates submitted for verification. truncated means results may be incomplete because a listing/search/pool cap was reached, ranking stopped early, the result limit excluded matches, or discovery had verification/search errors. A full API page is conservatively marked limited when exhaustion cannot be established without another request.

Counts describe observed work, not the total number of issues on GitHub. For MCP scans, considered counts issues in fetched listing pages (excluding PRs); for discovery it counts candidates admitted to the verification pool. returned counts rows in results.

CLI JSON migration: --discover --json and bare-repository scans with --json now return an object containing results and this metadata. Consumers of the former array should read payload["results"]. Repository batches also include scans, with per-repository listing counts and limits; their top-level considered counts check jobs. Batches containing only explicit issue targets keep their JSON array format. Human-readable output is unchanged. Discovery emits its JSON object even when no candidate is returned.

Development

uv sync # install dev tools (ruff, pytest) uv run pytest uv run ruff check uv run ruff format --check

AI assistance

This project is built with AI assistance, and says so openly. Every contribution is reviewed and understood by its author before it lands.

Security

See SECURITY.md for the supported versions and how to report a vulnerability. Please use private vulnerability reporting, not a public issue.