How to use the Dev Agent to automatically create pull requests — prerequisites, commands, examples, and tips for getting the best results.

Creating PRs with the Dev Agent

The Dev Agent reads your codebase, generates code changes using Claude, and opens pull requests automatically. This guide covers how to use it effectively.

Estimated time: 5 minutes to learn, then seconds per PR

Prerequisites

Before using the Dev Agent to create PRs, ensure:

GITHUB_TOKEN is configured with repo scope (required for reading code, creating branches, and opening PRs)
ANTHROPIC_API_KEY is configured (required for Claude code generation)
A repository is linked via @codespar link owner/repo

Verify Setup

@codespar status

You should see a linked project with an active Project Agent. If no project is linked, follow the Configure a Project guide first.

Commands

Two commands trigger the Dev Agent to create PRs:

`@codespar instruct <task>`

For new features, additions, and general coding tasks:

@codespar instruct add a health check endpoint at /api/health
@codespar instruct create a user validation middleware
@codespar instruct add rate limiting to the login endpoint

`@codespar fix <issue>`

For bug fixes and corrections:

@codespar fix the auth middleware is not checking token expiry
@codespar fix TypeError in user.service.ts when email is null
@codespar fix the CORS headers are missing on the /api/upload endpoint

Both commands follow the same flow internally — the distinction is semantic, helping the agent understand whether you want new code or a fix to existing code.

How It Works

When you send a command, the Dev Agent executes this flow:

1. Extract keywords from your instruction
2. Search repository for relevant files (GitHub Code Search)
3. Read the top 5 files (max 20KB each)
4. If no files found via search, browse the file tree
5. Build a prompt with your instruction + file contents
6. Send to Claude Sonnet for code generation
7. Parse Claude's response for file changes
8. Create branch: codespar/<taskId>
9. Commit changes via GitHub API
10. Open PR with description
11. Report back with PR URL and summary

For a deeper technical explanation, see the Dev Agent documentation.

The Dev Agent creates a new src/routes/health.ts file with a health check handler and modifies src/routes/index.ts to register the new route. The PR description includes the list of changes and a note that it was generated by CodeSpar.

Example 2: Fix a Bug

Command:

@codespar fix the auth middleware is not checking token expiry

Agent Response:

Task completed:
- Branch: codespar/task-a1b2c3
- Files changed:
  - src/middleware/auth.ts (modified)
- PR: https://github.com/acme/api/pull/16

Added token expiry check in validateToken(). Tokens past their
exp claim now return 401 Unauthorized instead of being accepted.

Example 3: Refactor

Command:

@codespar instruct refactor the user service to use dependency injection

Agent Response:

Task completed:
- Branch: codespar/task-g7h8i9
- Files changed:
  - src/services/user.service.ts (modified)
  - src/services/types.ts (new — interfaces for DI)
  - src/container.ts (new — DI container setup)
- PR: https://github.com/acme/api/pull/17

Extracted UserRepository and EmailService interfaces. UserService
now accepts dependencies via constructor injection instead of
importing concrete implementations directly.

Response Format

The Dev Agent always responds with:

Field	Description
Branch	The `codespar/<taskId>` branch where changes were committed
Files changed	List of files with action (new, modified, deleted)
PR URL	Direct link to the pull request on GitHub
Summary	Brief description of what was changed and why

After the PR is Created

Review the Code

Always review the generated PR before merging. The Dev Agent produces good code but is not infallible.

Automated Review

You can ask the Review Agent to analyze the PR:

@codespar review PR #15

The Review Agent will:

Fetch the PR diff
Classify the risk level (low, medium, high)
Provide specific code review comments
Suggest improvements

CI Checks

If your repository has CI configured (GitHub Actions, etc.), the PR will trigger your normal CI pipeline. The CodeSpar webhook integration will notify you of the result.

Iterate

If the PR needs changes, you can send another instruction:

@codespar instruct in PR #15, also add a /api/ready endpoint

Or fix specific issues:

@codespar fix in PR #15 the health check should also verify Redis connectivity

Tips for Best Results

Be Specific About Location

Instead of:

@codespar instruct add error handling

Be specific:

@codespar instruct add try-catch error handling to the createUser function in src/services/user.service.ts

Mention File Paths

The Dev Agent's code search works well, but explicitly mentioning file paths ensures it reads the right files:

@codespar fix the timeout in src/config/session.ts should be 24 hours not 30 seconds

Reference Existing Patterns

If your codebase has established patterns, reference them:

@codespar instruct add a /api/teams endpoint following the same pattern as src/routes/users.ts

Keep Tasks Focused

One task = one well-defined change. Instead of:

@codespar instruct add authentication, authorization, and rate limiting

Break it into three commands:

@codespar instruct add JWT authentication middleware
@codespar instruct add role-based authorization to protected routes
@codespar instruct add rate limiting to all API endpoints

Specify the Framework

If the agent needs to know framework specifics:

@codespar instruct add a WebSocket handler using Fastify's websocket plugin
@codespar instruct create a server action in the Next.js app router for form submission

Limitations

Limitation	Detail
5 files maximum	The agent reads at most 5 files for context
20 KB per file	Large files (generated code, bundles) are skipped
4,000 output tokens	Claude's response is capped, limiting very large changes
No binary files	Cannot generate images, compiled assets, etc.
Single repo	Each task operates on one repository

For tasks that exceed these limits, break the work into smaller, focused tasks.

Merging PRs from Chat

After reviewing a pull request (either manually or via the Review Agent), you can merge it directly from your messaging channel:

@codespar merge PR #42

This uses the repository's default merge strategy. You can also specify a merge strategy explicitly:

@codespar merge PR #42 squash
@codespar merge PR #42 rebase

Example flow:

@codespar instruct add a health check endpoint at /api/health
  → PR #42 opened

@codespar review PR #42
  → Review: approve with suggestions

@codespar merge PR #42 squash
  → PR #42 merged (squash) into main

The merge command checks that the PR exists, that CI checks have passed (if configured), and that you have the required permissions before proceeding.

Next Steps

Dev Agent -- technical deep dive into the Dev Agent
Review Pull Requests -- automated PR review
Approval System -- configure approval workflows
Command Reference -- full list of all commands

Creating PRs with the Dev Agent

Creating PRs with the Dev Agent

Prerequisites

Verify Setup

Commands

`@codespar instruct <task>`

`@codespar fix <issue>`

How It Works

Examples

Example 1: Add an Endpoint

Example 2: Fix a Bug

Example 3: Refactor

Response Format

After the PR is Created

Review the Code

Automated Review

CI Checks

Iterate

Tips for Best Results

Be Specific About Location

Mention File Paths

Reference Existing Patterns

Keep Tasks Focused

Specify the Framework

Limitations

Merging PRs from Chat

Next Steps

On this page