# 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 PR's CI failures
cimonitor logs --pr 123 | claude \
"Analyze these CI failures and fix the issues. Commit and push the fixes when done."
# 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/4a/df/23643b99edd03300a9090d4153e06f1ec628b1ff459337e78ab6961217ad/cimonitor-0.1.0.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 PR's CI failures\ncimonitor logs --pr 123 | claude \\\n \"Analyze these CI failures and fix the issues. Commit and push the fixes when done.\"\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.0",
"project_urls": null,
"split_keywords": [
"actions",
" ci",
" debugging",
" devops",
" github",
" logs",
" monitor",
" workflow"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "540b864ee7e879ee50282b702e9d7debdd5a623651353c5e6da37e6555852d2f",
"md5": "3b54e658298ef682e3399b5786c6aaef",
"sha256": "0b723c8f94bdfe674e40c97bf2fedeb4620ca64344403d239bfdf265dc537cc7"
},
"downloads": -1,
"filename": "cimonitor-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3b54e658298ef682e3399b5786c6aaef",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 12594,
"upload_time": "2025-07-13T20:14:25",
"upload_time_iso_8601": "2025-07-13T20:14:25.710213Z",
"url": "https://files.pythonhosted.org/packages/54/0b/864ee7e879ee50282b702e9d7debdd5a623651353c5e6da37e6555852d2f/cimonitor-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4adf23643b99edd03300a9090d4153e06f1ec628b1ff459337e78ab6961217ad",
"md5": "29cedc7353e7a28f20acc99284139b5a",
"sha256": "ed0febde55e66c7a0c56a64960295b992cfb2f3a065e13fb3032dca9563af08b"
},
"downloads": -1,
"filename": "cimonitor-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "29cedc7353e7a28f20acc99284139b5a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 47527,
"upload_time": "2025-07-13T20:14:27",
"upload_time_iso_8601": "2025-07-13T20:14:27.214377Z",
"url": "https://files.pythonhosted.org/packages/4a/df/23643b99edd03300a9090d4153e06f1ec628b1ff459337e78ab6961217ad/cimonitor-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-13 20:14:27",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "cimonitor"
}
JSON