CLI tool · MIT licensed · open source

infracontext

Infrastructure context, for humans and their agents.

Keep server details, including services, quirks, dependencies, and past incidents, as YAML in git. ic briefs you before it connects and gives AI agents the same information through typed tools.

View on GitHub Quick start

incident — ic

$ ic ssh web

│ vm:web-01 · Production Web Server · tier 3 (privileged)

│ services: nginx, php8.2-fpm · 3 systems depend on this node

│ 2026-06-12: deploys spike CPU for ~5 min · cold OPcache, check pool first

web-01:~$ sudo systemctl reload php8.2-fpm

web-01:~$ exit

$ ic learn web "raised OPcache memory limit, deploy spikes gone"

✓ Learning recorded to vm:web-01

# next incident, in Claude Code:

> /ic-triage web-01 "high CPU"

briefed services, dependencies, 2 learnings · checking PHP-FPM first

Works with Sources, query targets, and agent integrations

1: memory

You've debugged this box before.

The details you learn about a server during an incident are easy to lose once you close the terminal. Infracontext keeps them next to the node they belong to.

`$ ssh web-01`

connects you blind

You reconstruct the box from memory: which services, what broke last time
The wiki page was last touched two migrations ago
Every incident starts with the same ten minutes of orientation
Agents check random logs and rediscover your setup every session
Findings end up in a closed ticket nobody reads again

`$ ic ssh web-01`

briefs you first, then connects

Services, dependencies, and the last relevant finding, before your prompt appears
Agents get the same context as typed MCP tools and Claude Code skills
ic learn records what you found in one line
Knowledge stays in git next to your code, where you can diff and review changes
Fuzzy names and tab completion work from any directory

2: how

Three parts, each useful alone.

Everything meets in the YAML: the CLI writes it, agents read it, git versions it.

architecture

  you: ic ssh · ctx · status · learn     agents: skills · MCP tools
                 |                                  |
                 +----------------+-----------------+
                                  |
                           +-------------+
                           |   ic CLI    |
                           +-------------+
                          /       |       \
       reads / writes    /       SSH       \    HTTP · SNMP
                        /         |          \
        +----------------+  +-----------+  +--------------------+
        | .infracontext/ |  |   your    |  | Prometheus · Loki  |
        | YAML in git:   |  |  servers  |  | CheckMK · Monit    |
        | nodes, edges,  |  +-----------+  | SNMP · Redfish     |
        | learnings      |                 +--------------------+
        +----------------+

part 1

The `ic` CLI

The hot path for humans: connect, get context, record learnings. Fuzzy names and tab completion from any directory.

part 2

`.infracontext/` in git

One YAML file per node, committed next to your code. Edit the files by hand, then diff and review them like code.

part 3

Agent integrations

Claude Code skills for USE-method triage, plus an MCP server with typed tools. Agents read the same context and write learnings back.

All three meet in the same YAML files, so humans and agents cannot drift apart.

3: incident

Four commands cover an incident.

Resolve a fuzzy name, get briefed, check monitoring, record what you found.

ic ssh <query> Resolves a fuzzy name, briefs you on stderr, then execs ssh. Pipes stay clean.

ic ctx <query> Everything known about the node: services, dependencies, learnings. --json for scripts.

ic status <query> All monitoring sources at once, queried concurrently.

ic learn <query> "…" One line to record what you found. Opens $EDITOR when called without a finding.

Bare names resolve fuzzily: web finds vm:web-01. Node IDs support tab completion, and the environment registry lets you run every command from any directory.

status — ic

$ ic status web

vm:web-01 · Production Web Server

Prometheus cpu 91% · mem 64% · disk 41%

Loki 14 error lines in the last hour

CheckMK 2 services WARN

Monit php8.2-fpm running · nginx running

$ ic ctx web --json | jq .learnings

[{ "date": "2026-06-12", "finding": "deploys spike CPU…" }]

4: agents

Agents get the same briefing you do.

Typed tools give agents the same infrastructure context before they start triage.

ic mcp serve MCP server with typed tools: find_node, get_context, query_status, add_learning.

/ic-triage USE-method triage (Utilization, Saturation, Errors) with per-node context and hints.

/ic-collect Discovers a server over SSH and writes its node YAML for you. Bare metal gets a hardware probe: dmidecode, LLDP cabling, the BMC.

/ic-trace Follows a request across nodes using the relationship graph.

Agents record findings on the node with source: agent. Access tiers set the permitted operations for each machine, from local context to full remediation.

claude-code

$ claude mcp add infracontext -- ic mcp serve

> /ic-triage web-01 "high CPU"

✓ Context: services, dependencies, 2 learnings

✓ SSH validated · tier 3 (privileged)

✓ USE checks: CPU saturated · memory OK · disk OK

Finding: PHP-FPM pool at 94% · matches learning from 2026-06-12

✓ Learning recorded (source: agent)

The four MCP tools
Tool	CLI twin	What it does
`find_node`	ic describe node find	Resolves a fuzzy query to a node. Start here.
`get_context`	ic ctx	Everything known about the node: services, dependencies, learnings.
`query_status`	ic status	All monitoring sources for the node at once.
`add_learning`	ic learn	Records a finding on the node, marked `source: agent`.

The Claude Code skills ship in the repository and use the same context; no separate configuration beyond claude mcp add.

5: features

Beyond the hot path.

Import nodes, map relationships down to racks and power feeds, query monitoring systems, and validate stored data.

Source sync

Import from Proxmox VE, NetBox, Kubernetes, SSH config, and SOS reports; sync switches and BMCs over SNMP and Redfish, and the full host inventory of a CheckMK site. Sync keeps any triage hints or learnings you added by hand.

Physical layer

Model sites, racks, PDUs, and UPSes with located_in, powered_by, and manages relationships. Hardware attributes fill from device-type libraries, NetBox, or a dmidecode probe during /ic-collect.

Graph analysis

Single points of failure, impact analysis, cycles, orphans. The analyses traverse power and placement chains, so a failing PDU shows every affected service.

Renders, including 3D

ic graph render -f 3d opens a navigable outage explorer with deep links to nodes. Mermaid export renders on GitHub, GitLab, and Obsidian; the default HTML artifact works offline, and SVG and GraphML still ship.

Monitoring queries

Prometheus, Loki, CheckMK, and Monit per node, straight from the CLI. ic query snmp walks a switch live, ic query redfish reads BMC health and power draw. --json on every query for scripting.

Request-path chains

Describe lb → app → db as one ordered entry in chains.yaml; graph, doctor, and render expand it to pairwise edges. Older ic versions in federated repos simply ignore the file.

Federation

Compose repositories: a shared fleet repo for hypervisors, per-app repos on top. Cross-repo references like @fleet:physical_host:pve-01, fleet-wide SPOF and impact analysis.

Access tiers

Choose one of five tiers, from local_only (no SSH) to remediate (may make changes), per node or globally. Agents inherit the setting.

Living documentation

Humans and agents record findings as learnings on the node. Those learnings stay in git with the node and are available during the next incident.

Data hygiene

Every sync writes a run record, and doctor flags nodes a source stopped reporting. ic describe node consolidate merges duplicates and rewrites every reference. Failed or partial syncs never rewrite node files.

Local overrides

Machine-specific settings (SSH aliases, source paths) live in .infracontext.local.yaml, which git ignores so those values stay out of the shared repo.

Doctor

ic doctor validates schemas, configuration, cross-repo references, and consistency between node IDs and file paths, plus content lints: constraint re-validation, duplicate SSH aliases and IPs, blank learnings. Broken data gets a report instead of a traceback.

6: schema

A node is one YAML file.

A node needs only an ID and SSH alias before you can use it for triage.

.infracontext/projects/prod/nodes/vm/web-01.yaml

version: "2.0"
id: "vm:web-01"
slug: web-01
type: vm
name: "Production Web Server"
ssh_alias: "acme-web01"

triage:
  services: [nginx, php8.2-fpm]
  context: |
    Peak traffic 5-7pm weekdays.
    If CPU high, check PHP-FPM pool first.

observability:
  - type: prometheus
    instance: web-prod:9100
  - type: loki
    selector: '{service_name="web-prod"}'

learnings:
  - date: "2026-06-12"
    context: "high CPU after deploy"
    finding: "Cold OPcache spikes CPU ~5 min after each deploy"
    source: agent

Keep triage hints minimal. Document setup details that would be costly, slow, or unsafe to rediscover from standard logs and commands.

7: cli

Everything is an ic subcommand.

The CLI, built with Python and Typer, lets you document infrastructure and use that context while working on it.

ic ssh · ctx · status · learn The incident hot path, with fuzzy node resolution everywhere

ic describe Nodes, projects, relationships, and sync sources

ic graph SPOFs, impact, cycles, orphans, rendering

ic query Prometheus, Loki, CheckMK, Monit, SNMP, Redfish, SOS data

ic import · describe source One-shot: SSH config, SOS, Kubernetes, device types. Syncing: Proxmox, NetBox, CheckMK, SNMP, Redfish

ic config env Environment registry for running ic from anywhere

ic mcp MCP server for agent integrations

ic doctor Validate schemas, config, and references

ic — overview

# Incident hot path (fuzzy queries)

ic ssh <query> [cmd…] | ctx | status | learn "finding"

# Nodes

ic describe node add <ssh-alias>

ic describe node list | show | edit | find <query> [--json]

# Relationships and sources

ic describe relationship list | create | wizard | chain add

ic import ssh-config | sos <path> | kubectl | devicetype

# Graph analysis

ic graph analyze <id> --upstream | impact | spof | cycles

ic graph render --open | -f 3d | -f mermaid

ic graph spof -A # fleet-wide, across the power chain

# Monitoring

ic query status | prometheus | loki | checkmk | monit [--json]

ic query snmp | redfish | sos <id>

# Environment and agents

ic config env add <name> <path> --default

ic mcp serve · ic doctor [--json] · ic --install-completion

8: tiers

You decide how far an agent goes.

Choose one of five access tiers per node or globally. Agents inherit the setting.

tier 0

`local_only`

No SSH. Only local context and monitoring queries.

tier 1

`collector`

Run a pre-deployed collector script only.

tier 2

`unprivileged`

Read-only SSH, no sudo.

tier 3

`privileged`

SSH with sudo for diagnostics.

tier 4

`remediate`

Can make changes (restart services, edit config).

9: setup

Four steps to the first briefing.

Install the CLI, initialize a repo, add nodes, then use the context yourself or hand it to an agent.

install.sh

git clone https://github.com/sysinit-at/infracontext.git
# [mcp] bundles the MCP server used in step 4
uv tool install './infracontext[mcp]'

# tab completion for node IDs and projects
ic --install-completion

init.sh

cd my-project
ic init
ic describe project create prod

# register once: ic then works from any directory
ic config env add prod . --default

add-nodes.sh

# one step from an SSH alias
ic describe node add web-prod

# auto-discover via SSH (in Claude Code)
/ic-collect web-prod

# bulk import
ic import ssh-config
ic import kubectl
ic import sos /path/to/sosreport

# syncing sources: proxmox, netbox, checkmk, snmp, redfish
ic describe source add mypve --type proxmox
ic describe source add dc1 --type netbox

use-it.sh

# you
ic ssh web
ic learn web "what you found"

# your agents (skills ship in the repo)
claude mcp add infracontext -- ic mcp serve
/ic-triage web-01 "high CPU"
/ic-trace proxy-01 "requests to /api returning 502"

Get started.

Infracontext is open source under the MIT license. Clone the repo, run ic init, and use ic learn to save findings during the next incident.

View on GitHub Documentation

We use Infracontext to manage customer fleets. Email hello@infracontext.net if you need help with yours.