Run Agents Locally

Looking for the easiest way to create and manage agents? Cloud Agents in Mission Control are recommended for most teams. This guide covers local agents—agent files stored in your repository—for open source users or teams needing version-controlled definitions.

What You'll Build

A local agent system that:

Keeps agent definitions version-controlled alongside your code
Runs agents with Continue CLI for local development
Automates agent execution on pull requests via GitHub Actions
Applies consistent workflows across your team

Prerequisites

Before starting, ensure you have:

Continue CLI installed (npm i -g @continuedev/cli)
ANTHROPIC_API_KEY environment variable set
GitHub CLI installed locally if your agents interact with GitHub (pre-installed on GitHub-hosted runners)

Quick Setup

Create the agents directory

mkdir -p .continue/agents

Create your first agent

Create a markdown file with YAML frontmatter defining the agent’s behavior:

touch .continue/agents/my-agent.md

Add content like:

---
name: My First Agent
description: Describes what this agent does
---

You are an agent that helps with [specific task].

## Your Task

1. First, do this
2. Then, do that
3. Finally, complete this

## Guidelines

- Follow this pattern
- Avoid this anti-pattern

Run the agent

cn -p --agent .continue/agents/my-agent.md

For interactive development (TUI mode):

cn --agent .continue/agents/my-agent.md

Agent File Format

Agent files are markdown documents with YAML frontmatter. The frontmatter configures the agent, and the markdown body contains the prompt instructions.

Frontmatter Options

Field	Required	Description
`name`	Yes	Display name for the agent
`description`	Yes	Brief description of what the agent does

The markdown body is the agent’s system prompt. Write clear, specific instructions with examples for best results.

For additional options like rules, model, and MCP tool configuration, see the Agent Configuration Reference.

Example: Conventional PR Title Agent

This agent updates pull request titles to follow conventional commit format:

---
name: Conventional Title
description: Updates PR title to follow conventional commit format
---

You are reviewing a pull request to format its title according to conventional commit standards.

## Your Task

1. **Get the current PR title and number:**
   ```bash
   gh pr view --json number,title -q '{number: .number, title: .title}'
   ```

2. **Get the PR diff to understand changes:**
   ```bash
   git diff origin/main...HEAD --name-only
   ```

3. **Analyze the changes to determine type:**
   - `feat`: New feature
   - `fix`: Bug fix
   - `docs`: Documentation only
   - `refactor`: Code refactoring
   - `chore`: Build, tooling, configs

4. **Update the PR title:**
   ```bash
   gh pr edit PR_NUMBER --title "type: description"
   ```

## Rules

- If title already follows format, do NOT modify
- Keep description under 72 characters
- Use lowercase, no period at end

GitHub Actions Integration

Continue provides a reusable workflow that handles agent discovery, parallel execution, and GitHub Check reporting.

Using the Reusable Workflow

Create .github/workflows/run-agents.yml:

name: Run Agents

on:
  pull_request:
    types: [opened, reopened, synchronize]
    branches:
      - main

jobs:
  agents:
    uses: continuedev/continue/.github/workflows/continue-agents.yml@main
    secrets:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

The reusable workflow automatically:

Discovers all .md files in .continue/agents/
Runs each agent in parallel
Creates GitHub Check runs for each agent
Provides GH_TOKEN for agents using the gh CLI
Writes job summaries with agent output

Configuration Options

jobs:
  agents:
    uses: continuedev/continue/.github/workflows/continue-agents.yml@main
    with:
      agents-path: '.continue/agents'  # Custom agents directory (optional)
    secrets:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Required Secrets

Add this secret to your repository under Settings > Secrets and variables > Actions:

Secret	Description
`ANTHROPIC_API_KEY`	Your Anthropic API key for Claude

The reusable workflow automatically provides GH_TOKEN via ${{ github.token }}, so agents using the gh CLI work out of the box.

Security Considerations

Agents can execute commands and modify files. Review these security practices before deploying to CI/CD.

Limit Agent Permissions

When running agents in CI/CD, follow the principle of least privilege:

GitHub Actions Permissions
CLI Tool Permissions
Environment Variables

Only grant the permissions your agent needs:

permissions:
  contents: read      # Read repository files
  pull-requests: write # Comment on PRs
  # Avoid: contents: write unless agent needs to push commits

Avoid granting contents: write unless your agent specifically needs to push commits. This prevents accidental or malicious code modifications.

Use cn permission flags to restrict what agents can do:

# Only allow specific tools
cn --allow "Read()" --allow "Grep()" --exclude "Bash()" \
   --agent .continue/agents/analysis-only.md

Learn more in the CLI documentation.

Never commit secrets. Use GitHub Actions secrets or environment variables:

env:
  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  GH_TOKEN: ${{ github.token }}  # Scoped to the repo

Never hardcode API keys in agent files or workflows. Always use secrets management.

Review Agent Outputs

Before enabling fully automated agents:

Test locally first - Run agents with cn to verify behavior
Review CI logs - Check what commands agents execute in your workflows
Start with read-only agents - Begin with agents that analyze rather than modify

For high-risk operations (like pushing commits or modifying infrastructure), consider requiring manual approval steps in your workflow.

Environment Variables

When running agents locally, set these environment variables:

# Required: Your Anthropic API key
export ANTHROPIC_API_KEY=your-api-key

# Optional: GitHub token if your agents use the gh CLI
export GH_TOKEN=$(gh auth token)

cn --agent .continue/agents/my-agent.md

Directory Structure

A typical setup looks like:

your-repo/
├── .continue/
│   └── agents/
│       ├── conventional-title.md
│       ├── deploy-checklist.md
│       └── security-scan.md
├── .github/
│   └── workflows/
│       └── continue-agents.yml
└── ...

Troubleshooting

Agent not found

Ensure the path is correct and the file exists:

ls -la .continue/agents/

The path must be relative to your repository root.

GitHub CLI authentication errors

If agents using gh fail, verify authentication:

# Check auth status
gh auth status

# Set token for local testing
export GH_TOKEN=$(gh auth token)

In GitHub Actions, ensure GH_TOKEN: ${{ github.token }} is set in the environment.

Agent runs but doesn't complete the task

Simplify the prompt and add more specific instructions
Check if the agent has access to required tools
Enable verbose logging: cn --verbose --agent .continue/agents/my-agent.md
Review logs with cn --verbose or check the Continue logs directory

Workflow doesn't discover agents

Verify your agents are in the correct directory:

find .continue/agents -name "*.md" -type f

The workflow looks for .md files in .continue/agents/.

Best Practices

Start Simple

Begin with read-only agents that analyze code before adding agents that make changes.

Test Locally

Always run cn --agent locally before enabling CI automation.

Use Descriptive Names

The name field in frontmatter is displayed to users. Use descriptive filenames for organization: conventional-title.md, security-scan.md.

Keep Agents Focused

Each agent should do one thing well. Combine multiple agents for complex workflows.

Next Steps

Agent Overview

Learn about agent components and capabilities

CLI Reference

Full Continue CLI documentation

MCP Tools

Add external tools to your agents

Rules

Configure agent behavior with rules

Getting Started

Cloud Agents

Guides

Run Agents Locally

What You'll Build

Prerequisites

Quick Setup

Agent File Format

Frontmatter Options

Example: Conventional PR Title Agent

GitHub Actions Integration

Using the Reusable Workflow

Configuration Options

Required Secrets

Security Considerations

Limit Agent Permissions

Review Agent Outputs

Environment Variables

Directory Structure

Troubleshooting

Best Practices

Start Simple

Test Locally

Use Descriptive Names

Keep Agents Focused

Next Steps

Agent Overview

CLI Reference

MCP Tools

Rules

Getting Started

Cloud Agents

Guides

What You'll Build

​Prerequisites

​Quick Setup

​Agent File Format

​Frontmatter Options

​Example: Conventional PR Title Agent

​GitHub Actions Integration

​Using the Reusable Workflow

​Configuration Options

​Required Secrets

​Security Considerations

​Limit Agent Permissions

​Review Agent Outputs

​Environment Variables

​Directory Structure

​Troubleshooting

​Best Practices

Start Simple

Test Locally

Use Descriptive Names

Keep Agents Focused

​Next Steps

Agent Overview

CLI Reference

MCP Tools

Rules

Prerequisites

Quick Setup

Agent File Format

Frontmatter Options

Example: Conventional PR Title Agent

GitHub Actions Integration

Using the Reusable Workflow

Configuration Options

Required Secrets

Security Considerations

Limit Agent Permissions

Review Agent Outputs

Environment Variables

Directory Structure

Troubleshooting

Best Practices

Next Steps