GitHub Issues workflow for Claude Code, Codex and Cursor

Updated

CRUX connects GitHub Issues to the coding agent you already use, with or without a GitHub Projects board. It is for a small team or an open-source maintainer who wants a person to start each step and the agent to know the task's history.

The problem with issue text alone

Before CRUX, we gave the agent only the text of one GitHub issue. From here on this page calls it a task. The agent did not know why earlier code was written that way, so it changed the code and broke working behaviour.

What CRUX adds on top of GitHub Issues

Your tasks, comments and statuses stay in GitHub. CRUX gives each status an owner role, its agents and the artifact each step leaves. Through CRUX the agent reads the task and earlier tasks with their approved artifacts. An agent on your machine reads the code and the wiki from the repository checkout, not over MCP.

How to connect GitHub Issues

  1. Create a project. Sign in, create an organization and a project, choose GitHub Issues as the tracker and pick the repository. The project's ticket prefix, <KEY>, is filled in from the repository name. You can change it while you create the project, not later. An issue #N then appears in CRUX as <KEY>-N.
  2. Install the CRUX GitHub App. An owner of your CRUX organization starts the install, and an owner of the GitHub organization installs or approves the app there. The same app gives CRUX access to the repositories you select, with their code, pull requests, issues and the organization's projects.
  3. Link your GitHub account. Each team member links their own GitHub account on the Connected accounts page. CRUX then acts in GitHub as that person.
  4. Statuses. CRUX finds your GitHub Projects board, or keeps statuses in labels without one. The next section explains how.
  5. Connect your coding agent. Each person opens "Connect your coding agent", creates a personal token and keeps it in the CRUX_MCP_TOKEN environment variable.
  6. Set up the workflow. A project admin installs the plugin and runs /crux:crux-config in Claude Code, which needs the connection from step 5. The agent reads your statuses, asks who owns each one and proposes a .crux/ folder in a pull request. Without a code repository CRUX imports the workflow directly. Without Claude Code, choose "Start from the template" or "Build from my board" in the dashboard.
  7. Start a step. Run /crux:crux-run <KEY>-N planner in Claude Code.

The plugin install in Claude Code:

claude plugin marketplace add cruxteam/skills
claude plugin install crux@cruxteam

How do GitHub Projects statuses work with Claude Code?

With GitHub Projects, statuses live in the Status field of a Projects v2 project board, and without a board CRUX keeps them in S:<NAME> labels. If you have a board, CRUX finds it, takes statuses from its Status field and writes status changes there. You pick a board only when you can write to several. Without a board, CRUX creates the S:<NAME> labels itself. A personal repository always uses labels. An issue that is not on the board has no status, so it waits in no role's queue until CRUX sets its status and adds it to the board.

How statuses map to workflow steps

The template a new project starts from looks like this. While you set it up, you match its statuses to your board or labels and change the roles and agents.

StatusOwner roleAgentArtifact
To DoPMrefineracceptance criteria
In ProgressDeveloperplannerimplementation plan
In ReviewDeveloperreviewerreview report
DonePMnonenone

The person in the owner role starts the step. A person approves at the checkpoints, usually the agent's understanding, its plan and its result. A person moves the task to the next status.

What the agent reads and what it may change

The agent reads the task, its parent issue, its sub-issues, comments and relations. A relation on GitHub is blocks or blocked by. The agent searches tasks, also by label.

It can create and update tasks, and add comments and relations. It is told to change a status or an estimate only when a person asks. CRUX stores an estimate as an EST: label. On GitHub the agent cannot attach files, add URL links or delete a task.

Nobody acts under a bot account. Text that an agent wrote starts with a robot emoji, 🤖.

Each step posts its artifact as a structured comment on the task. At a checkpoint the agent posts it only after you approve the draft. The next step reads that comment, not the chat history.

How CRUX differs from GitHub's own coding agent

The GitHub Copilot cloud agent takes an issue you assign to it, works in a cloud sandbox at GitHub and opens a pull request. In CRUX a person starts each step. The checkpoints for the agent's understanding and its plan come before any code. Assigning a task to an agent in Jira, or delegating an issue to Linear's coding sessions, works like Copilot; Task-to-PR agents compares these products.

Limits

  • CRUX supports only Projects v2 boards. Classic boards do not work.
  • A CRUX project is one repository plus at most one board.
  • GitHub Enterprise Server is not supported as a tracker.
  • CRUX is a hosted service only. There is no self-hosted version.
  • CRUX is in beta.

Next step

Start free. For setup in Codex, Cursor and other agents, read Connect your coding agent.

FAQ

Do I need GitHub Projects, or are issues enough?

Issues are enough. Without a Projects v2 board, CRUX keeps statuses in S:<NAME> labels that it creates itself.

Can I use Codex or Cursor instead of Claude Code?

Yes. Only the setup command /crux:crux-config needs Claude Code, and without it you set the workflow up in the dashboard.

What does it cost?

One person uses CRUX free. A team of 2 to 10 people pays $49 per active project per month, 11 or more pay $120, and the first month of every project is free. During the beta billing is not switched on, so nothing is charged. See the pricing page.

Other trackers

CRUX also works with Jira Cloud, Linear and Plane.