Claude Code Guide: Setup to Your First Pull Request

Unsure which file to edit or which tests to run for your first pull request? Claude Code can help trace the bug while you control what goes to GitHub.

Use Claude Code to fix a Python display-name bug, test the patch, and submit it for review.

What Is Claude Code and How Does It Work?

Claude Code is one of the AI coding agents developers can use to investigate bugs and prepare fixes. Claude Code searches the repository, reads relevant files, and uses what it finds to propose changes. Depending on the permission mode, it can also edit files and run commands such as your test suite. In Plan Mode, Claude Code can investigate and outline a fix before changing source files. For a first pull request, give it one bug, an example that reproduces it, and a testable outcome. If you’re weighing Codex vs Claude Code, try the same small task in both and compare the diffs and test results.

Is Claude Code Free?

The installer is free to download. The standard Claude Free plan excludes coding agent access. Use an eligible paid Claude subscription, a Claude Console account with API credits, or supported cloud access. Check current Claude Code pricing before choosing between a subscription and usage-based API billing.

1. Install Claude Code and check your access

You’ll need Git, a cloned repository, and access to Claude Code. For a work or open-source project, check its rules for using an AI coding assistant. Keep credentials and .env values out of Claude Code prompts.

Claude Code download and version check

If “Claude Code Anthropic” turns up several installers, use Anthropic’s official setup page. Run the Bash installer if you’re using macOS, Linux, or Windows Subsystem for Linux.

curl -fsSL https://claude.ai/install.sh | bash

On native Windows, run this command in PowerShell.

irm https://claude.ai/install.ps1 | iex

In a fresh terminal, run claude --version to verify the Claude Code CLI. If it’s missing, check the installer’s PATH instructions.

How to Update Claude Code

Native installs update automatically. To update on demand, run claude update and confirm with claude --version. For Homebrew, upgrade the installed cask. For WinGet, run winget upgrade Anthropic.ClaudeCode.

2. Create a branch before Claude Code makes edits

The example project rejects an empty display name but accepts a name made of spaces. Give Claude Code three checks. An empty name and " " should both fail validation. Ada Lovelace should still pass.

Run git status --short from the repository. If it lists files, save your work separately or use a clean clone before launching Claude Code. Run each command separately and stop on errors. This assumes main tracks the remote and has no unpublished commits. Substitute your target branch if needed.

git switch main
git pull --ff-only
git switch -c fix/blank-display-name

Check git branch --show-current before asking Claude Code to edit. It should print fix/blank-display-name.

Run the project’s tests once on the new Git branch. This Python example uses unittest and keeps tests in tests/.

python3 -m unittest discover -s tests

If your Windows terminal uses the Python launcher, replace python3 with py -3. Record any failures before Claude Code changes a file. That gives you a baseline for troubleshooting.

3. Ask Claude Code for a plan and a small edit

Start Claude Code from the repository root in Plan Mode so it can inspect the project before editing. Follow the sign-in prompts on your first launch.

claude --permission-mode plan

If there’s a CLAUDE.md file at the repository root, read it for project instructions Claude Code loads when the session starts.

Give Claude Code the bug, the expected behavior, and a clear stopping point.

Read the README and locate the display-name validator and its tests. The app rejects a string with zero characters but accepts one made entirely of spaces. Plan a regression test and the smallest fix. Keep Ada Lovelace valid. Once I approve the plan, add only the test and wait for my next instruction.

If Claude Code suggests editing other fields, narrow the plan to the validator and its tests.

Add the failing test first

Approve the plan with manual edit approvals. Once Claude Code adds the test, rerun the suite. The new test should fail. If it passes, check that it calls the actual validator.

Then ask Claude Code to fix the validator and stop before committing. In this example, bool(value.strip()) rejects whitespace-only input while leaving the stored name alone.

4. Test and review what Claude Code changed

Rerun the same test command after the fix. In a local reproduction, the new test failed on the original validator and all three passed after the fix. If another test fails, give Claude Code the command and the relevant error, then compare it with your baseline.

Ask Claude Code for a short summary of the patch, then check the actual diff yourself. A diff shows the lines Git sees as added or removed.

git status --short
git diff --check
git diff

The status output also lists untracked files the diff omits. Look for debug prints, secrets, and unrelated formatting. If Claude Code touched a third file, find out why before you stage it.

5. Commit the patch and push your branch

Stage the two files Claude Code changed, using your project’s paths. Staging tells Git what to include in the next commit. Check the staged diff before committing.

git add src/validation.py tests/test_validation.py
git diff --cached

Commit and push the reviewed patch. If Claude Code runs these commands, confirm the remote and branch before approving the push.

git commit -m "Reject whitespace-only display names"
git push -u origin fix/blank-display-name

If the push fails, check origin with git remote -v. GitHub authenticates the push separately from your Claude Code session.

6. Turn Claude Code’s patch into a GitHub pull request

To open a pull request, go to the repository on GitHub and click Compare & pull request after pushing. Set the base to the branch where the fix should land, usually main. Set the compare branch to fix/blank-display-name. If the banner is missing, start under Pull requests → New pull request.

Share the commit and the test result you saw with Claude Code. Ask it to draft a title and description, then check that it reports only the tests you ran.

Reject whitespace-only display names

The validator now rejects names made only of whitespace. A regression test covers the case. Verified with python3 -m unittest discover -s tests.

Paste the title and description, then check the comparison diff for the patch Claude Code prepared. Select Create Pull Request when it’s ready for review, or choose Create Draft Pull Request in the button’s menu.

Open a draft from the terminal

With the GitHub CLI installed and signed in, run this command to open a draft pull request. Enter the title and description at the prompts.

gh pr create --draft --base main --head fix/blank-display-name

Check any automated results on the PR. If a reviewer asks for an adjustment, give Claude Code that specific request. To update the existing pull request, commit your changes and push them to the same branch.

Frequently asked questions

Can Claude Code create a pull request for me?

Yes. With gh authenticated and the right repository permissions, the assistant can run gh pr create. Check the repository, branches, and description before approving the action.

Can I use Claude Code on a repository I don’t own?

Yes, if the project allows AI-assisted contributions. Check CONTRIBUTING.md for any rules about disclosing Claude Code use. If you lack write access and forking is allowed, fork the repository, clone your fork, and push your branch there. Choose the original repository and target branch as the PR base.

What if Claude Code changes too many files?

Ask Claude Code which edits are essential to the fix. Keep the change and its test, and remove unrelated edits before staging. Check for your own uncommitted work before undoing changes.

Can I use Claude Code without the GitHub CLI?

Yes. Use Claude Code for the local work, push the branch with Git, and create the pull request in your browser.

Conclusion

Start with a bug you can reproduce. Use Claude Code to write a failing test, then review the fix and open a draft to see which checks GitHub runs.