1.0.1 • Published yesterdayCLI

gh-auto-agent

Licence

MIT

Version

1.0.1

Deps

Size

176 kB

Vulns

Weekly

Summary Dependency Versions

gh-auto-agent

An autonomous GitHub agent for your terminal. It runs the repetitive Git/GitHub work for you — creating repos, shipping pull requests, and automatically fixing failing CI — then retries until it succeeds.

Detect → Think → Fix → Ship. You say what you want; the agent figures out how.

Install in one line

npm install -g gh-auto-agent

That's it. The agent command now works in any folder. Or run it without installing using npx:

npx gh-auto-agent help

Note: the agent drives the GitHub CLI (gh) and git under the hood, so you also need those installed and logged in. See Prerequisites.

What it actually does (in plain English)

Normally, shipping a code change means running ~8 commands by hand:

git checkout -b feature/x   →   git add .   →   git commit -m "…"
→   git push -u origin …   →   gh pr create   →   (wait for CI)
→   gh pr merge   →   git checkout main && git pull

With this agent, that's one command:

agent ship "add login page"

And when your CI (automated tests on GitHub) fails, instead of you opening the logs and debugging, the agent reads the failure, works out the cause, fixes it, and re-runs — on its own.

You want to…	Old way	With the agent
Start a new project	6–7 setup commands	`agent init my-app`
Ship a change	8 commands + waiting	`agent ship "message"`
Fix broken CI	Manual log reading + retries	`agent fix`
Keep CI healthy	Watch it yourself	`agent watch`

What Makes This Different

This is not a thin gh wrapper. It's an agent that:

Understands context — detects your language, framework, project state
Reasons about failures — when AI is enabled, it diagnoses errors it has never seen before (not just static pattern matching)
Self-heals — detects failures, applies fixes, retries autonomously
Knows when NOT to add value — uses native single gh commands where they already do the job

Static vs AI — a deliberate split

Task	How it works	Why
Auth, push, merge, labels, branch protection	Static (single `gh`/git command)	Deterministic — AI adds latency & risk, no benefit
Known errors (auth failed, push rejected, conflicts…)	Static regex → fixed command	Fast, predictable, offline
Unknown CI failures	AI root-cause analysis → safe fix	Patterns can't cover every error
Workflow failed	AI diagnoses WHY, fixes root cause	Beats blindly re-running the same failure
Commit messages	AI reads the diff → conventional commit	Meaningful, not "update 3 files"
PR descriptions	AI summarises real code changes	Actual context for reviewers

If no AI provider is configured, the agent runs fully in static mode — every known error is still handled deterministically. AI is strictly additive.

Enabling AI (optional)

AI is off by default and only activates when a provider is configured.

Easiest: a `.env` file

cp .env.example .env

Then edit .env and uncomment ONE provider:

# Pick one:
GITHUB_TOKEN=ghp_...          # GitHub Models (free for GitHub users)
OPENAI_API_KEY=sk-...         # OpenAI
AGENT_AI_PROVIDER=ollama      # Local model via Ollama (no key, private)

The agent loads .env automatically on every run. The file is git-ignored, and real shell environment variables always take precedence over it.

Or export in your shell

export OPENAI_API_KEY=sk-...
export GITHUB_TOKEN=ghp_...
export AGENT_AI_PROVIDER=ollama
# Azure:
export AZURE_OPENAI_API_KEY=...
export AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com

Search order for `.env`

$AGENT_ENV_FILE (explicit path override)
./.env in the current working directory
.env next to the agent install

Check status anytime:

agent ai

Safety: AI-suggested commands are filtered — destructive operations (rm -rf, force-push to main, hard reset, sudo, etc.) are blocked and never executed. Commands only run when the model's confidence ≥ 0.5.

Prerequisites

The agent itself is a small Node.js program, but it operates the GitHub CLI and Git — so you need all three installed:

Tool	Version	Check it	Install
Node.js	≥ 18	`node --version`	https://nodejs.org
Git	any recent	`git --version`	https://git-scm.com
GitHub CLI (`gh`)	≥ 2.0	`gh --version`	https://cli.github.com

Then log in to GitHub once (this stores your credentials securely — the agent never sees your password or token):

gh auth login

Installation

Pick whichever fits you:

1. Global install (recommended)

npm install -g gh-auto-agent
agent help

The agent command is now available everywhere on your machine.

2. No install — run on demand with `npx`

npx gh-auto-agent help
npx gh-auto-agent status

Great for trying it once, or in CI where you don't want a global install.

3. From source (for development)

git clone https://github.com/tarunReddy20/gh-auto-agent.git
cd gh-auto-agent
npm link          # makes the local code available as the `agent` command
npm test          # run the 91-test suite

60-second Quickstart

# 1. Check your setup
agent help
gh auth status

# 2. Go into ANY of your project folders (a git repo)
cd path/to/your/project

# 3. See a live health dashboard (read-only, safe)
agent status

# 4. Ship a change end-to-end (branch → commit → push → PR → merge)
agent ship "fix: correct typo in header"

# 5. If CI ever breaks, repair it automatically
agent fix

The agent always acts on the repository in your current folder. There is nothing to deploy and no server — it runs locally, like git itself.

Command Reference (at a glance)

Command	What it does	Common flags
`agent init [name]`	Create repo + README + .gitignore + license + CI	`--template <lang>`, `--public`
`agent ship [msg]`	Branch → commit → push → PR → merge	`--draft`, `--no-merge`
`agent fix`	Scan & auto-repair broken CI, conflicts, configs	—
`agent heal`	Deep health scan + repair	`--dry-run`
`agent watch`	Continuously monitor CI, auto-fix failures	`--interval <sec>`, `--once`
`agent deploy [env]`	Test → tag → release → deploy, rollback on fail	`--tag <v>`, `--rollback`
`agent pipeline <run\|create\|list>`	Run YAML multi-step pipelines	—
`agent team <setup\|assign\|label>`	Reviewer & label automation	—
`agent status`	Live project health dashboard (read-only)	—
`agent ai`	Show AI provider status & setup help	—
`agent state <show\|reset>`	Inspect/clear agent state	—
`agent help`	Full command reference	—

Detailed docs for each command follow below.

Smart Commands

`agent init [name]` — Project Bootstrap

Leans on native gh flags instead of chaining commands. A single gh repo create NAME --clone --add-readme --gitignore <tpl> --license mit handles repo + README + .gitignore + license + clone. The agent only adds what gh can't do natively: the CI workflow (language-aware).

agent init my-app              # Auto-detect language, scaffold everything
agent init api --template node --public

What you get:

GitHub repo (via native gh)
README, .gitignore (GitHub template), MIT license (via native gh)
Language-aware CI workflow (the agent's value-add)
Issue labels + branch protection (single gh calls)

`agent ship [message]` — Working Tree to Merged PR

One command goes from dirty working directory to merged pull request:

Creates feature branch (if on main)
Generates smart commit message from diff
Stages, commits, pushes (with self-healing)
Creates PR with context-aware title/body
Waits for CI to pass
Auto-merges

agent ship "feat: add authentication"
agent ship --draft              # Stop at draft PR
agent ship --no-merge           # Create PR but don't merge

`agent fix` — Auto-Diagnose & Repair

Scans your repo for all broken things and fixes them:

Failing CI workflows → analyzes logs, reruns
PR merge conflicts → rebases, resolves
Missing CI config → generates appropriate workflow
Push issues → pulls, rebases, force-pushes safely
Stale state → cleans up

agent fix

`agent heal` — Deep Health Scan

Comprehensive repo audit:

Failed workflow runs
Stale merged branches (auto-deletes)
Conflicted PRs
Missing configs (CI, README, .gitignore)
Security issues (.env files in history)

agent heal                     # Fix everything
agent heal --dry-run           # Preview without applying

`agent watch` — Continuous Monitoring

Real-time workflow monitor that auto-fixes failures as they occur:

agent watch                    # Monitor forever (30s interval)
agent watch --interval 60      # Check every 60 seconds
agent watch --once             # Single check cycle

`agent deploy [env]` — Full Deployment Pipeline

Complete deployment with safety:

Ensures you're on main, up-to-date
Runs local tests
Auto-bumps version (or uses --tag)
Creates git tag + GitHub release
Monitors deployment workflow
Auto-rollbacks on failure

agent deploy production
agent deploy staging --tag v2.1.0
agent deploy --rollback         # Revert last deploy

Pipeline Engine

Define custom multi-step workflows in YAML:

agent pipeline create release   # Scaffold a template
agent pipeline run release.yml  # Execute it
agent pipeline list             # See available pipelines

Pipeline files (.agent/pipelines/*.yml):

name: release
steps:
  - name: Run tests
    run: npm test
  - name: Build
    run: npm run build
  - name: Push
    action: push
    with:
      message: "chore: release build"
  - name: Create PR
    action: pr-create
    with:
      title: "Release"
  - name: Merge
    action: pr-merge

Steps auto-heal: if a step fails, the agent parses the error, applies a fix, and retries.

Team Automation

agent team setup               # Configure rules + create labels
agent team assign              # Auto-assign reviewers to open PRs
agent team label               # Auto-label PRs by file changes

Configuration lives in .agent/team.json:

Path-based reviewer assignment
File-pattern label mapping
PR size labels (S/M/L/XL)
Round-robin reviewer selection
Auto-generated CODEOWNERS

Project Intelligence

agent status                   # Full health dashboard

Shows:

Git status (branch, modified files, sync state)
CI health (workflows, recent runs)
Open PRs
Project analysis (language, framework, tests, docs)
Actionable recommendations

Self-Healing Loop

Every operation follows:

EXECUTE → FAIL → PARSE → THINK → FIX → RETRY → VERIFY

Error Pattern	Autonomous Fix
Auth failed	Re-authenticate via `gh auth login`
Permission denied	Re-auth + retry
Branch missing	Create branch + push upstream
Merge conflict	Pull rebase → resolve → push
Workflow failed	Analyze logs → rerun
Workflow missing	Detect language → generate CI
Push rejected	Pull rebase → force-push (with-lease)
Rate limited	Wait 60s → retry
Network error	Wait 10s → retry

Max retries: 5. Stops on success or unrecoverable error.

Architecture

gh-auto-agent/
├── index.js                  # CLI entry point
├── package.json
├── core/
│   ├── executor.js           # Shell execution (sync, stream, retry)
│   ├── logger.js             # Colored + file logging
│   ├── stateManager.js       # Execution state persistence
│   ├── env.js                # Zero-dependency .env loader
│   └── ai.js                 # LLM client (OpenAI/GitHub/Azure/Ollama)
├── modules/
│   ├── orchestrator.js       # Brain: init, ship, fix, heal, watch, deploy
│   ├── intelligence.js       # Context analysis & recommendations
│   ├── pipeline.js           # YAML pipeline engine
│   ├── team.js               # Reviewer & label automation
│   ├── github.js             # GitHub CLI operations
│   ├── workflow.js           # Self-healing execution loop
│   ├── autofix.js            # Static fixes + AI fallback for unknowns
│   ├── parser.js             # Log error pattern matching
│   └── yaml-lite.js          # Zero-dependency YAML parser
├── examples/workflows/       # CI templates
├── tests/test-runner.js      # 91 unit tests
└── .agent/
    ├── pipelines/            # Custom pipeline definitions
    └── team.json             # Team automation config

Security

Authenticated via gh auth login (no stored tokens)
Force push uses --force-with-lease only
GH_NO_PROMPT=1 prevents interactive stalls
Respects repo permissions
Detects .env files in history (heal command)

Zero Dependencies

This project has no npm dependencies. Everything is built-in:

Custom YAML parser (yaml-lite.js)
Custom glob matching
LLM client uses Node's native fetch (Node 18+) — no SDK needed
Node.js child_process for shell execution

Why it matters: nothing to audit, no supply-chain risk, and a tiny, fast install.

Testing

The project ships with a 91-test offline suite (no network or GitHub needed):

npm test

It covers the error parser, state manager, YAML parser, AI provider detection, the command safety filter, and the .env loader. Expected result:

  Passed: 91
  Failed: 0
  Total:  91

To try the agent for real, use a throwaway repo and delete it afterward — the full step-by-step walkthrough is in docs/USAGE.md.

Troubleshooting

Symptom	Cause	Fix
`gh: command not found`	GitHub CLI not installed	Install from https://cli.github.com
Auth errors on every command	Not logged in	Run `gh auth login`
`agent: command not found` after install	npm global bin not on PATH	Run `npm bin -g` and add that folder to PATH, or use `npx gh-auto-agent`
`agent ai` says "No AI provider"	No key configured	Add a key to `.env` or export it (AI is optional)
Force-push seems blocked	Safety by design	The agent only uses `--force-with-lease`
A command seems stuck	Waiting on CI or a run to start	It polls automatically; give it a moment

Diagnostics:

agent state show          # last task, retry count, history
gh auth status            # verify GitHub auth
gh run list --limit 5     # recent workflow runs

Per-run logs are written to logs/github/{runId}.log (command, output, detected error, fix applied).

Full Documentation

How It Works — architecture, problems solved, benefits, and diagrams
Usage & Testing — install, every command, and detailed test steps

gh-auto-agent

gh-auto-agent

Install in one line

What it actually does (in plain English)

What Makes This Different

Static vs AI — a deliberate split

Enabling AI (optional)

Easiest: a `.env` file

Or export in your shell

Search order for `.env`

Prerequisites

Installation

1. Global install (recommended)

2. No install — run on demand with `npx`

3. From source (for development)

60-second Quickstart

Command Reference (at a glance)

Smart Commands

`agent init [name]` — Project Bootstrap

`agent ship [message]` — Working Tree to Merged PR

`agent fix` — Auto-Diagnose & Repair

`agent heal` — Deep Health Scan

`agent watch` — Continuous Monitoring

`agent deploy [env]` — Full Deployment Pipeline

Pipeline Engine

Team Automation

Project Intelligence

Self-Healing Loop

Architecture

Security

Zero Dependencies

Testing

Troubleshooting

Full Documentation

Contributing / Publishing

License

Keywords