Skip to content

Getting Started with Plan-Linter

This guide will help you get up and running with Plan-Linter.

Installation

Using pip

pip install plan-lint

From source

git clone https://github.com/cirbuk/plan-lint.git
cd plan-lint
pip install -e .

Basic Usage

The simplest way to use Plan-Linter is to run it on a JSON plan file:

plan-lint path/to/plan.json

This will validate the plan against the default schema and report any issues.

Using a Policy File

For more control, create a policy YAML file:

# policy.yaml
allow_tools:
  - sql.query_ro
  - priceAPI.calculate
bounds:
  priceAPI.calculate.discount_pct: [-40, 0]
deny_tokens_regex:
  - "AWS_SECRET"
  - "API_KEY"
max_steps: 50
risk_weights:
  tool_write: 0.4
  raw_secret: 0.5
fail_risk_threshold: 0.8

Then run Plan-Linter with the policy:

plan-lint path/to/plan.json --policy policy.yaml

Output Formats

Plan-Linter can output in different formats:

CLI (default)

plan-lint path/to/plan.json

This shows a rich formatted report in the terminal.

JSON

plan-lint path/to/plan.json --format json

This outputs a machine-readable JSON report.

Saving Output

To save the output to a file:

plan-lint path/to/plan.json --output results.txt

Or for JSON:

plan-lint path/to/plan.json --format json --output results.json

CI Integration

Plan-Linter can be integrated into CI pipelines. Add this to your GitHub workflow:

- name: Lint agent plan
  run: |
    plan-lint path/to/plan.json --policy policy.yaml

The command will return a non-zero exit code if the plan fails validation, which will fail the CI step.

Next Steps