From issue to pull request

This tutorial sends one small GitHub issue to Claude Code with the dream:smith assignment skill. At the end, the agent's implementation is on a pull request that is ready for you to review.

Use a repository where you are comfortable letting an agent create a branch, commit and push changes, and update a pull request.

1. Install the tools

You need:

• Git;
• uv;
• GitHub CLI, version 2.94.0 or later for the dream skills; and
• a Claude Code account and setup that supports auto permission mode.

If you are upgrading an older installation, read Compatibility and upgrades before replacing it. For a first installation, run this command unless you have already run it:

uv tool install dreamcatcher

Then make the command available in your shell:

uv tool update-shell

Open a new terminal if uv tool update-shell asks you to, then check the commands are available:

dreamcatcher --version
gh --version
claude --version

This installs the latest release of dreamcatcher from PyPI.

2. Sign in to GitHub and Claude

dreamcatcher acts as the account that gh is signed in as. For this walkthrough, use HTTPS for Git too:

gh auth login --git-protocol https
gh auth setup-git
gh auth status

The account needs permission to push branches to the repository. Later, assign the issue to this same account; dreamcatcher will ignore an issue assigned only to somebody else.

Start Claude Code in auto permission mode, and follow the browser sign-in if Claude asks:

claude --permission-mode auto

Reaching the Claude prompt confirms that this installation and account can start the mode dreamcatcher uses. Leave Claude with /exit.

3. Prepare the repository

Use the main checkout of an ordinary clone, not a linked Git worktree. dreamcatcher deliberately refuses to run from a linked worktree because it creates and manages worktrees of its own.

git clone https://github.com/OWNER/REPOSITORY.git
cd REPOSITORY
git switch main
git pull --ff-only origin main

Replace OWNER/REPOSITORY with your repository.

An assignment sees the files committed on origin/main, not uncommitted setup from your main checkout. Before dispatching, commit and push the project's agent instructions, dependency manifests, lockfiles and any scripts needed to set up or test the project. Make those instructions non-interactive: nobody can answer a prompt that waits inside an autonomous round.

This walkthrough assumes you may push that setup to main. If main is protected, land the same files through your repository's normal pull-request process before continuing.

4. Run dreamcatcher init

From the main checkout, run:

dreamcatcher init

init checks that gh can push to the repository, that Git can commit and that origin/main can be fetched. It writes a default dreamcatcher.toml, installs the dream plugin for each harness the file uses, and creates the labels the file names. It prints one line for each step. If a step fails, init says how to fix it; fix it and run init again. If Codex is installed as well as Claude, the file uses both, so sign in to Codex too, with codex login.

The dream plugin is installed at user scope, outside the repository, so its skills are available in the Git worktree where an assignment runs. The plugin provides dream:smith, the assignment skill this tutorial uses.

The dreamcatcher.toml that init writes routes the labels agent-assignment, agent-assignment-easy, agent-campaign and agent-conversation to skills from the dream plugin. Customise skills says which skill each label runs, and Configure labels and harnesses says when to choose agent-assignment-easy. If Codex is not installed, the file keeps the Codex recipes as comments. The label connects a GitHub issue to its route, and {issue} in a prompt becomes the issue number, so issue 123 with the agent-assignment label starts Claude with /dream:smith GH123.

Until origin/main holds the file, init ends by printing the commands that commit and push it. Run them, so the assignment worktree contains the file too:

git add dreamcatcher.toml
git commit -m "Configure dreamcatcher"
git push origin main

For other routes or another harness, see Configure labels and harnesses. The configuration reference lists every setting.

5. Prepare a small issue

In GitHub:

1. Open one small, self-contained issue. State the expected result and how to check it.
2. Assign it to the account shown by gh auth status.
3. Add the agent-assignment label.

Choose work that can finish in one pull request. Avoid an issue with an open blocking issue or an existing open pull request linked to it; either condition keeps a new assignment from starting.

Suppose GitHub gives the issue number 123. The commands below call it GH123; replace that with your own issue number.

6. Start dreamcatcher

From the main checkout, start the daemon in its own terminal:

dreamcatcher run --harness claude --interval 30 --max-agents 1

Keep this terminal open. dreamcatcher looks for work, waits 30 seconds after each look, and runs at most one agent round at a time. A round is one headless run of the agent: dreamcatcher readies the worktree and the round's input, runs the agent process, and finishes up after that process exits.

dreamcatcher starts Claude non-interactively in auto permission mode and allows the selected Git, pull-request and issue commands the assignment needs to finish the job. The agent can edit files, run tools, commit and push under your account. These controls are not a security sandbox or a guarantee about what a plugin will do, so use a repository, plugin and GitHub account you trust.

On dispatch, dreamcatcher fetches origin/main, creates a branch and a worktree for it, pushes an empty commit, and opens a linked draft pull request. The draft means the assignment has begun; it does not mean the implementation is ready for review. Claude then works in that worktree.

7. Watch the assignment

Your browser opens the web home page when the daemon starts. Select the > on the card for issue #123 to open the assignment and see its rounds and live feed. The page reads local state, so it can show activity without publishing the agent's working notes to GitHub. You can also follow the same feed in a second terminal:

dreamcatcher feed GH123

If the agent needs a decision, it should ask on the draft pull request. Reply there using the same GitHub account that gh is signed in as. dreamcatcher relays your pull-request comment or review into another round at its next update.

When the implementation is complete, the assignment skill changes the pull request from draft to ready for review. That is the endpoint of this tutorial: a normal pull request containing the implementation, checks and the agent's account of the change.

Continue with Review an assignment to give feedback, merge it, and let dreamcatcher finish its wrap-up.