Install and configure the Chunk CLI
The chunk CLI is a developer tool for AI-assisted development workflows. It works with AI coding agents such as Claude Code, Cursor, and VS Code Copilot, and does two things:
-
Generates team review context: mines your GitHub PR review history, analyzes it with Claude, and produces a
.chunk/context/review-prompt.mdfile that encodes how your team actually reviews code. AI coding agents pick this file up automatically and apply your team’s standards. -
Validates changes remotely: runs your quality checks (tests, lint, format) in a clean CircleCI Cloud environment before you push, so you catch failures that only reproduce outside your machine.
After following these steps, say "review my changes" in Claude Code to get a review against your team’s standards. Say "validate on the sidecar" to run checks in a CircleCI Cloud environment.
Chunk CLI vs Chunk by CircleCI. The chunk CLI is a local developer tool. It is separate from Chunk by CircleCI, the AI-powered CI/CD assistant in the CircleCI web app.
|
1. Installation
The chunk CLI supports macOS and Linux (arm64 and x86_64). Windows is not supported.
|
Install with Homebrew:
$ brew install CircleCI-Public/circleci/chunkVerify the installation:
$ chunk --version2. Authentication
After installing the chunk CLI, set credentials for each service you plan to use. Some commands require authentication, such as chunk sidecar and chunk task.
2.1 CircleCI
Required for chunk sidecar and chunk task commands. The chunk CLI uses your CircleCI credentials to create and manage cloud sidecar environments for running remote validations.
The recommended method uses browser-based OAuth. If you already have a CircleCI account:
$ chunk auth loginIf you are new to CircleCI:
$ chunk auth signupBoth commands open your browser for a secure login flow. If you prefer to use a personal API token instead:
$ chunk auth set circleciEnter your CircleCI personal API token when prompted. Generate a token from your User Settings in the CircleCI web app.
2.2 Anthropic
Required for chunk build-prompt. The chunk CLI uses your Anthropic API key to analyze GitHub PR comments with Claude and generate team-specific review prompts.
$ chunk auth set anthropicEnter your Anthropic API key when prompted. Generate an API key from the Anthropic console.
3. Initialize and validate a project
3.1 Initialize a project
Run chunk init in your project directory to configure the chunk CLI for that project:
$ chunk initchunk init performs these actions:
-
Detects your build, test, lint, and format commands.
-
Creates a
.chunk/config.jsonfile with the detected commands. -
Installs shell completions.
-
Generates hook configuration in
.claude/settings.jsonfor Claude Code. -
Installs AI agent skills into your coding agent.
The following flags are available for chunk init:
| Flag | Description |
|---|---|
|
Overwrite an existing |
|
Skip generating hook configuration in |
|
Skip installing the git pre-commit hook. |
|
Skip installing AI agent skills. |
|
Skip installing shell completions. |
|
Skip command detection. Creates the config file without auto-detecting commands. |
|
Set the project directory. Defaults to the current directory. |
3.2 Validate your project
After initialization, run chunk validate to run the detected commands. You can also run chunk build-prompt to mine your GitHub PR history for a team-specific review prompt.
For detailed information on using the chunk CLI, including generating review prompts and running validations, refer to How to Use the chunk CLI.
4. Install AI agent skills
chunk init installs skills automatically, but you can also run chunk skill install directly at any time to install or reinstall skills into your AI coding agent (Claude Code, Cursor, or VS Code Copilot):
$ chunk skill installTo see available skills and their current installation status:
$ chunk skill listThe following skills are available:
| Skill | Trigger phrases | Description |
|---|---|---|
|
"review my changes", "review PR #123" |
Reviews pull requests and diffs using your team’s review standards from |
|
"validate on the sidecar", "sidecar dev loop" |
Creates and manages Chunk sidecar environments for cloud validation. |
|
"find testing gaps", "mutation test" |
Identifies test coverage gaps through mutation testing. |
|
"debug CI", "why is CI failing" |
Debugs CircleCI pipeline failures and identifies flaky tests. |
Once installed, invoke skills directly in your AI coding agent. In Claude Code, type /chunk-review to review a diff or /chunk-sidecar to validate changes in a CircleCI Cloud environment.