IRIS

IRIS is a network operations agent built as a Claude Code skill. The idea is simple: a network engineer still owns every decision, but a lot of the work around those decisions (pulling device state, checking it against source of truth, running pre-condition checks, drafting the change, verifying it after, writing it up in the ticket) is the kind of thing an agent can do well if you give it the right discipline.

That discipline is what's in this repo.

What's in the repo

.
├── SKILL.md                    the workflow IRIS follows on every ticket
├── CLAUDE.md                   operating rules for the agent
├── .claude/commands/iris.md    /iris slash command entry point
├── .mcp.json.example           template for the tools IRIS connects to
├── environment/
│   ├── discovery/              where IRIS learns your network
│   │   ├── docs/               drop network docs, diagrams, IaC here
│   │   └── scripts/            drop executable discovery scripts here
│   └── artifacts.md.template   what IRIS writes after first-run discovery
├── automation/
│   ├── scripts/                your operational automation lives here
│   └── artifacts.md.template   IRIS catalogs each artifact it learns
└── references/
    ├── learn-environment.md    how IRIS does first-run discovery
    ├── learn-automation.md     how IRIS learns a new automation artifact
    └── pre-change-checks.md    pre-condition checks by change type

The pieces

SKILL.md is the heart of it. It's the workflow IRIS runs on every ticket: discover, verify, propose, confirm, execute, verify, document. The discipline doesn't change whether you're touching Catalyst CLI, the Meraki dashboard, or a Terraform plan.

CLAUDE.md is the operating contract. Don't push without explicit approval. Stop if something looks wrong. Close the ticket with enough detail that the next engineer can reconstruct what happened and why.

environment/ is where IRIS learns what your network looks like. On first run it pulls from any MCPs you've connected, reads whatever docs you've dropped into discovery/docs/, and runs any scripts in discovery/scripts/. The result lands in environment/artifacts.md, which IRIS treats as its environment context going forward.

automation/ is your toolbelt. Drop scripts or playbooks into automation/scripts/ and IRIS will read them, install missing dependencies, and write a summary into automation/artifacts.md. Each artifact gets a safety classification. Read-only artifacts can run during investigation without approval. State-changing artifacts always require explicit approval before they run, the same as any other change.

references/ is the deeper reading. The pre-change checks file is the one IRIS pulls from most — it has common pre-condition patterns by change type (BGP changes, ACL edits, VLAN moves, etc.).

Getting started

1. Clone

git clone <your-fork-url> ~/iris
cd ~/iris

2. Connect your tools

Copy the MCP template and fill in your own endpoints and credentials:

cp .mcp.json.example .mcp.json

Edit .mcp.json with the URLs, usernames, tokens, and passwords for whatever you want IRIS to reach. The template ships with entries for ServiceNow, NetBox, and CML. Keep what applies, delete what doesn't, add what you need.

.mcp.json is gitignored. It does not get pushed.