GitHub Tasks

A Codex / ChatGPT desktop plugin that turns your GitHub account into a task workspace. Browse every issue you're involved in, see your GitHub Projects as boards, and start a Codex thread on any of them in one click, pre-loaded with the issue, the repo and a plan-first or implement-now brief.

Screenshots use fake demo data (DEMO=1 npm run dev).

Features

• Issues across every repo. Involving me / Assigned / Created / Mentioned, filtered by repo, label, state, issues vs PRs, optionally grouped by repo. The search box takes raw GitHub qualifiers (label:bug no:assignee repo:owner/name).

• GitHub Projects (v2) as boards. Every project you and your orgs can see, grouped by any single-select field (Status by default), with a card filter and "hide done".

• One-click task kickoff. Choose a mode, add notes, and Start in new thread:

  Mode	What Codex is told to do
  Plan first	Explore the code, propose a plan, wait for approval before editing
  Implement	Branch, change, test, open a PR that closes the issue
  Investigate	Find the root cause and report; no edits
  Review (PRs)	Review the diff and report findings by severity

  The ▶ button on any row or card starts a thread immediately in your current mode.

• Edit before you send. Edit prompt shows the exact text Codex will receive. Edits are used by Start, Copy and Add to composer alike.

• Pick a model first. The extension API can't choose a model for a new thread (it uses your default). Use Add to composer to attach the prompt to the open composer, choose the model there, then send. Each attachment appears as its own removable chip titled with what it contains (e.g. Plan first · acme/api#482 Webhook retries exhaust the…), and adding more issues keeps the earlier ones. Copy prompt puts it on your clipboard.

• Stays responsive while GitHub is slow. Nothing blocks: saved results from your last visit show instantly and update in place (a thin progress bar and spinner show activity), filters and the board keep the old view on screen until fresh data lands, and hovering an issue pre-loads its details so opening it is instant.

• Any GitHub, any account. github.com, GitHub Enterprise Server and ghe.com, with every signed-in account one click away in the avatar menu. Hosts that aren't signed in get a step-by-step connect guide (see below) instead of an error.

• Batch. Tick several items to start one thread each, or attach them all to the composer.

• Resizable detail panel (drag the edge, double-click to reset, arrow keys to nudge; width is remembered).

• Keyboard: j/k move · x select · / search · Esc close.

• Model tools. Codex itself can call gh_tasks.search, gh_tasks.projects and gh_tasks.issue to read issues without leaving the conversation.

Related MCP server: Git MCP Server

Install

Requires the Codex desktop app and CLI, Node.js 22+, and a GitHub login (see GitHub access).

codex plugin marketplace add rafazafar/codex-gh-tasks-plugin
codex plugin add gh-tasks@codex-gh-tasks-plugin

Fully quit and reopen the app, then choose GitHub Tasks in the sidebar.

Update

Plugins don't update themselves. When a new version is released, run:

codex plugin marketplace upgrade codex-gh-tasks-plugin
codex plugin add gh-tasks@codex-gh-tasks-plugin

Then fully quit and reopen the app. The first command pulls the latest release; the second installs it (no need to remove first). Check with codex plugin list; the VERSION column should show the new version.

Running only the second command does nothing, because Codex is still looking at its old copy of this repo; the marketplace upgrade step is what refreshes it. Your settings (remembered host/account, panel width) are kept.

Uninstall:

codex plugin remove gh-tasks@codex-gh-tasks-plugin
codex plugin marketplace remove codex-gh-tasks-plugin

GitHub access (one-time setup)

The plugin talks to GitHub's GraphQL API itself; the GitHub CLI is only used to borrow your login, so you never paste a token. It finds credentials in this order:

1. GITHUB_TOKEN or GH_TOKEN in the environment of the Codex app, otherwise

2. your GitHub CLI session (gh auth token). gh is looked up on PATH and in the usual install locations (/opt/homebrew/bin, /usr/local/bin, …), since desktop apps often start with a minimal PATH.

Easiest path (recommended):

brew install gh                 # or see https://cli.github.com
gh auth login
gh auth refresh -s project      # gh's default login has no Projects access
gh auth status                  # check: scopes should include repo, read:org, project

Without the CLI: create a classic personal access token and make it available to the app as GITHUB_TOKEN. Apps launched from the Dock don't see variables exported in ~/.zshrc, so start Codex from a terminal where it's set, or set it at the system level.

If your orgs enforce SAML SSO, authorise the token for them (GitHub → Settings → Tokens → Configure SSO).

Several accounts or hosts? Switch from your avatar

Click your avatar and name (top right) to see every account the GitHub CLI is signed in to, grouped by host (github.com, your company's GitHub, …). Pick one and the whole plugin (issues, Projects, prompts) switches to it. The choice is remembered.

• Add a host or account… opens the guided connect flow. A second account on a host you already use is just gh auth login --hostname <host> again; the new account shows up in the menu as soon as you return to the window.

• Accounts come from the GitHub CLI (gh auth status lists them), so the plugin never stores credentials itself.

• Prompts sent to Codex name the account you picked, with the gh auth switch --hostname <host> --user <login> command in case the CLI in that thread is signed in as someone else.

• If a GITHUB_TOKEN environment variable is set, it's used for the CLI's default account on github.com (like gh itself does). Choosing a specific account from the menu uses that account's own saved login instead.

Company GitHub, but you only use git + SSH?

Very common: you git clone git@github.mycompany.com:team/repo.git all day and never signed the GitHub CLI in to that host. An SSH key can't read issues: it only authenticates git (clone/push), while issues and Projects come from GitHub's web API, which needs a separate sign-in token. The two don't conflict, so your SSH setup stays exactly as it is.

The plugin walks you through it, with nothing to configure and no token pasted anywhere:

1. Click your avatar (top right) → Add a host or account… (or just open the plugin: if a host isn't signed in you'll land on the same guide).

2. Type the host, i.e. the part after git@ in your repo URLs, or use Detect from my SSH config (reads hostnames only, only when you click it).

3. It checks the host and tells you what's missing:

   • Can't reach it → "connect to the company VPN", then it re-checks.

   • Not signed in → shows the one command to run, with a copy button:

     gh auth login --hostname github.mycompany.com --git-protocol ssh --skip-ssh-key --web --clipboard --scopes project

     --git-protocol ssh --skip-ssh-key keeps git on SSH and leaves your keys untouched. It opens your browser to sign in with your company account.

   • Browser sign-in blocked? An expandable alternative uses a personal access token.

4. When you come back to the window it re-checks by itself and switches to the host. The host is remembered.

If your organisation blocks both the GitHub CLI app and personal access tokens, API access isn't available to you and no tool can show issues; ask your GitHub admin to allow one of them.

GitHub Enterprise

Works with GitHub Enterprise Server (https://ghe.company.com) and GitHub Enterprise Cloud with data residency (*.ghe.com) as well as github.com.

gh auth login --hostname ghe.company.com
gh auth refresh -s project --hostname ghe.company.com

• The plugin reads the hosts you're signed in to from the GitHub CLI's hosts.yml. If you're signed in to more than one, a host switcher appears in the header. With a single Enterprise login it starts there automatically (set GH_HOST to force a default).

• Tokens are looked up per host: GH_ENTERPRISE_TOKEN (or GITHUB_ENTERPRISE_TOKEN) for Enterprise, GITHUB_TOKEN/GH_TOKEN for github.com. A github.com token is never sent to an Enterprise host (covered by a test).

• Prompts sent to Codex name the host and tell it to use GH_HOST=<host> with the gh CLI.

• Older Enterprise Server releases without some GraphQL fields (project membership, linked PRs) still list issues; those extras are simply left out. Projects v2 needs a server version that supports it.

Status: the Enterprise path is covered by unit tests (endpoint selection, token isolation, host discovery, older-server fallback) but hasn't been run against a real Enterprise instance yet. Issues welcome if you hit something.

Requests go only to the GitHub host you're using (api.github.com, or your Enterprise host) plus avatar images. Nothing is stored or sent anywhere else, and the plugin never writes to GitHub.

How it works

GitHub Tasks is built on the OpenAI MCP Extensions (docs): a local MCP server (stdio) that also serves an MCP App UI.

.agents/plugins/marketplace.json   marketplace manifest (repo root = marketplace)
plugins/gh-tasks/                  the built, installable plugin (committed so Git install works)
src/server/                        MCP server: tools, GitHub GraphQL client, demo fixtures
src/app/                           Preact UI, host bridge, prompt builder
.codex-plugin/ .mcp.json skills/   plugin manifest sources
scripts/build.mjs                  bundles server.js + a single self-contained app.html
scripts/dev.mjs                    standalone browser preview

Development

npm install
npm test               # query builder, prompts, markdown sanitising
npm run typecheck
npm run build:plugin   # rebuild plugins/gh-tasks (commit the result)

Preview the UI in a browser (no Codex needed, real GitHub data; "Start thread" copies the prompt):

npm run dev            # http://localhost:5199
DEMO=1 npm run dev     # fake data, no network
DEMO=1 LATENCY=3000 npm run dev   # simulate a slow GitHub to see the loading states

Install your working copy into Codex (after npm run build:plugin):

codex plugin marketplace add "$PWD"
codex plugin add gh-tasks@codex-gh-tasks-plugin

Bump version in .codex-plugin/plugin.json when you change the plugin, then remove and re-add it so Codex refreshes its cached copy.

Troubleshooting

• No sidebar entry: run codex plugin list and check it says installed, enabled, then fully quit and reopen the app.

• "Sign in to " screen: follow the on-screen command, or see Company GitHub, but you only use git + SSH?.

• "No GitHub credentials found" / "gh isn't logged in": run gh auth login, or provide GITHUB_TOKEN (see GitHub access above), then click refresh in the plugin.

• Projects tab is empty: run gh auth refresh -s project (add --hostname <host> for Enterprise). Org projects may also need SSO authorisation of your token.

• Avatars don't show: they're inlined by the server; check network access to avatars.githubusercontent.com.

Limitations

• Read-only: you can't move cards or edit issues; the point is starting work.

• Boards load up to 300 items per project; issue search pages 40 at a time.

• A new thread uses your default model; see "Pick a model first" above.

• The installed MCP SDK has no per-tool icons, so the sidebar uses the server icon.

Ideas

Composer @-mentions for issues, a settings page (default mode, prompt templates), a "which local checkout is this repo" mapping so threads open in the right workspace.

License

Apache-2.0