cicaid

One CLI for the GitHub-plumbing every repo ends up needing: sync issues, branch onto one, check out a PR, run the repo's local CI checks, link a PR back to its issue, auto-merge green Dependabot PRs. Install once — every command auto-detects the repo from your origin remote.

This is the free shell. The LLM-backed commands (triage-issues, review-issue, create-issue, local-review, pr-review, commit-and-push, implement-issue-with-aider, clear-ai-slop-issues) are part of cicaid-pro, a private package — cicaid <command> reports itself unavailable with a pointer there until it's installed.

Install

pip install "cicaid-devtools @ https://github.com/leonarduk/cicaid/releases/download/v0.6.0/cicaid_devtools-0.6.0-py3-none-any.whl"

This always points at the latest release — the install command above is updated automatically as part of every release, so it never goes stale. Want an older version instead? See Releases for every version's exact install command.

The standard installation loads GITHUB_TOKEN and similar from a repo-root .env file for local runs (CI should set real env vars instead). The historical [dotenv] extra remains available as a backwards-compatible alias:

pip install "cicaid-devtools[dotenv] @ https://github.com/leonarduk/cicaid/releases/download/v0.6.0/cicaid_devtools-0.6.0-py3-none-any.whl"

For tracking an unreleased commit instead of a tagged version:

pip install "cicaid-devtools @ git+https://github.com/leonarduk/cicaid.git@<ref>"

Quick start

cd your-repo                 # any repo with a github.com origin remote
cicaid --help                # list every command
cicaid help work-on-issue    # show one command's usage and parameters
cicaid sync-issues           # pull open issues into ./issues/*.md
cicaid work-on-issue 123     # branch + checkout for issue #123
cicaid publish-pr            # open the PR
cicaid run-ci-checks --list  # this repo's local check suite

Every command can be called by its full name or its two-letter abbreviation shown next to it (cicaid si for sync-issues) — cicaid --help lists them all.

Non-interactive use

Every command already avoids prompting when its arguments fully specify what to do (e.g. work-on-pr 123, run-ci-checks --check NAME, update-issue 123 --yes). Set CICAID_NON_INTERACTIVE=1 to make any command that would otherwise prompt (an unspecified PR to check out, an unselected check menu, an unconfirmed issue update) exit with a clear error instead, so an AI driver (Claude Code, aider, ...) can rely on one env var rather than a different flag per command.

Link checking

cicaid check-links validates markdown links in tracked *.md files:

• Same-repo relative links — the target path must exist in the working tree; a #anchor must match a heading in the target file.
• Sibling-repo blob links (github.com/leonarduk/<repo>/blob/<ref>/<path>) — resolved against the sibling checkout (the directory next to this repo) via git cat-file. A path that exists only on an unmerged branch produces a warning; a path missing at the stated ref is an error.
• External http(s) links — skipped (out of scope for v1).

cicaid check-links            # check all tracked .md files
cicaid check-links --root /path/to/repo

Wire it into your .cicaid-checks.toml so it runs with cicaid run-ci-checks:

[[checks]]
name = "links"
description = "Validate markdown links"
workflow = ".github/workflows/ci.yml"
commands = ["cicaid check-links"]

Knowledge-graph orchestration across repos

graphify-repos runs graphify (a codebase knowledge-graph generator, installed separately with pip install graphifyy) across a configured list of repos and collects their output into one combined directory. List the repos in a .cicaid-graphify.toml file:

[[repos]]
name = "allotmint"
url = "https://github.com/leonarduk/allotmint"
extract = true          # ask for full semantic extraction, if an API key is set

[[repos]]
name = "cicaid"
url = "https://github.com/leonarduk/cicaid"

cicaid graphify-repos --all         # every repo in the config
cicaid graphify-repos --repo cicaid # just one
cicaid graphify-repos --all --dry-run  # show what would run, without touching anything

MCP server

cicaid-mcp exposes every discovered command (this repo's own, plus any installed extension's, e.g. cicaid-pro) as an MCP tool, so MCP-capable clients can call them directly instead of shelling out. Requires the optional mcp extra:

pip install "cicaid-devtools[mcp]"
cicaid-mcp

Access to cicaid-pro

The LLM review/triage engine is the part of cicaid that's actually hard to reproduce, and is kept in a private package, cicaid-pro. Contact the maintainer for access.

Releasing

Releases are cut from the GitHub UI, not by hand-bumping a version file — pyproject.toml has no version field; setuptools-scm derives it from the git tag at build time.

1. Go to Releases → Draft a new release.
2. Create a new tag (the most recently published release is `v0.6.0`, so pick the next one) targeting main, and publish the release.

The release workflow is triggered when a v* tag is pushed. Publishing through the GitHub UI as described above triggers it by creating and pushing the new tag; publishing a release for an existing tag does not trigger the workflow again. The workflow builds the sdist/wheel, uploads them as release assets, and pushes a commit updating this README's install commands and the tag above to the new version — all automatically.

License

MIT — see LICENSE.