# A Claude Code workflow for GitHub issues

> **TL;DR** Pick one issue, give Claude Code its number and the repository, let it mark the issue in progress, do the work on a branch and comment what it did, then review the pull request yourself. Plain GitHub runs this loop with the gh CLI or GitHub's MCP server, bounded only by your token's scopes. Gitsu's desktop app runs it with an agent panel and a write budget: six single-item write tools, no deletes, a one-hour cap per agent process, and a log of every agent write.

A Claude Code workflow for GitHub issues is a loop with four steps: you pick an issue, you hand it to the agent, the agent updates the issue as it works, and you review the result. This guide runs that loop twice, first with plain GitHub tools and then with Gitsu's desktop app, and marks where each version can go wrong.

Both versions assume the agent can reach GitHub. If it cannot yet, set that up first with [connecting Claude Code to GitHub Projects with MCP](/guides/connect-claude-code-to-github-projects-mcp).

## What does the loop look like?

The loop keeps one person responsible for each issue and one agent working on it at a time:

1. **Pick.** Choose one issue that is small enough to review in one sitting. Its body should say what done looks like.
2. **Hand over.** Start Claude Code in a clone of the repository and give it the issue number.
3. **Update.** The agent moves the issue to In progress, works on a branch, and comments what it did.
4. **Review.** You read the diff and the comment, then merge, send it back, or close the pull request.

The step that fails most often is the second. An issue that says "fix the login bug" hands the agent a guess. An issue that names the file, the failing case and the expected behaviour hands it a task.

## How do you run the loop with plain GitHub?

Plain GitHub runs this loop with the `gh` CLI, which Claude Code can call from its shell, or with GitHub's MCP server. With `gh`:

1. **Pick.** List what is open and read the one you choose:

   ```bash
   gh issue list --state open --label bug
   gh issue view 42 --comments
   ```

2. **Hand over.** In the repository's folder, start Claude Code and say: "Work on issue 42. Read it with `gh issue view 42 --comments`, fix it on a new branch, open a pull request that closes it, and comment on the issue with what you changed."

3. **Update.** The agent can label and comment on the issue with `gh issue edit 42 --add-label in-progress` and `gh issue comment 42 --body "..."`. To move the card on a Projects board it needs `gh project item-edit`, which takes the project, item, field and option IDs rather than names. It also needs a token with the `project` scope, which you add with `gh auth refresh -s project`.

4. **Review.** Open the pull request and review it like any other. A pull request that says `Closes #42` closes the issue when it merges.

GitHub's MCP server replaces the shell commands with tools. Its `issues` toolset is on by default; its `projects` toolset is not, and without it the agent cannot touch the board.

## Where are the risks with plain GitHub?

The risk is that the agent's reach is your token's reach. A classic token with `repo` and `project` can edit, close and comment on every issue in every repository you can push to, and delete project items. Nothing between the agent and GitHub counts its writes or knows which issue it was given.

Ways to bound it:

- **Scope the token.** A fine-grained token limited to the one repository keeps a mistake inside that repository.
- **Separate planning from doing.** For a session that only reads the board, use GitHub's read-only server URL, which drops every write tool.
- **Keep Claude Code asking.** Leave tool-use approval on for `gh` commands that write, and approve each one.
- **Review the diff and the issue.** The pull request shows code changes, but label and comment changes happen on the issue. Read its timeline too.

Every write lands under your name, so a teammate cannot tell the agent's comment from yours unless the agent says so in the text.

## How does the loop change with Gitsu?

Gitsu's desktop app runs the same loop from inside the board. The agent panel starts Claude Code, or another installed agent, as a Run: one conversation, shown as a tab. [Agent runs](/features/agent-runs) covers the panel itself: which agents it lists, when the process starts and which folder it works in. The loop then goes like this:

1. **Pick.** Choose the issue on your board in Gitsu.
2. **Hand over.** Open the agent panel, choose **New run**, and pick the agent. A Run executes in a local clone of the repository. If no folder is bound, Gitsu passes the open board's ID in the first prompt so the agent's board tools know which board you mean. Put the issue number in your prompt.
3. **Update.** With Gitsu's MCP server enabled for that agent, the agent calls `start_work` on the issue, which puts an `agent-working` label on it, and the board animates the card. It moves Status with `set_field_value`, comments with `add_comment`, and calls `finish_work` to take the label off.
4. **Review.** You review the pull request on GitHub as before. In Gitsu the activity log lists every write the agent made, and the comments it wrote carry a hidden marker naming the agent and the date.

A Run on its own writes nothing to GitHub. Gitsu decided against labelling an issue just because a Run mentions it: a Run lives on one laptop, a label is visible to the whole project, and a crashed Run would leave the label wrong. Only the agent's own `start_work` call puts a label on an issue, and the app removes labels left behind by an agent process that died.

## How does Gitsu bound what the agent writes?

Gitsu bounds agent writes by what its tools can do and by a budget, not by a prompt on every call. Switching an agent on in **Settings → MCP server** is the grant; switching it off revokes it. After that:

- **The tool set is small.** Six write tools, each changing one item: set a field, add or remove labels, comment, close, reopen. There are no tools to create or delete issues, remove items from a project, or change assignees and milestones. Gitsu's rule is that an agent may only make changes GitHub keeps a record of, so each one can be seen and undone.
- **Writes come from a budget.** The agent calls `request_write_budget` with a reason and a number of writes. The budget belongs to that one agent process, dies with it, and expires after one hour at most. A write with no budget fails and names the tool to call.
- **Replies are confirmed.** A write reports success only after GitHub accepts it, and a write that GitHub refuses comes back with the board's valid field names and values.
- **The app must be open.** Writes go through the running desktop app. If it is closed, the write fails and nothing is queued.

## What does Gitsu not protect against?

Gitsu cannot prove which agent is calling. It can prove that the caller is its own MCP server, but the agent's name is a claim, so the per-agent switches are consent settings rather than a security boundary. The hidden comment marker is write-only today: nothing in Gitsu reads it back yet, so the activity log is where to look. And writes still land as you, with no bot identity, exactly as they do with `gh`.

Gitsu's MCP server and agent panel are part of the desktop app, which is Gitsu Pro. The free web app does not include them.

## Which version should you use?

Use plain GitHub if you want no extra app, work across many repositories, or need the agent to create issues and manage projects. Use Gitsu if you want to watch the board while the agent works and want a hard ceiling on what it can change. The reasoning behind that ceiling is in [how Gitsu lets an AI agent update GitHub issues safely](/features/agent-safety). If your board lives in Linear today, [moving from Linear to GitHub Issues](/guides/move-from-linear-to-github-issues) covers getting the issues across first.

## Frequently asked questions

### Can Claude Code update the Status field on my GitHub Projects board?

Yes, with a Projects-capable tool: gh project item-edit, the projects toolset of GitHub's MCP server, or set_field_value in Gitsu's MCP server. Plain gh issue commands cannot, because Status is a project field, not an issue property.

### How do I stop an agent from making changes I did not ask for?

Limit what its credentials can reach. Use a token scoped to the repositories involved, use a read-only server URL for planning sessions, and keep Claude Code asking before it runs tools. Gitsu adds a write budget and has no delete tools at all.

### Will other people see that an agent is working on an issue?

With Gitsu, only if the agent calls start_work, which puts a real agent-working label on the issue until finish_work removes it. A run in Gitsu's agent panel does not label anything on its own.

### Does the agent's comment show up as written by a bot?

No. Both gh and Gitsu write as you, with your token. Gitsu adds a hidden marker to comments the agent writes and an entry in its activity log; plain GitHub has no equivalent.