Auto-Coder

A Python application that automates application development using an AI CLI backend. It retrieves issues and error-related PRs from GitHub to build and fix the application, and automatically creates feature-addition issues when necessary.

Features

🔧 Core Features

GitHub API Integration: Automatic retrieval and management of issues and PRs
AI Analysis (multiple backends configurable via configuration file): Automatic analysis of issue and PR content
Automated Processing: Automatic actions based on analysis results
Feature Proposals: Automatic proposal of new features from repository analysis
Report Generation: Detailed reports of processing results
PR Mergeability Handling: Automated detection and remediation of non-mergeable PRs through base branch updates and intelligent conflict resolution

🚀 Automated Workflow

Issue Processing: Retrieve open issues and analyze with Gemini AI
PR Processing: Retrieve open PRs and evaluate risk levels
Feature Proposals: Propose new features from repository context
Automatic Actions: Add comments or auto-close based on analysis results

🔄 PR Mergeability Handling

Auto-Coder includes intelligent handling for PRs that are not immediately mergeable. When a PR is detected as non-mergeable, the system can automatically:

Detect and Analyze: Checks PR mergeability status and merge state (CLEAN, DIRTY, UNKNOWN)
Checkout PR Branch: Switches to the PR branch for local processing
Update from Base: Fetches and merges the latest changes from the base branch
Resolve Conflicts: Uses specialized handlers for different conflict types:
- Package-lock conflicts: Automatically deletes and regenerates lock files (package-lock.json, yarn.lock, pnpm-lock.yaml)
- Package.json dependency conflicts: Intelligently merges dependency sections, preferring newer versions
- General conflicts: Uses LLM to resolve remaining conflicts with context
Push Changes: Commits and pushes the updated branch with automatic retry logic
Signal Completion: Sets ACTION_FLAG:SKIP_ANALYSIS marker after successful remediation

This feature is controlled by the ENABLE_MERGEABILITY_REMEDIATION configuration flag. When enabled, non-mergeable PRs are automatically remediated without manual intervention.

Related Configuration:

ENABLE_MERGEABILITY_REMEDIATION (default: true) - Enables automatic remediation
SKIP_MAIN_UPDATE_WHEN_CHECKS_FAIL (default: true) - Controls base branch updates during fix flows

See docs/client-features/ for complete technical documentation. Operators can use the ChatGPT-assisted review-adjudication guide to publish an explicitly authorized decision without a local CLI.

📊 Logging and Monitoring

Real-time Dashboard: Visualize queue status and active workers at http://localhost:8000/dashboard/. See docs/DASHBOARD.md for details.
Structured JSON Logs: All LLM interactions are logged in JSON Lines format at ~/.auto-coder/logs/llm_output.jsonl
User-Friendly Output: Execution summaries are printed to console for immediate feedback
Rich Metadata: Each log entry includes timestamp, backend, model, prompt/response lengths, duration, and status
Environment Control: Toggle logging via AUTO_CODER_LLM_OUTPUT_LOG_ENABLED environment variable
Error Tracking: Detailed error information for failed requests
Easy Analysis: Machine-readable format for parsing with jq or custom scripts

🩺 Run Diagnostics (why a long run stopped)

Long sessions always leave diagnostics behind in ~/.auto-coder/logs/:

File	Contents
`auto-coder.log`	Application log, written even without `--log-file` (10 MB rotation, 14 days retention)
`health-YYYY-MM-DD.jsonl`	One JSON record per minute: RSS/peak memory, system and cgroup memory, open file descriptors, threads, child processes, asyncio tasks, CPU time, plus events such as signals, stalls, restarts and exits
`diagnostics-<pid>.log`	`faulthandler` output: native crashes and on-demand thread dumps

# Summary of the last run: memory trend, peak resources and why it stopped
auto-coder health

# Dump the stacks of every thread of a running (possibly stuck) process
kill -USR1 <pid>

Useful environment variables:

AUTO_CODER_HEALTH_INTERVAL_SECONDS (default 60): snapshot interval
AUTO_CODER_HEALTH_STALL_SECONDS (default 3600): report a stall and dump thread stacks when no progress is made
AUTO_CODER_HEALTH_TRACEMALLOC=1: log the top allocation sites with each snapshot to locate a memory leak
AUTO_CODER_FILE_LOG_LEVEL=DEBUG: keep a detailed on-disk trace while the console stays at INFO
AUTO_CODER_LOG_FILE, AUTO_CODER_HEALTH_LOG_DIR: change where the files are written
AUTO_CODER_HEALTH_LOG_ENABLED=0: disable health logging entirely

Installation

Prerequisites

Python 3.9 or higher
gh CLI pre-authenticated (gh auth login)
Codex CLI installed (default backend)
Antigravity CLI required when using Gemini backend (antigravity login)

Setup

Clone the repository:

git clone https://github.com/your-username/auto-coder.git
cd auto-coder

curl -LsSf https://astral.sh/uv/install.sh | sh uv sync

Install dependencies and make it executable from any directory:

source ./venv/bin/activate
pip install -e .
# Or install directly without cloning the repository
pip install git+https://github.com/your-username/auto-coder.git

Note (PEP 668 avoidance/recommended): In environments where system Python is externally managed and pip install is blocked, we recommend installation via pipx.

Example for Debian/Ubuntu:
sudo apt update && sudo apt install -y pipx
pipx ensurepath   # Restart/re-login to shell if needed
pipx install git+https://github.com/kitamura-tetsuo/auto-coder.git
auto-coder --help

Create configuration file if needed:

cp .env.example .env
# Tokens can be left blank as gh and gemini authentication information is used automatically

Usage

CLI Commands

`process-issues`

Process GitHub issues and PRs using AI CLI.

auto-coder process-issues [OPTIONS]

Options:

--repo TEXT: GitHub repository (owner/repo). Auto-detected if not specified.
--github-token TEXT: GitHub API token.
--jules-mode / --no-jules-mode: Run in jules mode (default: on).
--disable-labels / --no-disable-labels: Disable GitHub label operations (default: false).
--skip-main-update / --no-skip-main-update: Skip merging base branch into PR when checks fail (default: skip).
--ignore-dependabot-prs / --no-ignore-dependabot-prs: Skip all dependency-bot PRs (Dependabot/Renovate/[bot]), including ready ones (default: false).
--auto-merge-dependabot-prs / --no-auto-merge-dependabot-prs: When --no-ignore-dependabot-prs is set, only process dependency-bot PRs that have passing tests and are mergeable. If disabled, attempt to fix failing PRs (default: enabled).
--force-clean-before-checkout / --no-force-clean-before-checkout: Force clean workspace before checkout (default: false).
--only TEXT: Process only a specific issue/PR by URL or number.
--log-level [DEBUG|INFO|WARNING|ERROR|CRITICAL]: Set logging level (default: INFO).
--log-file TEXT: Log file path.
--verbose: Enable verbose logging.

`create-feature-issues`

Analyze repository and create feature enhancement issues.

auto-coder create-feature-issues [OPTIONS]

Options:

--repo TEXT: GitHub repository.
--disable-labels / --no-disable-labels: Disable GitHub label operations.
--log-level: Set logging level.
--verbose: Enable verbose logging.

`fix-to-pass-tests`

Run local tests and repeatedly request LLM fixes until tests pass.

auto-coder fix-to-pass-tests [OPTIONS]

Options:

--disable-labels / --no-disable-labels: Disable GitHub label operations.
--max-attempts INTEGER: Maximum fix attempts.
--log-level: Set logging level.
--verbose: Enable verbose logging.

Dependabot PR Handling

Auto-Coder handles dependency-bot PRs (Dependabot, Renovate, or any bot account ending with [bot]) based on the following configuration:

Configuration	Behavior
`--ignore-dependabot-prs`	Skip all dependency-bot PRs (both ready and non-ready)
`--no-ignore-dependabot-prs --auto-merge-dependabot-prs` (default)	Only process dependency-bot PRs with passing tests and mergeable state. These PRs will be auto-merged. Non-ready PRs are skipped.
`--no-ignore-dependabot-prs --no-auto-merge-dependabot-prs`	Process all dependency-bot PRs, attempting to fix failing ones

Default Behavior:

With default settings, Auto-Coder will:

Detect dependency-bot PRs by author name
Check if tests are passing and PR is mergeable
If yes → automatically merge the PR
If no → skip the PR (do nothing)

This ensures dependency updates are merged quickly when safe, without manual intervention.

Authentication

Basically, just run gh auth login. When using the Gemini backend, running antigravity login allows you to use it without setting API keys in environment variables (the --model flag is ignored for the codex backend).

Regarding Qwen Usage (Authentication)

Qwen OAuth (recommended):
- Run qwen once, and after authenticating your qwen.ai account in the browser, it will be automatically available.
- Running the /auth command midway will switch to Qwen OAuth.
- Reference: Qwen Code official repository (Authorization section): https://github.com/QwenLM/qwen-code
Automatic fallback when limits are reached:
- Auto-Coder prioritizes configured OpenAI-compatible endpoints and only returns to Qwen OAuth when all API keys are exhausted.
- Configuration file location: ~/.auto-coder/qwen-providers.toml (path can be overridden with AUTO_CODER_QWEN_CONFIG, directory can be specified with AUTO_CODER_CONFIG_DIR).
- TOML example:
```
[[qwen.providers]]
# Option 1: Alibaba Cloud ModelStudio
name = "modelstudio"
api_key = "dashscope-..."  # Set the obtained API key
# base_url and model can be omitted to use defaults (dashscope-compatible / qwen3-coder-plus)

[[qwen.providers]]
# Option 2: OpenRouter Free Tier
name = "openrouter"
api_key = "openrouter-..."
model = "qwen/qwen3-coder:free"  # Uses default when omitted
```
- Fallback occurs in the order written (API key → OAuth). If only API keys are filled in, default URL/model is applied, and OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL are automatically injected at runtime.
OpenAI-compatible mode:
- Available by setting the following environment variables.
  - OPENAI_API_KEY (required)
  - OPENAI_BASE_URL (specify according to provider)
  - OPENAI_MODEL (example: qwen3-coder-plus)
- The Qwen backend of this tool uses non-interactive mode with qwen -p/--prompt, and the model follows the --model/-m flag or OPENAI_MODEL (--model takes precedence if both are specified).

Regarding Auggie Usage

Install CLI with npm install -g @augmentcode/auggie.
This tool calls auggie --print --model <model name> "<prompt>" in non-interactive mode.
Auggie backend calls are limited to 20 per day. The 21st and subsequent calls automatically stop until the date changes and fallback to other backends.
If --model is not specified, GPT-5 is used as the default model. You can override with the --model option to specify any model.

CLI Commands

Processing Issues and PRs

# Run with configuration file defaults
auto-coder process-issues --repo owner/repo

# Process only specific Issue/PR (by number)
auto-coder process-issues --repo owner/repo --only 123

# Process only specific PR (by URL)
auto-coder process-issues --repo owner/repo --only https://github.com/owner/repo/pull/456

Creating Feature Proposal Issues

# Run with configuration file defaults
auto-coder create-feature-issues --repo owner/repo

Auto-fix until tests pass (fix-to-pass-tests)

Run local tests, and if they fail, ask the LLM for minimal fixes and repeatedly re-execute. Stops with an error if the LLM doesn't make any edits.

# Run with configuration file defaults
auto-coder fix-to-pass-tests

# Specify number of attempts (example: max 5 times)
auto-coder fix-to-pass-tests --max-attempts 5

Command Options

`process-issues`

--repo: GitHub repository (owner/repo format)
--skip-main-update/--no-skip-main-update: Switch behavior of whether to merge PR base branch into PR branch before attempting fixes when PR checks fail (default: skip base branch merge).
- Default: --skip-main-update (skip)
- Specify --no-skip-main-update to explicitly perform base branch merge
--ignore-dependabot-prs/--no-ignore-dependabot-prs: Exclude Dependabot PRs from processing (default: do not exclude)
--only: Process only specific Issue/PR (URL or number specification)

Options:

--github-token: Manual specification when not using gh CLI authentication

`create-feature-issues`

--repo: GitHub repository (owner/repo format)

Options:

--github-token: Manual specification when not using gh CLI authentication

`fix-to-pass-tests`

--max-attempts: Maximum number of test fix attempts (uses engine default when omitted)

Behavior Specification:

Test execution uses scripts/test.sh if it exists, otherwise runs pytest -q --maxfail=1.
- scripts/test.sh supports the following features:
  - Prefers using uv runner for consistent, reproducible environments
  - Falls back to system Python's pytest when uv is not installed
  - Can optionally activate local virtual environment by setting AC_USE_LOCAL_VENV=1
  - Always enables automatic dependency synchronization with uv
  - Automatically applies code style fixes (black, isort) when run in local environments (non-CI)
  - Runs code style checks in check-only mode when running in CI environments
For each failure, extracts important parts from error output and asks LLM for minimal fixes.
After fixes, stages and commits. Stops with error if there are no changes at all (nothing to commit).

Lock Management Commands

Auto-Coder includes a lock mechanism to prevent concurrent executions that could cause conflicts or data corruption. When you run an auto-coder command, it automatically acquires a lock to ensure only one instance is running at a time.

Automatic Lock Behavior:

Auto-Coder automatically acquires a lock before executing any command (except read-only commands like config and unlock)
If another instance is already running, you'll see an error message with lock information
The lock is automatically released when the command completes
Lock files are stored in the .git directory of your repository

For Developers: The LockManager class supports Python's context manager protocol for safe lock management:

from auto_coder.lock_manager import LockManager

# Recommended: Using context manager (automatic cleanup)
with LockManager() as lock:
    # Lock is automatically acquired here
    do_work()
# Lock is automatically released here, even if an exception occurs

# Alternative: Manual management
lock = LockManager()
if lock.acquire():
    try:
        do_work()
    finally:
        lock.release()

Manual Lock Control:

# Remove a lock file (use when you know the process has terminated)
auto-coder lock unlock

# Force remove a lock file (use with caution - only if the process is not running)
auto-coder lock unlock --force

Lock Information: When a lock is detected, Auto-Coder displays:

Process ID (PID) of the running instance
Hostname where the process is running
Start time of the process
Status (running or stale)

If the status shows "stale lock" (the process is no longer running), you can safely remove the lock with auto-coder lock unlock. The --force flag should only be used if you're certain the process isn't running or if you need to override a lock for emergency recovery.

Stale Lock Detection: Auto-Coder detects stale locks by checking if the process associated with the lock is still active. If the process has terminated but left behind a lock file, you can remove it without the --force flag. The system will automatically detect that the process is no longer running.

Branch Naming Best Practices

Naming Conventions

Issue Branches

Format: issue-<number> (e.g., issue-699)
Use case: Use for main development work on an issue
Example:
```
git checkout -b issue-699
```

Attempt Branches

Format: issue-<number>_attempt-<number> (e.g., issue-699_attempt-1)
Use case: Use when retrying work after a failed PR merge or regression
Example:
```
git checkout -b issue-699_attempt-1
```

Note: Prior to v1.x.x, attempt branches used slash separator (issue-699/attempt-1). The new underscore format prevents Git errors when both base and attempt branches exist. Both formats are supported for backward compatibility.

Git Ref Namespace Limitations

Git stores branch references as filesystem paths under .git/refs/heads/. This creates a limitation: a path cannot be both a file and a directory.

Conflicting Names ❌

The following branch name combinations will conflict:

Having both issue-699 AND issue-699/attempt-1 (legacy format)
Having both feature AND feature/new-api
Having both pr-123 AND pr-123/fix-typo

Resolution

If you encounter a branch name conflict:

Delete the parent branch:
```
git branch -D issue-699
```
Then create the child branch:
```
git checkout -b issue-699/attempt-1
```
Alternative: Use a different branch name that doesn't conflict

Prevention

Plan your branch naming hierarchy in advance
Clean up old branches regularly
Use consistent naming patterns
Prefer the underscore format for attempt branches to avoid namespace conflicts

Common Scenarios

When to Use Attempt Branches

Use attempt branches when:

Your PR failed CI/CD checks and you need to retry
You discovered a regression after merging
You need to try a different approach to solving the same issue
You want to preserve the original attempt for reference

How to Clean Up Old Branches

# List all local branches
git branch

# Delete a local branch
git branch -d issue-699_attempt-1

# Delete a remote branch
git push origin --delete issue-699_attempt-1

# Bulk delete merged local branches
git branch --merged | grep -v "\*" | xargs -n 1 git branch -d

Recommended Workflow

Initial work: Create issue-<number> branch
If PR fails: Keep the original branch for reference
Retry attempt: Create issue-<number>_attempt-1 from the base branch
Subsequent attempts: Continue with issue-<number>_attempt-2, etc.
After successful merge: Delete old attempt branches locally and remotely

Automated Conflict Detection

As of v1.x.x, auto-coder automatically detects branch name conflicts and provides clear error messages with resolution steps.

# If you see this error:
ERROR: Cannot create branch 'issue-699/attempt-1': conflicts with existing branch 'issue-699'

# Resolve by deleting the conflicting branch:
git branch -D issue-699

The system checks for conflicts before creating new branches and will:

Detect parent-child conflicts: Prevent creating branch/name if branch exists
Detect child conflicts: Prevent creating branch if branch/* branches exist
Provide clear error messages: Include the name of the conflicting branch
Suggest resolution steps: Tell you exactly which branch to delete

Migration from Legacy Format

If you have existing branches with the old slash format (issue-X/attempt-Y), they will continue to work. However, new attempt branches will use the underscore format.

For detailed migration instructions, see the Branch Naming Migration Guide.

To migrate an existing branch manually:

# Rename local branch (legacy slash to underscore)
git branch -m issue-699/attempt-1 issue-699_attempt-1

# Delete old remote branch
git push origin --delete issue-699/attempt-1

# Push renamed branch
git push origin issue-699_attempt-1

Work-in-Progress (WIP) Branch Resumption

When you run auto-coder process from a non-main branch, the system automatically detects work in progress and resumes processing:

Automatic WIP Detection

Detects current branch is not main
Searches for open PR with matching head branch
If PR found, resumes work on that PR
If no PR found, extracts issue number from branch name (e.g., fix/123-description → issue #123)

Parent Issue Auto-Reopen

When processing child issues in a parent-child relationship, Auto-Coder automatically handles closed parent issues:

Auto-Reopen Behavior

When processing a child issue whose parent is closed:

The system automatically reopens the parent issue before continuing
Branch selection and base branch selection use the parent issue context
Attempt tracking operates within the parent issue context
This ensures proper workflow continuity and prevents branch naming conflicts

Why This Matters

This behavior is critical for maintaining consistency when:

Working with hierarchical issue structures
Managing parent-child issue dependencies
Ensuring branch and attempt tracking remain coherent
Preventing branch naming and base selection issues during child issue processing

Example

If you have issue #100 (parent) with child issue #101:

Issue #101 is being processed
Issue #100 (parent) is closed
Auto-Coder automatically reopens #100
All branch operations and attempts now use #100's context
Processing continues with proper parent context maintained

Parent Issue Context Injection

When processing sub-issues (child issues), Auto-Coder automatically injects parent issue context into LLM prompts to help maintain awareness of the broader context.

What is Parent Issue Context?

Parent Issue Context is a feature that automatically retrieves and includes a parent issue's description and details when processing its sub-issues. This gives the LLM a complete understanding of the larger goal while maintaining focus on the specific sub-issue implementation.

When and Why It's Used

When:

Only for sub-issues (issues that have a parent issue)
Automatically detected and applied during issue processing
Works across all prompt types (default, bug fix, urgent, breaking-change)

Why:

Helps the LLM understand the broader context and goals
Ensures sub-issue implementations align with parent requirements
Provides visibility into the overall feature or project scope
Enables better decision-making during implementation

How It Works

When processing a sub-issue:

Detection: Auto-Coder detects if the issue has a parent using GitHub's sub-issues API
Context Retrieval: Fetches the parent issue's title, body, and details
Prompt Injection: Injects parent context into the LLM prompt with explicit scope limitations
LLM Processing: The LLM receives both sub-issue and parent context to make informed decisions

Scope Limitations

To prevent over-implementation, the feature includes explicit scope limitations in the prompt:

PARENT ISSUE CONTEXT (CONTEXT ONLY - DO NOT IMPLEMENT):
This issue is a sub-issue of #<parent_number>: <parent_title>

Parent Issue Description:
<parent_body>...

IMPORTANT SCOPE LIMITATIONS:
- The parent issue content above is for CONTEXT ONLY
- Implementation must be LIMITED to the current sub-issue scope (Issue #<number>)
- Changes should align with parent goals but only implement the specific requirements of this sub-issue
- Do NOT implement features or changes described in the parent issue unless they are directly relevant to this sub-issue

Example Scenario

Parent Issue #200: "Implement user authentication system"

Sub-Issue #201: "Add password reset functionality"

When processing sub-issue #201:

The LLM receives context about the parent authentication system
Understands that password reset is part of a larger authentication feature
Remains focused on implementing only the password reset functionality
Ensures the implementation aligns with the overall authentication architecture

Benefits

Informed Decisions: LLM can make better implementation choices with full context
Architectural Consistency: Sub-issues align with overall parent goals
Reduced Rework: Fewer implementation conflicts between parent and children
Better Testing: Tests consider parent context for more comprehensive coverage

Technical Details

Uses GitHub's GraphQL API with the sub_issues feature flag
Retrieves parent issue via get_parent_issue_details() and get_parent_issue_body()
Injects context into all label-based prompts (default, bug, urgent, breaking-change, etc.)
Does not affect regular issues without parent issues
Branch and attempt tracking also respect parent-child relationships

For complete technical documentation, see docs/parent_issue_context.md.

Configuration

Configuration File Locations

Auto-Coder supports configuration files in multiple locations with the following priority:

Local configuration (highest priority): .auto-coder/llm_config.toml in the current directory
Home configuration: ~/.auto-coder/llm_config.toml in your home directory
Default configuration: Auto-generated if no configuration file exists

When to Use Local Configuration

Use local configuration (.auto-coder/llm_config.toml) when:

You need project-specific LLM backend settings
You want to version-control your configuration with your project
You're working in a team and want to share configuration
You're testing different configurations without affecting global settings
You're working in container/CI environments where configuration should be part of the project

When to Use Home Configuration

Use home configuration (~/.auto-coder/llm_config.toml) when:

You want the same configuration across all projects
You're working on personal projects with consistent settings
You want to keep API keys and credentials out of project repositories

Configuration Search Behavior

When Auto-Coder starts, it searches for configuration files in this order:

Checks if .auto-coder/llm_config.toml exists in the current working directory
If not found, falls back to ~/.auto-coder/llm_config.toml in the home directory
If neither exists, creates a default configuration in the home directory

This approach is backward compatible: existing users with only home directory configs will see no change in behavior.

Configuration File (TOML)

Auto-Coder uses a TOML configuration file for backend settings. You can place this file in either location mentioned above.

Note: By default, all backends have enabled = true. You only need to specify enabled = false to disable a backend.

Custom Backend Names

You can define custom backend names using the backend_type field. This is useful for:

Using OpenRouter with specific model names
Configuring multiple versions of the same backend
Using OpenAI-compatible providers

Example:

[backends.grok-4.1-fast]
backend_type = "codex"  # Use codex CLI for OpenAI-compatible APIs
model = "grok-4.1-fast"
openai_api_key = "your-openrouter-api-key"
openai_base_url = "https://openrouter.ai/api/v1"

Supported backend_type values: codex, codex-mcp, gemini, qwen, auggie, claude

For detailed configuration examples and troubleshooting, including the new fallback backend feature, see:

Configuration Guide - General configuration overview
Configuration File Format Guide - Detailed guide on configuration file format and placeholder system

Configuring Model Provider

For backends using backend_type = "codex", you can specify the model provider using the model_provider field. This tells the codex CLI which provider to use when making API calls.

Example: Using OpenRouter

[grok-4.1-fast]
enabled = true
model = "x-ai/grok-4.1-fast:free"
backend_type = "codex"
model_provider = "openrouter"

This configuration is equivalent to running:

codex -c model="x-ai/grok-4.1-fast:free" -c model_provider=openrouter

Supported Providers

The model_provider field supports any provider that the codex CLI recognizes, such as:

openrouter - For OpenRouter API
anthropic - For Anthropic Claude
openai - For OpenAI models

Note: You still need to configure provider-specific settings (like API endpoints and authentication) in your codex configuration file (~/.codex/config.toml) or via environment variables. The model_provider field simply tells codex which provider configuration to use.

Complete Example with OpenRouter

Here's a complete example showing how to configure a custom backend with OpenRouter:

[backends.openrouter-grok]
enabled = true
backend_type = "codex"
model = "x-ai/grok-4.1-fast:free"
model_provider = "openrouter"
openai_api_key = "sk-or-v1-..."  # Your OpenRouter API key
openai_base_url = "https://openrouter.ai/api/v1"

Make sure your codex configuration file (~/.codex/config.toml) contains the appropriate provider settings. For example:

# ~/.codex/config.toml
[openrouter]
api_base = "https://openrouter.ai/api/v1"
default_model = "x-ai/grok-4.1-fast:free"

Check the codex CLI documentation for the full list of supported providers and their configuration options.

Configuration Management

Automatic package updates are enabled by default. To disable them, add this to .auto-coder/config.toml (project-local) or ~/.auto-coder/config.toml:

[auto_update]
enabled = false

Set enabled = true to turn them back on. The existing AUTO_CODER_DISABLE_AUTO_UPDATE=1 environment variable always disables updates, regardless of this setting.

To manage the configuration file, use the built-in config commands:

# Show current configuration
auto-coder config show

# Edit configuration file
auto-coder config edit

# Validate configuration
auto-coder config validate

# Create backup of configuration
auto-coder config backup

# Interactive setup wizard
auto-coder config setup

# Show usage examples
auto-coder config examples

# Migrate from environment variables
auto-coder config migrate

Note: If you're migrating from an older configuration format with message_backend section, see the Migration Guide for CLI Options for detailed instructions.

Example configuration file (.auto-coder/llm_config.toml or ~/.auto-coder/llm_config.toml):

version = "1.0.0"
created_at = "2023-01-01T00:00:00"
updated_at = "2023-01-01T00:00:00"

[backend]
order = ["agy", "qwen", "claude"]
default = "antigravity"

[backends.codex]
api_key = ""
base_url = ""
model = "codex"
temperature = 0.7
timeout = 30
max_retries = 3
usage_limit_retry_count = 0
usage_limit_retry_wait_seconds = 0

[backends.codex_mcp]
api_key = ""
base_url = ""
model = "codex-mcp"
temperature = 0.7
timeout = 30
max_retries = 3
usage_limit_retry_count = 0
usage_limit_retry_wait_seconds = 0

[backends.gemini]
api_key = "your-gemini-api-key"  # Alternatively use GEMINI_API_KEY env var
base_url = ""
model = "gemini-2.5-pro"
temperature = 0.7
timeout = 30
max_retries = 3
usage_limit_retry_count = 3
usage_limit_retry_wait_seconds = 30
always_switch_after_execution = false

[backends.qwen]
api_key = "your-qwen-api-key"  # Alternatively use OPENAI_API_KEY env var
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"  # Or your OpenAI-compatible endpoint
model = "qwen3-coder-plus"
temperature = 0.7
timeout = 30
max_retries = 3
usage_limit_retry_count = 2
usage_limit_retry_wait_seconds = 60
always_switch_after_execution = false

[backends.claude]
api_key = "your-claude-api-key"  # Alternatively use ANTHROPIC_API_KEY env var
base_url = ""
model = "sonnet"
temperature = 0.7
timeout = 30
max_retries = 3
usage_limit_retry_count = 5
usage_limit_retry_wait_seconds = 45

[backends.auggie]
api_key = ""
base_url = ""
model = "GPT-5"
temperature = 0.7
timeout = 30
max_retries = 3
usage_limit_retry_count = 1
usage_limit_retry_wait_seconds = 120

[message_backend]
order = ["claude"]
default = "claude"

Supported Backend Types

Auto-Coder supports multiple backend types. When using custom backend names, you must specify the backend_type field:

Backend Type	Description	Required Tools	Use Cases
`codex`	OpenAI Codex and OpenAI-compatible APIs	Codex CLI	OpenRouter, Azure OpenAI, custom endpoints
`codex-mcp`	Codex with MCP support	Codex CLI	Advanced MCP integrations
`gemini`	Google Gemini	Antigravity CLI	Direct Google API integration
`qwen`	Qwen Code	Qwen CLI	Native Qwen CLI with OAuth
`claude`	Anthropic Claude	Claude CLI	Direct Anthropic API integration
`jules`	Jules AI Assistant	Jules CLI	Session-based AI with PR feedback loop
`auggie`	Auggie	Auggie CLI (`npm install -g @augmentcode/auggie`)	Auggie integration

Important: Custom backend names require the backend_type field. Standard backend names (codex, gemini, qwen, claude, jules, auggie) work without this field.

For more details, see:

Jules Mode Configuration

Jules mode is a special operational mode that adds the jules label to issues and processes them using the Jules AI assistant. Jules mode can be enabled in two ways:

1. CLI Flag (Per-Command)

You can enable or disable Jules mode for each command using the --jules-mode or --no-jules-mode flag:

# Enable Jules mode (default: ON)
auto-coder process-issues --jules-mode

# Disable Jules mode
auto-coder process-issues --no-jules-mode

Jules mode is ON by default for process-issues commands.

2. Configuration File (Persistent)

You can configure Jules as a backend in your llm_config.toml file for persistent settings:

[backend]
# Add jules to your backend order
order = ["jules", "antigravity", "codex", "claude"]
default = "codex"

[backends.jules]
enabled = true
backend_type = "jules"
# No additional configuration needed - uses Jules CLI with OAuth

Configuration Options:

enabled: Set to true to enable Jules backend, false to disable (default: true)
backend_type: Must be set to "jules" for Jules backend configuration
model: Optional - Jules model name (defaults to Jules CLI default)
temperature: Optional - Controls randomness (default: 0.7)
timeout: Optional - Request timeout in seconds (default: 300)
max_retries: Optional - Maximum retry attempts (default: 3)

Notes:

Jules uses OAuth authentication - no API keys required
Requires Jules CLI to be installed and authenticated
Sessions are tracked in ~/.auto-coder/<repo>/cloud.csv files
Jules automatically comments on issues with session information

Issue timeout fallback:

When a Jules session works on an issue for longer than [jules].issue_pr_timeout_hours (default: 12) without opening a pull request, Auto-Coder sends a stop message to the session, increments the attempt counter of the issue, and implements the issue with the backend_with_high_score backend instead. The @auto-coder label stays on the issue for the whole hand-over so no other instance starts working on it in parallel:

# config.toml
[jules]
issue_pr_timeout_hours = 12

Sessions that already produced a PR, issues that already have a linked PR, and closed issues are never taken away from Jules.

For more details about Jules mode architecture and migration from legacy Jules label logic, see the Migration Guide: v2026.2.0.

Retry Configuration

Auto-Coder supports automatic retry on usage limit errors for LLM backends. This feature helps handle temporary rate limits or quota exhaustion by allowing backends to retry requests before rotating to the next available backend.

Configuration Fields

Each backend in the TOML configuration file can specify retry behavior using these fields:

usage_limit_retry_count: Number of times to retry when a usage limit error is encountered (default: 0)
- Set to 0 to disable retries (immediately rotate to next backend)
- Set to a positive number to retry on the same backend before rotating
usage_limit_retry_wait_seconds: Number of seconds to wait between retry attempts (default: 0)
- This delay allows the backend's usage quota to reset or rate limits to expire
- Recommended values depend on the backend provider's rate limiting policies

Behavior

When retry is configured (usage_limit_retry_count > 0):

Backend encounters a usage limit error
System retries the same backend up to usage_limit_retry_count times
Waits usage_limit_retry_wait_seconds between each retry attempt
If all retries are exhausted, rotates to the next backend in the configured order
Continues through the backend rotation until a successful response is received or all backends are exhausted

When retry is not configured (usage_limit_retry_count = 0, default):

Backend encounters a usage limit error
Immediately rotates to the next backend in the configured order
No retry attempts on the same backend

Example Configuration

The example configuration above demonstrates different retry settings for different backends:

Gemini: Retries 3 times with 30-second delays between attempts
Qwen: Retries 2 times with 60-second delays between attempts
Claude: Retries 5 times with 45-second delays between attempts (more aggressive retry policy)
Auggie: Retries 1 time with 120-second delays (longer wait time due to daily limits)
Codex/Codex-MCP: No retries (0 count, 0 wait) - immediately rotates on usage limits

Recommended Settings

Different LLM providers have different rate limiting behaviors:

Gemini: 3-5 retries with 30-60 second waits typically works well
Claude: 3-5 retries with 30-60 second waits
Qwen: 2-3 retries with 60-120 second waits, especially for API keys
Auggie: 1-2 retries with 120+ seconds (due to strict daily call limits)
Codex: 0-1 retries (OpenAI Codex has strict rate limits)

Adjust these values based on your usage patterns and the specific rate limits of your LLM providers.

Post-Execution Backend Rotation

Enable always_switch_after_execution on individual backends to rotate to the next backend in backend.order after every successful run. This is useful when you want round-robin usage across providers (for example, to spread traffic, avoid hitting soft limits, or comply with single-execution quotas) instead of sticking to the same backend until a failure occurs.

Example:

[backend]
order = ["agy", "qwen", "claude"]
default = "antigravity"

[backends.gemini]
model = "gemini-2.5-pro"
always_switch_after_execution = true  # switch to qwen after each gemini call

[backends.qwen]
model = "qwen3-coder-plus"
always_switch_after_execution = true  # continue rotation to claude next

If always_switch_after_execution is omitted or set to false, Auto-Coder keeps using the active backend until a retry/rotation condition is triggered.

Session Resume Configuration

Auto-Coder supports session resumption for backends that maintain stateful sessions (like Claude). When the same backend is used consecutively, the system can automatically resume the previous session instead of starting a new one, providing better context continuity.

How Session Resume Works

When configured, the system:

Tracks the session ID from the last backend execution
Detects when the same backend is used consecutively
Automatically injects resume options with the previous session ID
The backend resumes the previous session with full context

Configuration

Add the options_for_resume field to your backend configuration in llm_config.toml:

[backends.claude]
model = "sonnet"
# Resume options with session ID placeholder
options_for_resume = ["--resume", "[sessionId]"]

The [sessionId] placeholder will be automatically replaced with the actual session ID from the previous execution.

Example: Claude Backend with Session Resume

[backend]
order = ["claude", "antigravity", "codex"]
default = "claude"

[backends.claude]
enabled = true
model = "sonnet"
timeout = 60
max_retries = 3
# Enable session resume for Claude
options_for_resume = ["--resume", "[sessionId]"]

How It Works

When you run multiple operations consecutively:

# First operation - starts new session
auto-coder process-issues --only 123
# Session ID: abc123 (tracked internally)

# Second operation - resumes previous session
auto-coder process-issues --only 124
# Uses: claude --resume abc123

The second operation automatically resumes session abc123, providing Claude with context from the first operation.

Supported Backends

Currently, session resume is implemented for:

Claude: Uses --resume <session-id> flag

Other backends may support session resume if they provide similar session management capabilities.

Notes

Session IDs are tracked per backend
Session state is persisted to ~/.auto-coder/backend_session_state.json so consecutive executions can resume when the backend supports it
Resume only happens when the same backend is used consecutively
If a different backend is used, the session tracking resets
The options_for_resume list can include multiple options if needed

Timeout Handling and Automatic Backend Fallback

Auto-Coder includes automatic timeout handling that triggers fallback to the next configured backend when an LLM command exceeds its configured timeout. This ensures operations continue smoothly even when a backend becomes unresponsive or slow.

How Timeout Fallback Works

When a timeout occurs:

The current backend command is terminated when it exceeds its configured timeout duration
Auto-Coder catches the AutoCoderTimeoutError exception
The system automatically switches to the next backend in the configured backend.order list
The operation is retried with the new backend
This continues through all configured backends until a successful response is received or all backends are exhausted

Timeout behavior varies by operation:

Normal Operations (process-issues, create-feature-issues):
- Timeouts trigger automatic fallback to the next backend
- System continues through all backends in order
- If all backends timeout, the last timeout error is raised
Test Fix Operations (fix-to-pass-tests):
- Timeouts trigger immediate fallback to the next backend
- Operation is retried once with the new backend
- If the retry also times out, the error is propagated

Example Scenario

With the following configuration:

[backend]
order = ["agy", "qwen", "claude"]
default = "antigravity"

[backends.gemini]
model = "gemini-2.5-pro"
timeout = 30

[backends.qwen]
model = "qwen3-coder-plus"
timeout = 30

[backends.claude]
model = "sonnet"
timeout = 30

Execution flow:

First attempt uses gemini backend
If gemini times out after 30 seconds → automatically switch to qwen
If qwen times out after 30 seconds → automatically switch to claude
If claude succeeds, return the result
If claude also times out, raise the timeout error

Configuration

Timeout values are configured per backend in the TOML configuration file:

[backends.gemini]
model = "gemini-2.5-pro"
timeout = 30  # seconds

Timeout recommendations by provider:

Gemini: 30-60 seconds ( Google's API is generally fast)
Claude: 30-60 seconds (Anthropic's API is responsive)
Qwen: 60-120 seconds (Alibaba's API may need more time)
Codex: 30-60 seconds (OpenAI's Codex is typically fast)
Auggie: 60-120 seconds ( Auggie has daily call limits)

Adjust timeout values based on your network conditions and the complexity of tasks you're running.

Logging

Timeout fallback events are logged for debugging:

WARNING - Timeout error on backend 'antigravity', switching to next backend

Check the logs at ~/.auto-coder/logs/llm_output.jsonl for detailed information about timeout occurrences and backend rotations.

Environment Variables

Environment variables can be used to override configuration file values or provide sensitive information like API keys:

Variable Name	Description	Default Value	Required
`GITHUB_TOKEN`	GitHub API token (to override gh CLI authentication)	-	❌
`GITHUB_API_URL`	GitHub API URL	`https://api.github.com`	❌
`MAX_ISSUES_PER_RUN`	Maximum issues to process per run	`-1`	❌
`MAX_PRS_PER_RUN`	Maximum PRs to process per run	`-1`	❌
`LOG_LEVEL`	Log level	`INFO`	❌
`AUTO_CODER_DEFAULT_BACKEND`	Set default backend (e.g., 'antigravity', 'codex')	`codex`	❌
`AUTO_CODER_<BACKEND>_API_KEY`	Set API key for specific backend	-	❌
`AUTO_CODER_OPENAI_API_KEY`	Set OpenAI-compatible API key	-	❌
`AUTO_CODER_OPENAI_BASE_URL`	Set OpenAI-compatible base URL	-	❌

Backend-specific environment variables:

AUTO_CODER_CODEX_API_KEY, AUTO_CODER_ANTIGRAVITY_API_KEY, AUTO_CODER_QWEN_API_KEY, AUTO_CODER_CLAUDE_API_KEY, AUTO_CODER_AUGGIE_API_KEY
Model-specific variables: AUTO_CODER_<BACKEND>_MODEL (e.g., AUTO_CODER_ANTIGRAVITY_MODEL)

MAX_ISSUES_PER_RUN and MAX_PRS_PER_RUN are set to unlimited (-1) by default. Specify positive integers if you want to limit the number of items processed.

Migration from old environment variables: If you were using the old environment variables (GEMINI_API_KEY, OPENAI_API_KEY, etc.), you can migrate them automatically:

auto-coder config migrate

Logging and Monitoring

Overview

Auto-Coder provides comprehensive logging for all LLM interactions using the LLMOutputLogger class. Logs are written in structured JSON Lines format (one JSON object per line) for easy parsing and analysis.

Default Log Location

~/.auto-coder/logs/llm_output.jsonl

Environment Variable Control

Enable or disable logging using the AUTO_CODER_LLM_OUTPUT_LOG_ENABLED environment variable:

# Enable logging (default)
export AUTO_CODER_LLM_OUTPUT_LOG_ENABLED=1
# or: true, yes, on

# Disable logging
export AUTO_CODER_LLM_OUTPUT_LOG_ENABLED=0
# or: false, no, off

Rotation and retention

The active log is limited to 10 MiB and keeps five 10 MiB archives by default, for a combined maximum of 60 MiB. Set AUTO_CODER_LLM_OUTPUT_LOG_MAX_BYTES (an integer of at least 4096) and AUTO_CODER_LLM_OUTPUT_LOG_BACKUP_COUNT (a nonnegative integer) before constructing a logger to change those independent limits. Invalid values fall back to their respective defaults. Unlike these construction-time settings, the enable variable is reevaluated for every call. Different logger instances can therefore have different effective limits; the defaults are not a global disk quota.

Archives are siblings named llm_output.jsonl.auto-coder-archive.<20-or-more-digit-generation>.jsonl and are ordered by their numeric generation. The logger also owns sibling .auto-coder.lock and .auto-coder-stage.jsonl files. Oversized interactions become bounded JSON summaries with log_record_truncated and original_record_bytes. On first use, malformed, incomplete, or oversized legacy lines can be discarded independently from each segment; records are not repacked between segments. History readers should read archives in numeric generation order and the active path last.

The same naming and retention rules apply to custom paths. Rotation applies only to this structured interaction log and does not include the separate review-audit store.

Example Log Entry

Each log entry contains structured data about an LLM interaction:

{
  "timestamp": "2025-11-24T10:30:45.123Z",
  "event_type": "llm_interaction",
  "backend": "codex",
  "model": "codex",
  "prompt_length": 15420,
  "response_length": 8956,
  "duration_ms": 1234,
  "status": "success"
}

Parsing Logs with jq

# Extract all successful interactions
grep "^{" ~/.auto-coder/logs/llm_output.jsonl | jq 'select(.status == "success")'

# Find errors
grep "^{" ~/.auto-coder/logs/llm_output.jsonl | jq 'select(.status == "error")'

# Filter by backend
grep "^{" ~/.auto-coder/logs/llm_output.jsonl | jq 'select(.backend == "codex")'

# Get statistics
grep "^{" ~/.auto-coder/logs/llm_output.jsonl | jq -r '.backend' | sort | uniq -c

Parsing Logs with Python

import json
from pathlib import Path

log_file = Path.home() / ".auto-coder" / "logs" / "llm_output.jsonl"

# Read all log entries
with log_file.open("r") as f:
    for line in f:
        data = json.loads(line.strip())
        print(f"{data['timestamp']}: {data['backend']} - {data['status']}")

# Filter by backend
with log_file.open("r") as f:
    codex_logs = []
    for line in f:
        data = json.loads(line.strip())
        if data['backend'] == 'codex':
            codex_logs.append(data)

print(f"Found {len(codex_logs)} Codex interactions")

Log Entry Fields

Field	Type	Description
`timestamp`	string	ISO 8601 timestamp with timezone
`event_type`	string	Event type: `llm_request`, `llm_response`, or `llm_interaction`
`backend`	string	Backend name (e.g., "codex", "antigravity", "qwen")
`model`	string	Model name
`prompt_length`	integer	Prompt length in characters
`response_length`	integer	Response length in characters
`duration_ms`	float	Request duration in milliseconds
`status`	string	Request status (e.g., "success", "error")
`error`	string (optional)	Error message if status is "error"
Additional metadata	any	Custom fields from the interaction

Console Output

In addition to JSON log files, Auto-Coder prints user-friendly execution summaries to console:

============================================================
🤖 Codex CLI Execution Summary
============================================================
Backend: codex
Model: codex
Prompt Length: 15420 characters
Response Length: 8956 characters
Duration: 1234ms
Status: SUCCESS
============================================================

This provides immediate feedback during execution while detailed logs are saved to the file.

Custom Log Path

You can configure a custom log path programmatically:

from src.auto_coder.llm_output_logger import LLMOutputLogger

# Use custom path
logger = LLMOutputLogger(log_path="/custom/path/log.jsonl")

# Disable logging
logger = LLMOutputLogger(enabled=False)

For more detailed documentation, see docs/llm_output_logger_usage.md.

Label-Based Prompt Routing

Auto-Coder includes an intelligent label-based prompt system that dynamically selects appropriate prompt templates based on GitHub issue and PR labels. This enables more targeted and effective AI-driven automation by using context-specific instructions.

Overview

The label-based prompt system works by:

Analyzing Labels: Examining labels on GitHub issues and PRs
Priority Resolution: Selecting the highest priority applicable label when multiple labels exist
Prompt Selection: Using the selected label to choose an appropriate prompt template
Special Handling: Applying special behaviors for breaking-change and urgent issues

Default Label Categories

Breaking-Change Labels (highest priority):

breaking-change, breaking, api-change, deprecation, version-major

Priority Labels:

urgent, high-priority, critical, blocker, asap

Issue Type Labels:

bug, bugfix, defect, error, fix, hotfix, patch
enhancement, feature, improvement, new-feature
refactor, optimization, optimisation
documentation, docs, doc, readme, guide

Configuration

You can configure the label-based prompt system using environment variables:

Basic Setup

# Configure label-to-prompt mappings
export AUTO_CODER_LABEL_PROMPT_MAPPINGS='{
  "bug": "issue.bug",
  "enhancement": "issue.enhancement",
  "urgent": "issue.urgent",
  "breaking-change": "issue.breaking_change",
  "documentation": "issue.documentation"
}'

# Set priority order (highest priority first)
export AUTO_CODER_LABEL_PRIORITIES='[
  "breaking-change",
  "urgent",
  "bug",
  "enhancement",
  "documentation"
]'

PR Label Copying

The system can automatically copy semantic labels from issues to their corresponding PRs:

# Enable/disable (default: true)
export AUTO_CODER_PR_LABEL_COPYING_ENABLED='true'

# Maximum labels to copy (default: 3, range: 0-10)
export AUTO_CODER_PR_MAX_LABELS='3'

# Configure PR label mappings
export AUTO_CODER_PR_LABEL_MAPPINGS='{
  "breaking-change": ["breaking-change", "breaking"],
  "urgent": ["urgent", "critical"],
  "bug": ["bug", "bugfix", "defect"],
  "enhancement": ["enhancement", "feature"],
  "documentation": ["documentation", "docs"]
}'

# Set PR label priorities
export AUTO_CODER_PR_LABEL_PRIORITIES='[
  "urgent",
  "breaking-change",
  "bug",
  "enhancement",
  "documentation"
]'

How It Works

Priority Resolution Example:

If an issue has labels: ["bug", "enhancement", "urgent"] And priorities are: ["urgent", "bug", "enhancement"] Then the system uses the urgent prompt (highest priority).

Breaking-Change Detection:

Labels in the breaking-change category trigger special handling:

Automatically deletes failing tests that test removed features
Provides version bump recommendations (major version bump)
Generates migration guides
Updates CHANGELOG with breaking changes
Ensures backward compatibility guidance

Complete Example Configuration

Create a .env file:

# Label prompt mappings
AUTO_CODER_LABEL_PROMPT_MAPPINGS='{
  "bug": "issue.bug",
  "bugfix": "issue.bug",
  "enhancement": "issue.enhancement",
  "feature": "issue.enhancement",
  "urgent": "issue.urgent",
  "critical": "issue.urgent",
  "breaking-change": "issue.breaking_change",
  "documentation": "issue.documentation"
}'

# Label priorities
AUTO_CODER_LABEL_PRIORITIES='[
  "breaking-change",
  "urgent",
  "bug",
  "enhancement",
  "documentation"
]'

# PR label mappings
AUTO_CODER_PR_LABEL_MAPPINGS='{
  "breaking-change": ["breaking-change"],
  "urgent": ["urgent", "critical"],
  "bug": ["bug", "bugfix"],
  "enhancement": ["enhancement", "feature"],
  "documentation": ["documentation"]
}'

# PR label priorities
AUTO_CODER_PR_LABEL_PRIORITIES='[
  "urgent",
  "breaking-change",
  "bug",
  "enhancement",
  "documentation"
]'

# PR label copying
AUTO_CODER_PR_LABEL_COPYING_ENABLED='true'
AUTO_CODER_PR_MAX_LABELS='3'

Project-Specific Examples

See the examples/ directory for detailed configuration templates for different project types:

Testing Your Configuration

# Process a specific issue to test label-based prompts
auto-coder process-issues --repo owner/repo --only 123

# Check configuration
auto-coder config show

Documentation

For complete documentation with all options and best practices, see:

Label-Based Prompt Configurations
Client Features Documentation (technical specification)

Development

Development Environment Setup

Install development dependencies:

pip install -e ".[dev]"

Setup pre-commit hooks:

pre-commit install

VS Code Debug Settings

The project includes the following debug configurations:

Auto-Coder: Create Feature Issues: Feature proposal issue creation in outliner directory
Auto-Coder: Auth Status: Authentication status check in outliner directory
Auto-Coder: Process Issues (Live): Actual processing execution in outliner directory

To start debugging:

Press F5 in VS Code or open the "Run and Debug" panel
Select from the above configurations and run
Set breakpoints for step-by-step execution

Running Tests

# Run all tests
pytest

# Run tests with coverage
pytest --cov=src/auto_coder --cov-report=html

# Run specific test file
pytest tests/test_github_client.py

Code Quality Checks

# Formatting
black src/ tests/

# Import sorting
isort src/ tests/

# Linting
flake8 src/ tests/

# Type checking (canonical invocation, also used by CI and the pre-commit hook)
mypy --config-file pyproject.toml -p auto_coder

pyproject.toml's [tool.mypy] section is the sole authoritative mypy configuration (Python 3.12, non-strict). Passing --config-file pyproject.toml explicitly avoids mypy silently preferring a stray mypy.ini/setup.cfg if one is ever reintroduced.

Architecture

Component Structure

src/auto_coder/
├── cli.py              # CLI entry point
├── github_client.py    # GitHub API client (singleton)
├── gemini_client.py    # Gemini AI client
├── backend_manager.py  # LLM backend manager (singleton)
├── automation_engine.py # Main automation engine
└── config.py          # Configuration management

Singleton Pattern

Auto-Coder implements the singleton pattern for key components to ensure consistent state and resource management:

GitHubClient Singleton

The GitHubClient class uses a thread-safe singleton pattern:

from auto_coder.github_client import GitHubClient

# Get the singleton instance
client = GitHubClient.get_instance(token, disable_labels=False)

# Subsequent calls return the same instance
client2 = GitHubClient.get_instance(token, disable_labels=False)
# client is client2  # True

LLMBackendManager Singleton

The LLMBackendManager class manages LLM backends as a singleton:

from auto_coder.backend_manager import get_llm_backend_manager

# Initialize once with configuration
manager = get_llm_backend_manager(
    default_backend="codex",
    default_client=client,
    factories={"codex": lambda: client}
)

# Use globally
response = run_llm_prompt("Your prompt here")

For detailed usage patterns, see GLOBAL_BACKEND_MANAGER_USAGE.md.

Data Flow

CLI → AutomationEngine → GitHubClient (data retrieval)
AutomationEngine → GeminiClient (AI analysis)
AutomationEngine → GitHubClient (action execution)
AutomationEngine → Report Generation

Output and Reports

Execution results are saved in JSON format in the ~/.auto-coder/{repository}/ directory:

automation_report_*.json: Results of automation processing (saved per repository)
jules_automation_report_*.json: Results of automation processing in Jules mode

Example: For owner/repo repository, reports are saved in ~/.auto-coder/owner_repo/.

Troubleshooting

Common Issues

GitHub API limits: Wait some time before retrying if you hit rate limits
Gemini API errors: Check if API keys are correctly configured
Permission errors: Check if GitHub token has appropriate permissions

"Unsupported backend specified" Error

If you see this error with a custom backend name:

Ensure you have set backend_type in your configuration
Use a valid backend type: codex, codex-mcp, gemini, qwen, claude, or auggie
Ensure the required CLI tool for the backend_type is installed

Example fix:

[backends.my-custom-backend]
backend_type = "codex"  # Add this line
model = "grok-4.1-fast"
openai_api_key = "your-key"
openai_base_url = "https://openrouter.ai/api/v1"

See Configuration Guide for detailed troubleshooting.

Checking Logs

# Set log level to DEBUG
export LOG_LEVEL=DEBUG
auto-coder process-issues --repo owner/repo

License

This project is published under the MIT license. See the LICENSE file for details.

Contributing

We welcome pull requests and issue reports. Before contributing, please ensure:

Tests pass
Code style is consistent
New features include appropriate tests

Support

If you have issues or questions, please create a GitHub issue.

Name		Name	Last commit message	Last commit date
.Jules		.Jules
.autocoder-dev		.autocoder-dev
.devcontainer		.devcontainer
.github		.github
.jules		.jules
.vscode		.vscode
build_backend		build_backend
docs		docs
examples		examples
mcp-inspector-config		mcp-inspector-config
prompt-evals		prompt-evals
reports		reports
rm		rm
scripts		scripts
src/auto_coder		src/auto_coder
tests		tests
utils		utils
verification		verification
.env.example		.env.example
.flake8		.flake8
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
.pytestignore		.pytestignore
.python-version		.python-version
ACCESS_GUIDE.md		ACCESS_GUIDE.md
AGENTS.md		AGENTS.md
BACKWARD_COMPATIBILITY_IMPLEMENTATION.md		BACKWARD_COMPATIBILITY_IMPLEMENTATION.md
BREAKING_CHANGES.md		BREAKING_CHANGES.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
GLOBAL_BACKEND_MANAGER_USAGE.md		GLOBAL_BACKEND_MANAGER_USAGE.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
MCP_PDB_SETUP.md		MCP_PDB_SETUP.md
MIGRATION_909.md		MIGRATION_909.md
MIGRATION_GUIDE.md		MIGRATION_GUIDE.md
MIGRATION_GUIDE_v1.0.0.md		MIGRATION_GUIDE_v1.0.0.md
Makefile		Makefile
OPENROUTER_SETUP.md		OPENROUTER_SETUP.md
PARENT_ISSUE_COMPLETION.md		PARENT_ISSUE_COMPLETION.md
PROGRESS_DECORATORS_README.md		PROGRESS_DECORATORS_README.md
QWEN.md		QWEN.md
README.md		README.md
SINGLETON_IMPLEMENTATION_SUMMARY.md		SINGLETON_IMPLEMENTATION_SUMMARY.md
compose.channels.yml		compose.channels.yml
compose.management.yml		compose.management.yml
main_issue_proposal.md		main_issue_proposal.md
monitor_proxy.sh		monitor_proxy.sh
npm-install-124033.sh		npm-install-124033.sh
proxy_status.sh		proxy_status.sh
pyproject.toml		pyproject.toml
start_proxy.sh		start_proxy.sh
test_help.sh		test_help.sh
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

Auto-Coder

Features

🔧 Core Features

🚀 Automated Workflow

🔄 PR Mergeability Handling

📊 Logging and Monitoring

🩺 Run Diagnostics (why a long run stopped)

Installation

Prerequisites

Setup

Usage

CLI Commands

process-issues

create-feature-issues

fix-to-pass-tests

Dependabot PR Handling

Authentication

Regarding Qwen Usage (Authentication)

Regarding Auggie Usage

CLI Commands

Processing Issues and PRs

Creating Feature Proposal Issues

Auto-fix until tests pass (fix-to-pass-tests)

Command Options

process-issues

create-feature-issues

fix-to-pass-tests

Lock Management Commands

Branch Naming Best Practices

Naming Conventions

Issue Branches

Attempt Branches

Git Ref Namespace Limitations

Conflicting Names ❌

Resolution

Prevention

Common Scenarios

When to Use Attempt Branches

How to Clean Up Old Branches

Recommended Workflow

Automated Conflict Detection

Migration from Legacy Format

Work-in-Progress (WIP) Branch Resumption

Automatic WIP Detection

Parent Issue Auto-Reopen

Auto-Reopen Behavior

Why This Matters

Example

Parent Issue Context Injection

What is Parent Issue Context?

When and Why It's Used

How It Works

Scope Limitations

Example Scenario

Benefits

Technical Details

Configuration

Configuration File Locations

When to Use Local Configuration

When to Use Home Configuration

Configuration Search Behavior

Configuration File (TOML)

Custom Backend Names

Configuring Model Provider

Example: Using OpenRouter

Supported Providers

Complete Example with OpenRouter

Configuration Management

Supported Backend Types

Jules Mode Configuration

1. CLI Flag (Per-Command)

2. Configuration File (Persistent)

Retry Configuration

Configuration Fields

Behavior

Example Configuration

`process-issues`

`create-feature-issues`

`fix-to-pass-tests`

`process-issues`

`create-feature-issues`

`fix-to-pass-tests`