The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Taken listing page.
taken? answers one question before you volunteer for a GitHub issue: is it
already taken?
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.
gh), authenticatedtaken? only makes read-only API calls through your own gh login. It never
sees or stores tokens, and it never writes anything to GitHub.
Or with pipx:
A full issue URL works too:
Useful flags:
--json: print the full findings as JSON instead of the human summary--me LOGIN: ignore your own comments when scanning for claimants--file PATH: read targets from a file, one per line--limit N: scan mode checks at most N open issues per repo (default: 20)--label LABEL: scan mode only considers open issues carrying this label--no-cache: bypass the API response cache--clear-cache: delete the API response cache and exit--graphql: fetch each issue with one GraphQL query (gh api graphql)
instead of ~10 REST calls; same verdicts, opt-in (or TAKEN_GRAPHQL=1)--persistent-session: run the GraphQL query over one persistent HTTPS
connection for the whole process; the token comes from gh auth token
and is held in memory only. Opt-in (or TAKEN_PERSISTENT_SESSION=1);
see GRAPHQL_NOTES.md for the security tradeoff--version, --helpExit codes: 0 means GO, 1 means TAKEN, 2 means CAUTION, 3 means something
broke (bad target, no gh, API error). With several targets the exit code
is 0 when every target produced a verdict and 3 when any target failed.
Give taken several targets and it prints one verdict line per target:
A bare owner/repo scans the repo automatically: its open issues
(most recently updated first, PRs excluded) are each checked:
API responses are cached for one hour in ~/.cache/taken
(override with TAKEN_CACHE_DIR), so repeated scans stay cheap.
--no-cache skips the cache; --clear-cache deletes it.
taken --discover finds contribution candidates across GitHub. It
piggybacks on GitHub's issue search API (the same source the web
aggregators use) for raw candidates, then runs taken's full verification
on each one and ranks the survivors. Only GO verdicts make the list.
Candidates are scored on the signal no aggregator filters on: maintainer
responsiveness. A non-author, non-bot comment scores +3; an issue updated
in the last 7 days scores +2; a repo pushed in the last 7 days scores +1.
Each line explains its own score. --label restricts the search to one
label instead of the default set (good first issue, good-first-issue,
beginner friendly, help wanted).
Every candidate is also marked for first-time friendliness: the issue's
own labels (e.g. [good first issue]) plus repo-level signs that
contributions are welcome ([has CONTRIBUTING.md], recent merged PRs).
Repo scans annotate the GO recommendations the same way, friendliest
first:
Candidates are verified in parallel (8 workers by default; --jobs N
tunes it). A progress bar on stderr shows live feedback during the run;
--no-progress hides it. The bar never touches stdout, so --json
stays script-friendly.
taken --json owner/repo#123 prints an object with three keys:
verdict: one of GO, TAKEN, CAUTIONreasons: list of human-readable strings explaining the verdictfindings: the raw check results:
target: e.g. owner/repo#123issue: number, state, title, labels, assignees,
comment_count, author, url, created_atlinked_prs: list of number, title, state, merged, author, urlclaimants: list of author, date, pattern, snippet, urlai_policy: verdict (ban, disclosure-required, or none-found),
snippet, sourcerepo_health: pushed_at, pushed_recently, recent_merges, starstaken also ships as an MCP server, so coding agents can check issues with a
tool call instead of shelling out to the CLI. It needs the same setup: gh
installed and authenticated, and it only makes read-only API calls through
your own login.
Run it directly (the MCP server ships with every install):
Or add it to your MCP client config:
Three tools:
check_issue(owner, repo, issue_number, me?): GO/TAKEN/CAUTION verdict with
reasons and full findings for one issue.scan_repo(owner, repo, limit?, label?, me?): the repo's open issues with
verdicts, GO first, plus recommendations (just the GO targets), a
verdict summary, and per-issue friendly_labels / welcoming markers
so the safest issues to adopt stand out.discover_candidates(limit?, language?, label?, min_contributors?, me?):
good-first-issue style candidates, verified and ranked, each marked with
its first-time-friendly labels and contribution-welcome signals.scan_repo and discover_candidates include effective_parameters in every
response so clients can see the resolved defaults and filters behind the
results. Their MCP input schemas also describe each optional parameter's
default.
taken is published in the official
MCP Registry as
io.github.RogueAlg0/taken.
An issue with a PR already fixing it:
An issue someone is already assigned to:
A clean issue, with your own volunteering comment filtered out:
TAKEN wins over CAUTION, which wins over GO.
The claimant scan is a heuristic over comment text, not proof. The verdict always prints its evidence so you can judge for yourself.
The hotspots badge tracks files that are both complex and frequently changed: complexity is cyclomatic complexity summed per file (via radon); churn is the number of commits touching the file. A file needs attention when it has complexity >= 50 and >= 5 commits; these are the files where refactoring pays off most.
To regenerate the badge data locally:
This project is built with AI assistance, and says so openly. Every contribution is reviewed and understood by its author before it lands.
See SECURITY.md for the supported versions and how to report a vulnerability. Please use private vulnerability reporting, not a public issue.