# CI Monitor
CI Monitor is a command-line tool that lets AI agents and humans instantly access GitHub CI status, logs, and failure details without leaving the terminal.
**Eliminates Copy-Paste Development** - No more copying error messages from GitHub's web interface. Agents can directly access CI failures, logs, and status updates through a simple command-line interface.
**Universal Agent Compatibility** - Works with any AI coding assistant (Claude Code, Cursor, etc.) that can run terminal commands.
## Automated CI Debugging with Claude Code
```bash
# Single command to investigate and fix your active branch's CI failures
claude "Use cimonitor to watch my PR's CI. If the tests fail, fix and push. \
Notify me when finished or if you can't solve the problem. Think hard."
# Auto-retry flaky tests and get notified only for real failures
cimonitor watch --pr 123 --retry 3 | claude \
"Monitor this output. If tests still fail after retries, analyze the logs and notify me with a summary of the real issues."
```
This powerful combination lets you:
- **Stay Focused**: No need to monitor job status and engage with an agent if you see a failure—let the agent do the waiting
- **Fix Real Issues**: Claude Code automatically parses CI logs, identifies root causes, implements fixes, and pushes solutions
- **Handle Flaky Tests**: Auto-retry failing jobs up to N times, only getting notified if failures persist
## Installation
```bash
pip install cimonitor
export GITHUB_TOKEN="your_github_token_here"
```
How to generate a token:
1. Visit [https://github.com/settings/tokens](https://github.com/settings/tokens),
2. "Generate new token" -> "Generate new token (classic)"
3. Check "repo" and "workflow"
4. Generate the token and export it as an environment variable as shown above
## Usage
```bash
# Check CI status
cimonitor status # Current branch
cimonitor status --pr 123 # Specific PR
cimonitor status --commit abc1234 # Specific commit
# Get error logs
cimonitor logs # Current branch (filtered logs)
cimonitor logs --pr 123 # PR logs
cimonitor logs --raw # Raw unfiltered logs
cimonitor logs --job-id 12345678 # Specific job logs
# Watch CI progress
cimonitor watch # Watch current branch
cimonitor watch --until-complete # Wait for completion
cimonitor watch --until-fail # Stop on first failure
cimonitor watch --retry 3 # Auto-retry failed jobs up to 3 times
```
## Command Reference
### Main Command
```
Usage: cimonitor [OPTIONS] COMMAND [ARGS]...
CI Monitor - Monitor GitHub CI workflows, fetch logs, and track build
status.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
logs Show error logs for failed CI jobs.
status Show CI status for the target commit/branch/PR.
watch Watch CI status with real-time updates.
```
### cimonitor status
```
Usage: cimonitor status [OPTIONS]
Show CI status for the target commit/branch/PR.
Options:
--pr, --pull-request INTEGER Pull request number to check
--commit TEXT Specific commit SHA to check
--branch TEXT Specific branch to check (defaults to current
branch)
-v, --verbose Show verbose output
--help Show this message and exit.
```
### cimonitor logs
```
Usage: cimonitor logs [OPTIONS]
Show error logs for failed CI jobs.
Options:
--pr, --pull-request INTEGER Pull request number to check
--commit TEXT Specific commit SHA to check
--branch TEXT Specific branch to check (defaults to current
branch)
-v, --verbose Show verbose output
--raw Show complete raw logs (for debugging)
--job-id INTEGER Show logs for specific job ID only
--help Show this message and exit.
```
### cimonitor watch
```
Usage: cimonitor watch [OPTIONS]
Watch CI status with real-time updates.
Options:
--pr, --pull-request INTEGER Pull request number to check
--commit TEXT Specific commit SHA to check
--branch TEXT Specific branch to check (defaults to current
branch)
-v, --verbose Show verbose output
--until-complete Wait until all workflows complete
--until-fail Stop on first failure
--retry COUNT Auto-retry failed jobs up to COUNT times
--help Show this message and exit.
```
## What Agents Can Do
**Instant CI Diagnosis** - Check any commit, branch, or PR for failures and get structured output perfect for programmatic analysis.
**Real-Time Monitoring** - Use `watch --until-complete` to watch CI progress live, `watch --until-fail` for fail-fast workflows, or `watch --retry N` to automatically retry failed jobs and filter out flaky test failures.
**Targeted Debugging** - Get step-level failure details and filtered error logs without downloading massive raw logs.
**Multi-Branch Operations** - Seamlessly check CI status across different branches, PRs, and commits in automated workflows.
## License
MIT License - see [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "cimonitor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "actions, ci, debugging, devops, github, logs, monitor, workflow",
"author": null,
"author_email": "Steve Landey <steve@steveasleep.com>",
"download_url": "https://files.pythonhosted.org/packages/0e/61/4e45b0e7a0ffac9c698306f40811e1670c8c6f83890ebe3d03fb3996af1d/cimonitor-0.1.6.tar.gz",
"platform": null,
"description": "# CI Monitor\n\nCI Monitor is a command-line tool that lets AI agents and humans instantly access GitHub CI status, logs, and failure details without leaving the terminal.\n\n**Eliminates Copy-Paste Development** - No more copying error messages from GitHub's web interface. Agents can directly access CI failures, logs, and status updates through a simple command-line interface.\n\n**Universal Agent Compatibility** - Works with any AI coding assistant (Claude Code, Cursor, etc.) that can run terminal commands.\n\n## Automated CI Debugging with Claude Code\n\n```bash\n# Single command to investigate and fix your active branch's CI failures\nclaude \"Use cimonitor to watch my PR's CI. If the tests fail, fix and push. \\\nNotify me when finished or if you can't solve the problem. Think hard.\"\n\n# Auto-retry flaky tests and get notified only for real failures\ncimonitor watch --pr 123 --retry 3 | claude \\\n \"Monitor this output. If tests still fail after retries, analyze the logs and notify me with a summary of the real issues.\"\n```\n\nThis powerful combination lets you:\n- **Stay Focused**: No need to monitor job status and engage with an agent if you see a failure\u2014let the agent do the waiting\n- **Fix Real Issues**: Claude Code automatically parses CI logs, identifies root causes, implements fixes, and pushes solutions\n- **Handle Flaky Tests**: Auto-retry failing jobs up to N times, only getting notified if failures persist\n\n## Installation\n\n```bash\npip install cimonitor\nexport GITHUB_TOKEN=\"your_github_token_here\"\n```\n\nHow to generate a token:\n1. Visit [https://github.com/settings/tokens](https://github.com/settings/tokens),\n2. \"Generate new token\" -> \"Generate new token (classic)\"\n3. Check \"repo\" and \"workflow\"\n4. Generate the token and export it as an environment variable as shown above\n\n## Usage\n\n```bash\n# Check CI status\ncimonitor status # Current branch\ncimonitor status --pr 123 # Specific PR\ncimonitor status --commit abc1234 # Specific commit\n\n# Get error logs\ncimonitor logs # Current branch (filtered logs)\ncimonitor logs --pr 123 # PR logs\ncimonitor logs --raw # Raw unfiltered logs\ncimonitor logs --job-id 12345678 # Specific job logs\n\n# Watch CI progress\ncimonitor watch # Watch current branch\ncimonitor watch --until-complete # Wait for completion\ncimonitor watch --until-fail # Stop on first failure\ncimonitor watch --retry 3 # Auto-retry failed jobs up to 3 times\n```\n\n## Command Reference\n\n### Main Command\n```\nUsage: cimonitor [OPTIONS] COMMAND [ARGS]...\n\n CI Monitor - Monitor GitHub CI workflows, fetch logs, and track build\n status.\n\nOptions:\n --version Show the version and exit.\n --help Show this message and exit.\n\nCommands:\n logs Show error logs for failed CI jobs.\n status Show CI status for the target commit/branch/PR.\n watch Watch CI status with real-time updates.\n```\n\n### cimonitor status\n```\nUsage: cimonitor status [OPTIONS]\n\n Show CI status for the target commit/branch/PR.\n\nOptions:\n --pr, --pull-request INTEGER Pull request number to check\n --commit TEXT Specific commit SHA to check\n --branch TEXT Specific branch to check (defaults to current\n branch)\n -v, --verbose Show verbose output\n --help Show this message and exit.\n```\n\n### cimonitor logs\n```\nUsage: cimonitor logs [OPTIONS]\n\n Show error logs for failed CI jobs.\n\nOptions:\n --pr, --pull-request INTEGER Pull request number to check\n --commit TEXT Specific commit SHA to check\n --branch TEXT Specific branch to check (defaults to current\n branch)\n -v, --verbose Show verbose output\n --raw Show complete raw logs (for debugging)\n --job-id INTEGER Show logs for specific job ID only\n --help Show this message and exit.\n```\n\n### cimonitor watch\n```\nUsage: cimonitor watch [OPTIONS]\n\n Watch CI status with real-time updates.\n\nOptions:\n --pr, --pull-request INTEGER Pull request number to check\n --commit TEXT Specific commit SHA to check\n --branch TEXT Specific branch to check (defaults to current\n branch)\n -v, --verbose Show verbose output\n --until-complete Wait until all workflows complete\n --until-fail Stop on first failure\n --retry COUNT Auto-retry failed jobs up to COUNT times\n --help Show this message and exit.\n```\n\n## What Agents Can Do\n\n**Instant CI Diagnosis** - Check any commit, branch, or PR for failures and get structured output perfect for programmatic analysis.\n\n**Real-Time Monitoring** - Use `watch --until-complete` to watch CI progress live, `watch --until-fail` for fail-fast workflows, or `watch --retry N` to automatically retry failed jobs and filter out flaky test failures.\n\n**Targeted Debugging** - Get step-level failure details and filtered error logs without downloading massive raw logs.\n\n**Multi-Branch Operations** - Seamlessly check CI status across different branches, PRs, and commits in automated workflows.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Monitor GitHub CI workflows, fetch logs, and track build status",
"version": "0.1.6",
"project_urls": null,
"split_keywords": [
"actions",
" ci",
" debugging",
" devops",
" github",
" logs",
" monitor",
" workflow"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d58ebdbb3d060d148f0198862b86ffa3189020bc7aa76fddcd734c491938cc1d",
"md5": "1573fb9c778fa057f139e85613801f3d",
"sha256": "1bff7dbce871991731a755692778d4812ac47199348cbbbba7990522f35288a4"
},
"downloads": -1,
"filename": "cimonitor-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1573fb9c778fa057f139e85613801f3d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 22940,
"upload_time": "2025-07-18T21:42:04",
"upload_time_iso_8601": "2025-07-18T21:42:04.736399Z",
"url": "https://files.pythonhosted.org/packages/d5/8e/bdbb3d060d148f0198862b86ffa3189020bc7aa76fddcd734c491938cc1d/cimonitor-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0e614e45b0e7a0ffac9c698306f40811e1670c8c6f83890ebe3d03fb3996af1d",
"md5": "1c84f232eb82432052ea7e19027905d0",
"sha256": "600ec5bae05db0f2d15e21eeecaca70e089830d4884bf05aa3faffd25f9783f3"
},
"downloads": -1,
"filename": "cimonitor-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "1c84f232eb82432052ea7e19027905d0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 60804,
"upload_time": "2025-07-18T21:42:06",
"upload_time_iso_8601": "2025-07-18T21:42:06.038276Z",
"url": "https://files.pythonhosted.org/packages/0e/61/4e45b0e7a0ffac9c698306f40811e1670c8c6f83890ebe3d03fb3996af1d/cimonitor-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 21:42:06",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "cimonitor"
}
JSON