ChadGI

Autonomous Task Worker powered by Claude Code

ChadGI is a CLI tool that runs Claude Code in a continuous loop to automatically work through tasks from a GitHub Project board. It's designed for transparency - you can watch it work in real-time and stop it at any moment.

Features

• Pulls tasks from GitHub Project board's "Ready" column
• Two-phase workflow: Implementation, then PR creation (only after tests pass)
• Rich streaming output showing tool calls with details
• Configurable via YAML with customizable templates
• Progress tracking with session resume capability
• Automatic task generation when queue is empty

Quick Start

# Install globally
npm install -g chadgi

# Initialize in your project
cd your-project
chadgi init

# Run interactive setup wizard (recommended)
chadgi setup

# Validate setup
chadgi validate

# Start the automation loop
chadgi start

Prerequisites

Before using ChadGI, ensure you have the following installed:

| Tool | Purpose | Installation | |------|---------|--------------| | Claude Code CLI | AI agent for task execution | Install Claude Code | | GitHub CLI (gh) | GitHub API interactions | brew install gh or GitHub CLI | | jq | JSON parsing | brew install jq or apt install jq | | git | Version control | Usually pre-installed |

Verify your setup:

claude --version
gh auth status
jq --version
git --version

CLI Commands

chadgi init

Creates a .chadgi/ directory with configuration and template files.

chadgi init           # Initialize ChadGI
chadgi init --force   # Overwrite existing files

Creates:

• .chadgi/chadgi-config.yaml - Main configuration
• .chadgi/chadgi-task.md - Task prompt template
• .chadgi/chadgi-generate-task.md - Task generation template
• .chadgi/.gitignore - Ignores progress file

chadgi setup

Interactive configuration wizard that guides you through setting up ChadGI.

chadgi setup                    # Launch interactive wizard
chadgi setup --non-interactive  # Use sensible defaults for CI environments
chadgi setup --config /path/to/config  # Configure specific file

The wizard:

• Auto-detects your git remote repository
• Lists available GitHub Projects for selection
• Validates project board has required columns (Ready, In Progress, In Review)
• Configures base branch, GigaChad mode, budget limits, and notifications
• Shows a summary before saving changes
• Preserves existing configuration values as defaults when re-running

Example interaction:

$ chadgi setup

ChadGI Setup Wizard

Detected repository: SwapLabsInc/ChadGI

? Select GitHub Project:
  > ChadGI Tasks (#7)
    Sprint Board (#3)
    Backlog (#1)

? Base branch [main]: main
? Enable GigaChad mode (auto-merge PRs)? [y/N]: n
? Per-task budget limit (USD, blank for no limit): 2.00
? Configure Slack notifications? [y/N]: y
? Slack webhook URL: https://hooks.slack.com/...

Configuration saved to .chadgi/chadgi-config.yaml
Run 'chadgi validate' to verify your setup.

chadgi setup-project

Creates a GitHub Project v2 with the required Status field.

chadgi setup-project                      # Auto-detect repo
chadgi setup-project --repo owner/repo    # Specify repo
chadgi setup-project --name "My Tasks"    # Custom project name

Note: You may need to manually add Status field options via the GitHub web interface if they don't exist.

chadgi validate

Checks dependencies and configuration.

chadgi validate                          # Check default config
chadgi validate --config /path/to/config # Check specific config

chadgi start

Starts the automation loop.

chadgi start                             # Use default config
chadgi start --config /path/to/config    # Use specific config

Press Ctrl+C to stop gracefully.

chadgi watch

Monitor a running ChadGI session in real-time from another terminal.

chadgi watch                             # Live dashboard with auto-refresh
chadgi watch --once                      # Show current status without auto-refresh
chadgi watch --json --once               # Output machine-readable JSON status
chadgi watch --interval 5000             # Refresh every 5 seconds (default: 2000ms)

Example live dashboard:

==========================================================
                  CHADGI WATCH
==========================================================
Status: RUNNING /

Phase:  [CODE] IMPLEMENTATION

CURRENT TASK
  Issue:   #42
  Title:   Add user authentication
  Branch:  feature/issue-42-add-user-auth
  Elapsed: 5m 23s

ITERATION
  [######--------------] 2/5
  Retries remaining: 3

SESSION STATS
  Duration:  1h 23m 45s
  Completed: 3 task(s)
  Cost:      $0.4521

Last updated: 1/15/2026, 10:30:45 AM
Press Ctrl+C to exit

The watch command is useful for:

• Monitoring long-running sessions from another terminal
• Running ChadGI on remote servers or in detached mode
• Building external dashboards with --json --once
• Quick status checks without interrupting the main process

chadgi queue

View and manage the task queue before running ChadGI.

chadgi queue                             # List tasks in Ready column
chadgi queue list                        # Same as above (list is default)
chadgi queue --json                      # Output as JSON
chadgi queue --limit 5                   # Show only first 5 tasks
chadgi queue skip 123                    # Move issue #123 back to Backlog
chadgi queue promote 456                 # Move issue #456 to front of queue

Example output:

ChadGI Task Queue
=================
Ready column: 5 tasks

 #   Issue   Priority   Category   Title                          Status
--------------------------------------------------------------------------------
 1   #101    critical   feature    Add user authentication
 2   #102    high       bug        Fix login timeout issue
 3   #103    normal     refactor   Consolidate API handlers       blocked by #99
 4   #104    normal     bug        Handle null pointer in parser  deps resolved
 5   #105    low        feature    Add dark mode support

Commands:
  chadgi queue skip <issue-number>      Move task to Backlog
  chadgi queue promote <issue-number>   Move task to front
  chadgi start                          Process queue

Note: The skip command requires a "Backlog" column in your project board. The promote command requires priority ordering to be enabled in your config.

chadgi history

View task execution history with filtering and export options.

chadgi history                           # Show last 10 tasks
chadgi history --limit 50                # Show more entries
chadgi history --since 7d                # Tasks from last 7 days
chadgi history --since 2024-01-01        # Tasks since specific date
chadgi history --status failed           # Only show failed tasks
chadgi history --since 7d --status failed  # Combine filters
chadgi history --json                    # Machine-readable output

Example output:

==========================================================
                  CHADGI TASK HISTORY
==========================================================

Showing 10 of 45 total tasks

Summary
  Success: 8
  Failed:  2
  Total Time: 1h 23m 45s
  Total Cost: $0.8234

Task History
──────────────────────────────────────────────────────────────────────────────
#42 [SUCCESS]
  Add user authentication system
  Date:    Jan 15, 2026, 10:30:45 AM
  Elapsed: 12m 34s
  Cost:    $0.1234
  PR: https://github.com/owner/repo/pull/43
──────────────────────────────────────────────────────────────────────────────
#41 [FAILED]
  Fix database connection timeout
  Date:    Jan 15, 2026, 10:15:23 AM
  Elapsed: 8m 12s
  Reason: Build verification failed
──────────────────────────────────────────────────────────────────────────────

Supported time formats for --since:

• Relative: 7d (days), 2w (weeks), 1m (months), 24h (hours)
• Absolute: 2024-01-01 (ISO date format)

chadgi diff

Preview pending PR changes for a task. Useful for reviewing changes before PR creation or checking on in-progress work.

chadgi diff                              # Show diff of current in-progress task
chadgi diff 42                           # Show diff for issue #42's branch
chadgi diff --stat                       # Condensed file statistics view
chadgi diff --files                      # List only modified files
chadgi diff --pr 123                     # Show diff from an existing PR
chadgi diff --output changes.diff        # Save diff to a file
chadgi diff --json                       # Machine-readable output

Example output (--stat):

==========================================================
                    CHADGI DIFF
==========================================================

Issue:   #42
Branch:  feature/issue-42-add-user-authentication
Base:    main

Commits (3)
  abc1234 Add authentication middleware
  def5678 Implement login endpoint
  ghi9012 Add tests for auth flow

Summary
  5 files changed
  +142 insertions
  -12 deletions

Changes
  + src/middleware/auth.ts                           +45 -0
  M src/routes/index.ts                              +23 -5
  + src/routes/login.ts                              +38 -0
  M src/config.ts                                    +8 -2
  + tests/auth.test.ts                               +28 -5

Features:

• Syntax highlighting for terminal output (supports delta, diff-so-fancy if installed)
• Shows commit messages alongside changes
• Parses branch naming convention to find task branches
• Integrates with gh CLI for PR diffs

chadgi config export

Export your ChadGI configuration to a portable format for sharing with teammates or backing up.

chadgi config export                             # Export to stdout as JSON
chadgi config export -o team-config.json         # Export to file
chadgi config export --format yaml -o config.yaml  # Export as YAML
chadgi config export --exclude-secrets           # Strip sensitive data (webhook URLs, tokens)
chadgi config export -e -o shareable.json        # Combine flags for safe sharing

The export bundle includes:

• Configuration values from chadgi-config.yaml
• Template files (chadgi-task.md, chadgi-generate-task.md)
• Metadata: ChadGI version, export timestamp, source repository

Example export format (JSON):

{
  "_meta": {
    "chadgi_version": "1.0.5",
    "exported_at": "2026-01-15T10:30:00Z",
    "source_repo": "SwapLabsInc/ChadGI"
  },
  "config": {
    "github": {
      "project_number": 7,
      "ready_column": "Ready"
    },
    "iteration": {
      "max_iterations": 5,
      "gigachad_mode": false
    }
  },
  "templates": {
    "chadgi-task.md": "...",
    "chadgi-generate-task.md": "..."
  }
}

chadgi config import

Import a ChadGI configuration from an exported bundle.

chadgi config import team-config.json            # Import and replace existing config
chadgi config import config.yaml --merge         # Merge with existing config
chadgi config import config.json --dry-run       # Preview changes without writing

Options:

• --merge: Overlay imported config onto existing (instead of replacing)
• --dry-run: Preview changes without modifying files

Features:

• Validates imported config against current ChadGI version
• Warns about version mismatches (major version incompatibility is highlighted)
• Prompts for missing secrets (webhook URLs, API keys) during import
• Supports both JSON and YAML export formats

Typical workflows:

# Share configuration with teammates (exclude secrets)
chadgi config export --exclude-secrets > team-config.yaml

# Teammate imports and provides their own webhook URL
chadgi config import team-config.yaml

# Backup before making changes
chadgi config export -o backup-$(date +%Y%m%d).json

# Preview an import before applying
chadgi config import shared-config.json --dry-run

Configuration

Configuration File (chadgi-config.yaml)

# Task source - where to get tasks from
task_source: github-issues

# Template files (relative to .chadgi directory)
prompt_template: ./chadgi-task.md
generate_template: ./chadgi-generate-task.md
progress_file: ./chadgi-progress.json

# GitHub configuration
github:
  repo: owner/repo
  project_number: 1
  # Column names must match exactly (case-sensitive)
  ready_column: Ready
  in_progress_column: In progress
  review_column: In review
  done_column: Done  # Used when gigachad_mode is enabled

# Branch configuration
branch:
  base: main
  prefix: feature/issue-

# Polling settings
poll_interval: 10
consecutive_empty_threshold: 2

# What to do when queue is empty: generate, wait, exit
on_empty_queue: generate

# Iteration settings
iteration:
  max_iterations: 5
  completion_promise: "COMPLETE"
  ready_promise: "READY_FOR_PR"
  test_command: "npm test"
  build_command: "npm run build"
  on_max_iterations: skip
  gigachad_mode: false  # Auto-merge PRs without human review

# Output settings
output:
  show_tool_details: true
  show_cost: true
  truncate_length: 60

# Budget limits - protect against runaway costs
budget:
  per_task_limit: 2.00       # USD - skip task if exceeded
  per_session_limit: 20.00   # USD - stop session if exceeded
  on_task_budget_exceeded: skip   # skip | fail | warn
  on_session_budget_exceeded: stop  # stop | warn
  warning_threshold: 80      # Percentage at which to warn

Budget Limits

ChadGI can automatically stop when API costs exceed configured limits, protecting against runaway expenses:

budget:
  # Maximum cost (USD) for a single task before action is taken
  per_task_limit: 2.00

  # Maximum total cost (USD) for the entire ChadGI session
  per_session_limit: 20.00

  # What to do when per-task budget is exceeded
  # Options: skip (move to next task), fail (treat as failure), warn (log warning but continue)
  on_task_budget_exceeded: skip

  # What to do when per-session budget is exceeded
  # Options: stop (end session gracefully), warn (log warning but continue)
  on_session_budget_exceeded: stop

  # Percentage threshold for warning (0-100) - warns when approaching limit
  warning_threshold: 80

Behavior:

| Limit Type | Actions | Description | |------------|---------|-------------| | per_task_limit | skip | Skips the current task and moves to the next one | | | fail | Treats the task as failed (follows on_max_iterations behavior) | | | warn | Logs a warning but continues executing the task | | per_session_limit | stop | Gracefully stops the entire ChadGI session | | | warn | Logs a warning but continues processing tasks |

Warning Threshold:

When cost reaches 80% (default) of any limit, ChadGI logs a warning and sends a webhook notification (if configured). This gives you early notice before limits are hit.

Notes:

• Budget limits are checked after each Claude CLI invocation completes
• Costs are accumulated from Claude's JSON output (total_cost_usd field)
• Budget checks are skipped in --dry-run mode
• Set limit values to empty (per_task_limit: ) to disable that specific limit

Template Variables

Templates support these variables:

| Variable | Description | |----------|-------------| | {{ISSUE_NUMBER}} | GitHub issue number | | {{ISSUE_TITLE}} | Issue title | | {{ISSUE_URL}} | Full issue URL | | {{ISSUE_BODY}} | Issue description | | {{BRANCH_NAME}} | Created branch name | | {{BASE_BRANCH}} | Base branch (e.g., main) | | {{REPO}} | Repository (owner/repo) | | {{REPO_OWNER}} | Repository owner | | {{PROJECT_NUMBER}} | Project number | | {{READY_COLUMN}} | Ready column name | | {{COMPLETION_PROMISE}} | Completion signal string | | {{TEST_COMMAND}} | Configured test command | | {{BUILD_COMMAND}} | Configured build command |

GitHub Project Setup

ChadGI uses GitHub Projects v2 to manage tasks. You need a project with a Status field that has these options:

• Ready - Tasks waiting to be picked up
• In progress - Task currently being worked on
• In review - PR created, awaiting review
• Done - (Optional) Task completed via GigaChad Mode auto-merge

Option 1: Automatic Setup

chadgi setup-project --repo owner/repo

This creates the project but you may need to manually add Status options.

Option 2: Manual Setup

1. Go to your GitHub profile or organization
2. Click "Projects" tab
3. Click "New project" -> "Board"
4. Name your project (e.g., "ChadGI Tasks")
5. In the project settings, configure the Status field with options:
   • Ready
   • In progress
   • In review
   • Done (if using GigaChad Mode)
6. Note the project number from the URL

Adding Tasks

Add issues to the project and move them to the "Ready" column:

# Using GitHub CLI
gh issue create --repo owner/repo --title "Add dark mode" --body "Description..."
gh project item-add PROJECT_NUMBER --owner OWNER --url ISSUE_URL
# Then move to "Ready" column in the GitHub web interface

Or use the GitHub web interface to create issues and add them to the project.

Workflow

+-------------------------------------------------------------+
|                       CHADGI WORKFLOW                       |
+-------------------------------------------------------------+
|                                                             |
|   +-----------+                                             |
|   |   Ready   | <--- Finds tasks in "Ready" column          |
|   +-----+-----+                                             |
|         |                                                   |
|         v                                                   |
|  +-------------+                                            |
|  | In Progress | <--- Updates board, starts working         |
|  +------+------+                                            |
|         |                                                   |
|         v                                                   |
|   +---------------------+                                   |
|   | PHASE 1: IMPLEMENT  | <--- Claude implements & commits  |
|   |   (no PR yet)       |      Outputs: READY_FOR_PR        |
|   +----------+----------+                                   |
|              |                                              |
|              v                                              |
|   +---------------------+                                   |
|   | VERIFY: Test/Build  | <--- Runs configured test/build   |
|   +----------+----------+                                   |
|              |                                              |
|         Pass |  Fail --> Iterate (back to Phase 1)          |
|              v                                              |
|   +---------------------+                                   |
|   | PHASE 2: CREATE PR  | <--- Claude creates PR            |
|   |                     |      Outputs: COMPLETE            |
|   +----------+----------+                                   |
|              |                                              |
|              v                                              |
|   +------------+                                            |
|   |  In Review | <--- Updates board, PR ready               |
|   +-----+------+                                            |
|         |                                                   |
|         v                                                   |
|   Queue empty? --Yes--> Generate new tasks (optional)       |
|         |                                                   |
|         No                                                  |
|         |                                                   |
|         +-----------------> Loop to next task               |
+-------------------------------------------------------------+

Two-Phase Workflow

ChadGI ensures tests pass before creating a PR:

Phase 1: Implementation

1. Claude implements the feature/fix
2. Claude runs tests locally
3. Claude commits changes
4. Claude outputs <promise>READY_FOR_PR</promise>

Verification

• ChadGI runs test_command and build_command
• If verification fails, Claude iterates to fix issues
• Only proceeds to Phase 2 when verification passes

Phase 2: PR Creation

1. ChadGI confirms tests passed
2. Claude pushes branch and creates PR
3. Claude outputs <promise>COMPLETE</promise>

GigaChad Mode

For the truly fearless, GigaChad Mode bypasses human review entirely:

iteration:
  gigachad_mode: true

When enabled, after PR creation:

1. ChadGI automatically merges the PR into the target branch (squash merge)
2. Pulls the latest changes locally to prevent merge conflicts on next task
3. Moves the ticket directly to the "Done" column (not "In Review")

This is Chad-level confidence. Only enable if:

• You have comprehensive test coverage
• You trust your CI/CD pipeline
• You're comfortable with autonomous deployments
• You want maximum velocity

To use GigaChad Mode, you'll also need a "Done" column in your project board:

github:
  done_column: Done

Commit Prefix for Rollbacks

Auto-merged commits are prefixed with [GIGACHAD] by default, making it easy to identify autonomous merges in your git history:

[GIGACHAD] feat: add user authentication
[GIGACHAD] fix: resolve database connection issue
feat: manual human-reviewed commit

To rollback to the last human-approved commit:

# Find the last non-GigaChad commit
git log --oneline | grep -v "^\[GIGACHAD\]" | head -1

# Or reset to before GigaChad started
git log --oneline --all | grep -v GIGACHAD

Customize the prefix in your config:

iteration:
  gigachad_commit_prefix: "[AUTO]"  # Or "[BOT]", "🤖", etc.

Safety Notes

ChadGI runs Claude Code with --dangerously-skip-permissions

This means Claude Code will:

• Execute commands without confirmation
• Create/modify/delete files automatically
• Push code to GitHub
• Create Pull Requests
• Create GitHub issues (when generating tasks)
• With GigaChad Mode: Auto-merge PRs without human review

Recommended safeguards:

1. Run in a dedicated terminal you can monitor
2. Have your repository backed up
3. Review PRs before merging (unless using GigaChad Mode)
4. Use a test repository first
5. Set higher poll_interval for more review time
6. Avoid GigaChad Mode on production repositories without comprehensive tests

Troubleshooting

"No tasks found in 'Ready' column"

• Add issues to your project and move them to "Ready"
• Verify column names match exactly (case-sensitive)
• Wait for task generation if on_empty_queue: generate

"Could not find project #N"

• Check the project number in your config
• Ensure GitHub CLI has project scope: gh auth refresh -s project

Config file not loading

• Ensure you ran chadgi init
• Check path: ./.chadgi/chadgi-config.yaml
• Use --config flag to specify custom path

Template not found

• Templates should be in the .chadgi/ directory
• Paths are relative to the config file location

"gh auth" errors

• Re-authenticate: gh auth login
• Add project scope: gh auth refresh -s project

Progress file shows interrupted session

• Check the branch and issue mentioned
• The previous task may be partially complete
• ChadGI will continue from where it left off

Testing

ChadGI uses two types of tests:

Unit Tests (Jest/TypeScript)

Unit tests cover core utilities and logic functions:

npm run test:unit           # Run unit tests
npm run test:coverage       # Run with coverage report
npm run test:watch          # Watch mode for development

Test coverage targets:

• src/utils/formatting.ts - Date, duration, and value formatting
• src/utils/config.ts - YAML parsing and configuration loading
• src/utils/data.ts - Session stats and metrics data loading

Unit tests use:

• Jest with ts-jest for TypeScript support
• memfs for virtual file system mocking
• jest.unstable_mockModule for ESM module mocking

Bash Unit Tests (Bats)

Bash function unit tests use bats-core to test pure functions in scripts/chadgi.sh:

npm run test:bash           # Run bash unit tests

Test coverage targets:

• mask_secrets - Secret pattern redaction
• parse_log_level - Log level string to number conversion
• strip_colors - ANSI escape sequence removal
• format_duration - Time formatting (hours/minutes/seconds)
• parse_yaml_value - YAML key-value extraction
• calculate_budget_percentage - Budget percentage calculation
• check_task_budget_exceeded / check_session_budget_exceeded - Budget threshold detection

Integration Tests (Bash)

Integration tests verify CLI commands and end-to-end workflows:

npm run test:integration    # Run all integration tests

These tests spawn actual ChadGI processes and verify output.

Running All Tests

npm test                    # Runs unit, bash, and integration tests

License

MIT