AutoAgent

> Autonomous AI agent runner for executing tasks with Claude or Gemini, featuring automatic failover and comprehensive task management.


Overview

AutoAgent is a powerful npm package that enables running autonomous AI agents using Claude or Gemini for task execution. It converts complex bash scripts into a robust TypeScript-based solution with both CLI and programmatic APIs.

$3

- 🤖 Multiple AI Providers: Support for Claude (Anthropic), Gemini (Google), and Mock provider for testing
- 🔄 Automatic Failover: Seamlessly switches between providers on rate limits
- 📋 Task Management: Comprehensive issue and plan tracking system with status management
- 🔧 Git Integration: Automatic commits with co-authorship attribution
- 📊 Provider Learning: Tracks performance and learns from execution patterns
- 📝 List Command: Query issues, providers, and execution history with filtering
- ⚡ Async Execution: Efficient async/await based architecture
- 🛡️ TypeScript: Full type safety and IntelliSense support with strict mode
- 🎯 Retry Logic: Intelligent retry with exponential backoff
- 📁 Template System: Pre-built templates for issues and plans
- 🚀 CLI & API: Use as a command-line tool or programmatically
- 🔍 Enhanced Error Handling: Proper exit codes and descriptive error messages
- 🌍 Environment Variables: Full support for configuration via environment
- 📖 Enhanced Gemini Output: Automatic formatting with smart sentence boundary detection
- 🔄 Reflection Engine: Iterative improvement of decomposed plans and issues

Table of Contents

- Installation
- Quick Start
- CLI Usage
- Programmatic Usage
- Configuration
- Environment Variables
- Agent Instructions
- Task Management
- Examples
- Architecture
- Testing
- Troubleshooting
- Contributing
- License

Installation

$3

- Node.js >= 22.0.0
- npm or yarn
- Claude CLI (claude) or Gemini CLI (gemini) installed and authenticated
- Git (required for auto-commit feature, optional otherwise)

$3

AutoAgent's auto-commit feature requires a properly configured git environment. While git is optional, it's recommended for tracking changes automatically.

#### Required Git Setup

1. Install Git
``bash
# macOS (with Homebrew)
brew install git

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install git

# Windows
# Download from https://git-scm.com/download/windows

# Verify installation
git --version
`

2. Initialize Repository
`bash
# In your project directory
git init

# Or clone existing repository
git clone
cd
`

3. Configure Git User
`bash
# Set globally (for all repositories)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Or set locally (for current repository only)
git config user.name "Your Name"
git config user.email "your.email@example.com"

# Verify configuration
git config user.name
git config user.email
`

4. Add Remote (Optional)
`bash
# Add remote repository for pushing changes
git remote add origin

# Verify remote
git remote -v
`

#### Disabling Auto-Commit

If you don't want to use git or prefer manual commits:

`bash


Via CLI

autoagent config set-auto-commit false

Via configuration file

{
"gitAutoCommit": false
}
`

$3

AutoAgent supports configuring git hook behavior during auto-commit. By default, git hooks are executed normally, but you can bypass them when needed:

`bash


Disable git hooks globally (use --no-verify)

autoagent config set-git-no-verify true

Enable git hooks globally (default)

autoagent config set-git-no-verify false

Override per execution

autoagent run 1 --no-verify # Skip hooks for this run
autoagent run 1 --verify # Force hooks for this run
`

#### When to use --no-verify

The --no-verify flag is useful in specific scenarios:

- CI/CD pipelines where pre-commit hooks may fail in automated environments or require interactive input
- Testing environments where hooks designed for human workflows are not appropriate
- Emergency situations where broken or misconfigured hooks are blocking critical fixes
- Automated environments where hooks interfere with autonomous operations
- Development workflows with slow or broken git hooks that interrupt execution

⚠️ Security Warning: Using --no-verify bypasses pre-commit hooks that may include:
- Security checks and vulnerability scanning
- Code quality validation and linting
- Test execution and coverage requirements
- Commit message formatting and validation
- Other important safeguards specific to your project

Only use --no-verify when you understand the implications and are certain the hooks can be safely bypassed.

#### Examples

`bash


Development workflow with slow hooks

autoagent config set-git-no-verify true # Set globally for dev
autoagent run --all # Runs without hooks
autoagent run 5 --verify # Override for important changes

CI/CD pipeline configuration

export AUTOAGENT_GIT_NO_VERIFY=true # Environment variable
autoagent run specs/feature.md --all

Emergency fix workflow

autoagent run critical-fix --no-verify

Testing environment configuration

In .autoagent/config.json:

{
"gitAutoCommit": true,
"gitCommitNoVerify": true,
"includeCoAuthoredBy": false
}
`

$3

AutoAgent supports automatic git push after commits, allowing for fully automated workflows. This feature is disabled by default for security reasons and must be explicitly enabled.

#### Prerequisites for Auto-Push

1. Git remote repository configured
`bash
# Check if remote is configured
git remote -v

# Add remote if needed
git remote add origin
`

2. Push permissions to remote repository
- SSH keys configured (recommended)
- HTTPS credentials cached
- Or other authentication method

3. Valid upstream branch
`bash
# Set upstream branch
git push -u origin main

# Or for current branch
git push -u origin HEAD
`

#### Enabling Auto-Push

`bash


Enable auto-push globally

autoagent config set-auto-push true

Set specific remote (default: origin)

autoagent config set-push-remote upstream

Set specific branch (default: current branch)

autoagent config set-push-branch main
`

#### Security Considerations

⚠️ IMPORTANT: Auto-push is disabled by default for security reasons. Before enabling:

1. Understand the risks: Auto-push will automatically push all changes to your remote repository
2. Review your authentication: Ensure your git credentials are properly secured
3. Consider your environment: Auto-push may not be suitable for:
- Shared repositories with strict review processes
- Production branches with protected status
- Repositories requiring signed commits
- Environments with compliance requirements

4. Use branch protection: Configure branch protection rules on your remote repository
5. Test locally first: Always test auto-push with a test repository before using in production

#### Configuration Options

`json
{
"gitAutoCommit": true,
"gitAutoPush": false,
"gitPushRemote": "origin",
"gitPushBranch": null,
"gitCommitNoVerify": false
}
`

- gitAutoPush: Enable/disable automatic push (default: false)
- gitPushRemote: Remote name to push to (default: "origin")
- gitPushBranch: Branch to push to (default: current branch)

#### Auto-Push Workflow Examples

1. CI/CD Pipeline Integration
`bash


GitHub Actions workflow

name: Automated Updates
on:
schedule:
- cron: '0 0 *' # Daily

jobs:
auto-update:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
token: ${{ secrets.GITHUB_TOKEN }}

- name: Configure git
run: |
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"

- name: Run autoagent with push
run: |
npm install -g autoagent-cli
autoagent config set-auto-push true
autoagent config set-push-branch main
autoagent run --all
`

2. Development Feature Branch Workflow
`bash


Setup feature branch with auto-push

git checkout -b feature/new-functionality
autoagent config set-auto-push true
autoagent config set-push-branch feature/new-functionality

Work on issues with automatic backup

autoagent run specs/feature.md --all

Each completed issue is automatically pushed to remote

Team members can track progress in real-time

`

3. Team Collaboration Setup
`bash


Configure for team repository

autoagent config init
autoagent config set-auto-push true
autoagent config set-push-remote origin
autoagent config set-push-branch develop

Add team-specific configuration

cat > .autoagent/config.json << EOF
{
"gitAutoCommit": true,
"gitAutoPush": true,
"gitPushRemote": "origin",
"gitPushBranch": "develop",
"includeCoAuthoredBy": true
}
EOF

Team members can now run with auto-sync

autoagent run --all
`

4. Testing Environment with Conditional Push
`bash
#!/bin/bash


Script for test environments

Only push if tests pass

autoagent run 1-implement-feature
if npm test; then
git push origin HEAD
else
echo "Tests failed, not pushing changes"
exit 1
fi

Or use auto-push with pre-push hooks

autoagent config set-auto-push true

Configure .git/hooks/pre-push to run tests

`

5. Multi-Repository Workflow
`bash


Working with multiple related repositories

REPOS=("frontend" "backend" "shared")

for repo in "${REPOS[@]}"; do
cd "$repo"
autoagent config set-auto-push true
autoagent config set-push-branch integration
autoagent run --all
cd ..
done

All repositories stay synchronized

`

$3

`bash
npm install -g autoagent-cli
`

$3

`bash
npm install autoagent-cli
`

$3

`bash
git clone https://github.com/carlrannaberg/autoagent.git
cd autoagent
npm install
npm run build
npm link # For global CLI access
`

Quick Start

$3

`bash


Create a local configuration

autoagent config init

Or create a global configuration

autoagent config init --global
`

$3

`bash


Create a task with AI assistance

autoagent create "Add user authentication to the API"

This creates a task in the STM (Simple Task Master) system

Tasks are automatically numbered and stored in .simple-task-master/tasks/

`

$3

`bash


Execute next pending task

autoagent run

Execute with specific provider

autoagent run --provider gemini

Execute a specific task by number

autoagent run 1
`

Task Management

AutoAgent uses STM (Simple Task Master) for unified task management. All tasks are stored as structured data with automatic numbering, status tracking, and metadata.

$3

Tasks can be created from:

1. Specification Files (Specs): High-level project descriptions that get decomposed into actionable tasks
2. Direct Task Creation: Using autoagent create command for immediate tasks
3. Batch Operations: Processing multiple related tasks together

$3

Each task contains:
- Title and Description: Clear definition of what needs to be done
- Status: pending, in_progress, completed, cancelled
- Metadata: Created date, tags, priority, estimated effort
- Validation: Success criteria and acceptance requirements

$3

The typical workflow is:
1. Write a spec describing what you want to build
2. Run the spec to automatically decompose it into tasks
3. Execute tasks to implement the changes

Example spec processing:
`bash


Process a specification file

autoagent run specs/add-authentication.md --all

This automatically:

1. Analyzes the spec

2. Creates structured tasks in STM

3. Executes each task in sequence

`

CLI Usage

$3

#### autoagent run [target]
Intelligently execute specs, issues, or plans based on the target type.

`bash


Run next pending issue

autoagent run

Run a specification file (creates plan + issues, then executes)

autoagent run specs/add-authentication.md

Run specific task by number

autoagent run 5

Run all pending tasks

autoagent run --all

Run spec and continue with all created tasks

autoagent run specs/refactor-api.md --all

Dry run (preview without execution)

autoagent run --dry-run

Override provider

autoagent run --provider gemini

Control git hooks during commits

autoagent run --no-verify # Skip git hooks
autoagent run --verify # Force git hooks (default)

Use mock provider for testing

AUTOAGENT_MOCK_PROVIDER=true autoagent run

Run with custom reflection settings

autoagent run --reflection-iterations 5

Run without reflection

autoagent run --no-reflection
`

Smart Detection:
- Spec files: Automatically detected by content and file extension
- Task references: Can use task number (5) or task ID

#### autoagent create
Create a new task with AI assistance.

`bash


Basic usage

autoagent create "Implement user profile page"

With specific provider

autoagent create "Add caching layer" --provider claude
`

#### autoagent status [task]
Display project status, pending tasks, or specific task status.

`bash


Show overall project status

autoagent status

Show specific task status

autoagent status 5

Show execution history

autoagent status --history
`

Output:
`
📊 Project Status

Total Tasks: 15
Completed: 12
Pending: 3

Next Task: #16 Add error handling

✅ Available Providers: claude, gemini
`

#### autoagent config
Manage configuration settings.

`bash


Initialize configuration

autoagent config init [--global]

Set default provider

autoagent config set-provider gemini

Set failover order

autoagent config set-failover claude,gemini

Enable/disable auto-commit

autoagent config set-auto-commit true

Enable/disable git hooks during commits

autoagent config set-git-no-verify true # Skip hooks (--no-verify)
autoagent config set-git-no-verify false # Run hooks (default)

Configure auto-push

autoagent config set-auto-push true # Enable auto-push
autoagent config set-auto-push false # Disable auto-push (default)
autoagent config set-push-remote upstream # Set remote (default: origin)
autoagent config set-push-branch main # Set branch (default: current)

Show current configuration

autoagent config show

Clear rate limits

autoagent config clear-limits

Get specific config value

autoagent config get provider
autoagent config get provider --show-source
autoagent config get gitCommitNoVerify

Set any config value

autoagent config set logLevel debug
autoagent config set retryAttempts 5
autoagent config set gitCommitNoVerify true
`

#### autoagent list
List tasks, providers, or execution history.

`bash


List all tasks

autoagent list tasks

List tasks by status

autoagent list tasks --status pending
autoagent list tasks --status completed

List with JSON output

autoagent list tasks --json

List available providers

autoagent list providers
autoagent list providers --json

List execution history

autoagent list executions
autoagent list executions --json
`

Example output:
`
Found 3 task(s):

⏳ #1 Setup project (pending)
✅ #2 Add tests (completed)
🔄 #3 Refactor API (in_progress)
`

#### autoagent check
Verify provider availability.

`bash


Check all providers

autoagent check

Check specific provider

autoagent check claude
`

$3

Most commands support these common options:

- --workspace, -w : Set working directory
- --debug, -d: Enable debug logging
- --provider, -p : Override provider
- --reflection-iterations : Set maximum reflection iterations (1-10)
- --no-reflection: Disable reflection for this run
- --help, -h: Show help

Programmatic Usage

$3

`typescript
import { AutonomousAgent } from 'autoagent';

async function runAgent() {
// Create agent instance
const agent = new AutonomousAgent({
workspace: process.cwd(),
provider: 'claude',
autoCommit: true
});

// Execute a single task by number
const result = await agent.executeTask(1);

if (result.success) {
console.log('Task completed successfully!');
}
}
`

$3

`typescript
import { AutonomousAgent } from 'autoagent';

async function advancedExample() {
const agent = new AutonomousAgent({
workspace: './my-project',
provider: 'claude',
autoCommit: true,
debug: true
});

// Listen to execution events
agent.on('execution-start', (taskNumber) => {
console.log(Starting task #${taskNumber});
});

agent.on('execution-end', (result) => {
if (result.success) {
console.log(✓ Task #${result.taskNumber} completed);
} else {
console.log(✗ Task #${result.taskNumber} failed: ${result.error});
}
});

// Execute all pending tasks
const results = await agent.executeAll();

console.log(Completed ${results.length} tasks);
}
`

$3

`typescript
import { Provider, ExecutionResult } from 'autoagent';

class CustomProvider extends Provider {
get name(): string {
return 'custom';
}

async checkAvailability(): Promise {
// Implement availability check
return true;
}

async execute(
issueFile: string,
planFile: string,
contextFiles?: string[],
signal?: AbortSignal
): Promise {
// Implement execution logic
return {
success: true,
taskNumber: 1,
duration: 1000,
output: 'Custom provider executed successfully',
provider: 'custom'
};
}
}
`

For detailed API documentation, see docs/API.md.

Configuration

AutoAgent uses a layered configuration system:

1. Default Configuration (built-in)
2. Global Configuration (~/.autoagent/config.json)
3. Local Configuration (./.autoagent/config.json)

$3

`json
{
"defaultProvider": "claude",
"providers": {
"claude": {
"enabled": true,
"maxTokens": 100000
},
"gemini": {
"enabled": true,
"maxTokens": 100000
}
},
"failoverProviders": ["claude", "gemini"],
"failoverDelay": 2000,
"retryAttempts": 3,
"retryDelay": 1000,
"maxTokens": 100000,
"rateLimitCooldown": 3600000,
"gitAutoCommit": true,
"gitAutoPush": false,
"gitPushRemote": "origin",
"gitPushBranch": null,
"gitCommitNoVerify": false,
"gitCommitInterval": 300000,
"includeCoAuthoredBy": true,
"logLevel": "info",
"customInstructions": ""
}
`

For detailed configuration documentation, see docs/CONFIG.md.

Environment Variables

AutoAgent supports configuration through environment variables, which take precedence over configuration files:

$3

- AUTOAGENT_DEBUG - Enable debug mode (true/false)
- AUTOAGENT_GIT_NO_VERIFY - Skip git hooks during commits (true/false)

$3

- AUTOAGENT_MOCK_PROVIDER - Enable mock provider (true/false)
- AUTOAGENT_MOCK_DELAY - Simulated execution delay in ms
- AUTOAGENT_MOCK_FAIL - Simulate general execution failure (true/false)
- AUTOAGENT_MOCK_TIMEOUT - Simulate timeout errors (true/false)
- AUTOAGENT_MOCK_RATE_LIMIT - Simulate rate limit errors (true/false)
- AUTOAGENT_MOCK_AUTH_FAIL - Simulate authentication failures (true/false)
- AUTOAGENT_MOCK_CHAT_FAIL - Simulate chat/communication failures (true/false)

$3

- AUTOAGENT_DISABLE_GEMINI_FORMATTING - Disable automatic output formatting (true/false)
- AUTOAGENT_GEMINI_BUFFER_SIZE - Override default buffer size (default: 1000)
- AUTOAGENT_DEBUG_FORMATTING - Enable formatting debug logs (true/false)

$3

- DEBUG - Enable debug mode with stack traces (true/1)
- DEBUG_CLI_EXECUTOR - Debug CLI command execution

Example usage:
`bash


Use mock provider with custom delay

AUTOAGENT_MOCK_PROVIDER=true AUTOAGENT_MOCK_DELAY=500 autoagent run

Enable debug output

AUTOAGENT_DEBUG=true autoagent run --all

Simulate rate limit errors for testing

AUTOAGENT_MOCK_PROVIDER=true AUTOAGENT_MOCK_RATE_LIMIT=true autoagent run
`

Agent Instructions (AGENT.md)

AutoAgent uses the AGENT.md file to provide context to AI providers about your project. This file gives guidance to agentic coding tools on codebase structure, build/test commands, architecture, etc.

The AGENT.md file is automatically created when you run AutoAgent for the first time. It includes:
- Project context and description
- Technology stack
- Coding standards
- Build and test commands
- Execution history (automatically updated)

For backward compatibility, CLAUDE.md and GEMINI.md are created as symlinks to AGENT.md (or stub files on systems that don't support symlinks).

Learn more about the AGENT.md standard at https://agent.md.




Examples

$3

`bash


Create a specification for a new feature

cat > specs/add-user-profiles.md << 'EOF'

Add User Profiles Feature

Goal

Implement user profiles with avatars and bio information.

Requirements

- User profile page at /users/:id
- Editable bio field (max 500 chars)
- Avatar upload with image resizing
- Privacy settings (public/private profile)
EOF

Run the spec - this creates tasks, then executes them

autoagent run specs/add-user-profiles.md --all

Or run step by step:

1. Process spec to create tasks (with reflection)

autoagent run specs/add-user-profiles.md

2. Review created tasks

autoagent list tasks --status pending

3. Execute specific tasks

autoagent run 2
autoagent run 3

4. Or execute remaining tasks

autoagent run --all
`

$3

`bash


List all pending tasks

autoagent list tasks --status pending

Check specific task status

autoagent status 5

View recent executions

autoagent status --history

Get tasks in JSON format for scripting

TASKS=$(autoagent list tasks --status pending --json)
echo $TASKS | jq '.[0].name'
`

$3

`javascript
const { AutonomousAgent, ConfigManager, STMManager } = require('autoagent-cli');

async function processBatch() {
// Enable mock provider for testing
process.env.AUTOAGENT_MOCK_PROVIDER = 'true';

const config = new ConfigManager();
const stm = new STMManager();
const agent = new AutonomousAgent(config, stm);

// Process all tasks with progress tracking
const results = await agent.executeAll({
onProgress: (percent, message) => {
process.stdout.write(\r[${percent}%] ${message});
}
});

console.log(\nCompleted ${results.length} tasks);
}
`

$3

`javascript
const { createProvider, isProviderAvailable } = require('autoagent-cli');

async function executeWithFailover() {
const providers = ['claude', 'gemini'];

for (const providerName of providers) {
if (await isProviderAvailable(providerName)) {
const provider = createProvider(providerName);
try {
await provider.execute(1); // Execute task #1
console.log(Success with ${providerName});
break;
} catch (error) {
console.log(Failed with ${providerName}, trying next...);
}
}
}
}
`

$3

`bash


Check where configuration is coming from

autoagent config get provider --show-source

Output: provider = claude (from configuration file)

Override provider for single run

autoagent run --provider gemini

Set configuration programmatically

autoagent config set retryAttempts 5
autoagent config set logLevel debug

Validate configuration

autoagent config set provider invalid-provider

Error: Invalid value for provider. Must be one of: claude, gemini, mock

`

More examples available in the examples/ directory:
- basic-usage.js - Getting started
- provider-failover.js - Failover handling
- batch-execution.js - Batch processing
- configuration.js - Configuration management
- custom-integration.js - Advanced integration

Testing

AutoAgent includes comprehensive testing support including a mock provider for CI/CD pipelines:

$3

The mock provider simulates AI responses without making actual API calls:

`bash


Run with mock provider

AUTOAGENT_MOCK_PROVIDER=true autoagent run

Run tests in CI/CD

AUTOAGENT_MOCK_PROVIDER=true npm test

Simulate specific scenarios

AUTOAGENT_MOCK_RATE_LIMIT=true autoagent run
AUTOAGENT_MOCK_FAIL=true autoagent run --all
`

$3

`bash


Run all tests with Vitest

npm test

Run tests in watch mode

npm run test:watch

Run with coverage

npm run test:coverage

Run specific test suites

npm run test:unit # Unit tests only
npm run test:integration # Integration tests
npm run test:e2e # End-to-end tests

Run with Vitest UI

npm run test:ui
`

$3

- test/unit/ - Unit tests for individual components
- test/integration/ - Integration tests for component interactions
- test/e2e/ - End-to-end CLI tests
- test/benchmark/ - Performance benchmarks

Architecture

`
┌─────────────────┐ ┌──────────────────┐
│ CLI Interface │────▶│ Autonomous Agent │
└─────────────────┘ └────────┬─────────┘
│
┌────────────────────────┼────────────────────────┐
│ │ │
┌──────▼────────┐ ┌────────▼─────────┐ ┌────────▼────────┐
│ STM Manager │ │ Config Manager │ │ Providers │
│ │ │ │ │ │
│ • Task CRUD │ │ • User Config │ │ • Claude │
│ • Status │ │ • Rate Limits │ │ • Gemini │
│ • Search │ │ • Preferences │ │ • Mock (Test) │
│ • Validation │ │ • Env Variables │ │ • Failover │
└───────────────┘ └──────────────────┘ └─────────────────┘
`

$3

- AutonomousAgent: Main orchestrator for task execution
- Providers: AI provider implementations (Claude, Gemini)
- STMManager: Manages tasks through Simple Task Master integration
- ConfigManager: Manages configuration and rate limits
- ReflectionEngine: Iterative improvement system for decomposed plans
- Logger: Provides formatted console output
- Git Integration: Handles automatic commits and rollbacks
- StreamFormatter: Handles real-time output formatting for AI providers

Reflection Engine

AutoAgent includes an intelligent reflection system that iteratively improves decomposed plans and issues:

`bash


Use default reflection (3 iterations)

autoagent run specs/feature.md

Customize reflection iterations

autoagent run specs/feature.md --reflection-iterations 5

Disable reflection for faster execution

autoagent run specs/feature.md --no-reflection
`

The reflection engine:
- Analyzes initial decomposition quality using improvement scoring
- Identifies gaps and improvements in plans and issues
- Iteratively refines decomposed tasks for better clarity
- Skips reflection for simple specifications (< 500 words)
- Provides progress tracking during reflection iterations

$3

Reflection behavior can be controlled through configuration:

`json
{
"reflection": {
"enabled": true,
"maxIterations": 3,
"improvementThreshold": 0.1,
"skipForSimpleSpecs": true
}
}
`

Or via CLI options:
`bash


Set custom iteration count

autoagent run --reflection-iterations 5

Disable reflection entirely

autoagent run --no-reflection
`

Enhanced Gemini Output Formatting

AutoAgent automatically formats Gemini provider output for improved readability by detecting sentence boundaries and adding appropriate line breaks. This feature enhances the readability of long responses from the Gemini AI.

$3

- Smart Sentence Detection: Automatically detects sentence endings (periods, exclamation marks, question marks)
- Abbreviation Handling: Recognizes common abbreviations (Dr., Mr., Inc., etc.) to avoid incorrect splits
- Number Pattern Recognition: Handles decimal numbers (3.14, $10.50) without breaking
- URL/Email/Path Preservation: Keeps URLs, email addresses, and file paths intact
- Performance Optimized: Processes text with <1ms overhead per 1KB
- Configurable: Can be disabled or customized via environment variables

$3

`


Before formatting:

The AI response continues without breaks. It contains multiple sentences. This makes it harder to read. Dr. Smith mentioned that version 2.0 is ready.

After formatting:

The AI response continues without breaks.

It contains multiple sentences.

This makes it harder to read.

Dr. Smith mentioned that version 2.0 is ready.
`

$3

You can control the formatting behavior with environment variables:

`bash


Disable formatting entirely

export AUTOAGENT_DISABLE_GEMINI_FORMATTING=true

Customize buffer size (default: 1000 characters)

export AUTOAGENT_GEMINI_BUFFER_SIZE=2000

Enable debug logging for formatting

export AUTOAGENT_DEBUG_FORMATTING=true
`

$3

The formatter is highly optimized:
- Regex patterns are compiled once and reused
- Text processing achieves <1ms per 1KB of text
- Memory efficient with configurable buffer sizes
- Minimal impact on streaming performance

Troubleshooting

$3

Provider not available
`bash


Check provider status

autoagent check

Clear rate limits if needed

autoagent config clear-limits
`

Git auto-commit not working

AutoAgent validates your git environment before performing auto-commits. Here are common issues and their solutions:

1. Git not installed
`bash


Error: "Git is not available on your system"

Solution - Install git:

macOS

brew install git

Ubuntu/Debian

sudo apt-get install git

Windows

Download from https://git-scm.com/download/windows

Verify installation

git --version
`

2. Not a git repository
`bash


Error: "Current directory is not a git repository"

Solution - Initialize repository:

git init

Or clone existing repository:

git clone

Verify repository status

git status
`

3. Git user not configured
`bash


Error: "Git user configuration is incomplete"

Solution - Configure git user:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Verify configuration

git config --list | grep user
`

4. No remote repository
`bash


Warning: "No remote repository configured"

Solution - Add remote (optional for local-only repos):


git remote add origin
git remote -v
`

5. Quick fixes
`bash


Check current auto-commit setting

autoagent config get gitAutoCommit

Enable auto-commit

autoagent config set-auto-commit true

Disable auto-commit

autoagent config set-auto-commit false

Debug git validation

AUTOAGENT_DEBUG=true autoagent run
`

TypeScript compilation errors
`bash


Clean and rebuild


rm -rf dist
npm run build
`

Exit code 1 with no clear error
`bash


Enable debug mode to see stack traces

DEBUG=true autoagent run

Check for corrupted config

autoagent config show
`

Cyclic dependency detected
`bash


List all tasks to check dependencies

autoagent list tasks --json | jq '.[] | {name, dependencies}'

Fix by editing tasks to remove circular references

`

Mock provider not working
`bash


Ensure environment variable is set


export AUTOAGENT_MOCK_PROVIDER=true
autoagent list providers # Should show mock as available
`

Auto-push not working

1. Remote not accessible
`bash


Error: "Failed to push: remote 'origin' not found"

Solution - Check remote configuration:

git remote -v

Add remote if missing:

git remote add origin

Or use different remote:

autoagent config set-push-remote upstream
`

2. Authentication failed
`bash


Error: "Failed to push: authentication required"

Solution - Setup SSH keys (recommended):

ssh-keygen -t ed25519 -C "your_email@example.com"

Add public key to GitHub/GitLab/etc.

Or cache HTTPS credentials:

git config --global credential.helper cache
git push # Enter credentials once

Test authentication:

ssh -T git@github.com # For GitHub
`

3. Permission denied
`bash


Error: "Failed to push: permission denied"

Solution - Check repository permissions:

Ensure you have write access to the repository

Check branch protection rules:

Protected branches may block direct pushes

Use different branch:

autoagent config set-push-branch feature-branch
git checkout -b feature-branch
`

4. Push rejected (non-fast-forward)
`bash


Error: "Failed to push: non-fast-forward updates were rejected"

Solution - Pull latest changes first:

git pull --rebase origin main

Or disable auto-push until resolved:

autoagent config set-auto-push false
`

5. Quick push debugging
`bash


Test push manually first:

git push -u origin HEAD

Check push configuration:

autoagent config get gitAutoPush
autoagent config get gitPushRemote
autoagent config get gitPushBranch

Enable debug logging:

AUTOAGENT_DEBUG=true autoagent run
`

For more troubleshooting help, see docs/TROUBLESHOOTING.md.

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

$3

`bash


Clone the repository

git clone https://github.com/carlrannaberg/autoagent.git
cd autoagent

Install dependencies

npm install

Run all checks (recommended)

npm run check

Individual commands

npm test # Run tests with Vitest
npm run typecheck # Check TypeScript types
npm run lint # Check code style
npm run build # Build the project

Development commands

npm run test:watch # Run tests in watch mode with Vitest
npm run test:ui # Run tests with Vitest UI
npm run test:coverage # Run tests with coverage report
npm run lint:fix # Auto-fix linting issues
`

License

MIT License - see LICENSE file for details.

Support

- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 📖 Documentation: See the docs/` directory for detailed guides

---

Made with ❤️ by Carl Rannaberg