001 Overview

CLI tool · MIT-licensed

Infracontext.

Infrastructure context for humans and 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 · 14:03

$ 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"

✓ Context loaded: services, dependencies, 2 learnings · checking PHP-FPM first

02 Why

The problem

The details you learn about a server during an incident are easy to lose once you close the terminal.

`$ 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

03 Architecture

How it works

Three loosely coupled parts. Each is useful on its own.

architecture

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

The ic CLIThe hot path for humans: connect, get context, record learnings. It handles fuzzy names and tab completion from any directory.
YAML in .infracontext/One file per node, committed to git. You can edit the files by hand, then diff and review them like code.
Agent integrationsClaude Code skills for USE-method triage, plus an MCP server with typed tools. Agents read the same context and write learnings back.

04 Hot path

During an incident

Four commands cover the usual incident workflow.

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.

terminal

$ 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…" }]

05 Agents

For agents

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.

/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)

06 Capabilities

Features

Import nodes, map relationships, query monitoring systems, and validate stored data.

Source sync

Import from Proxmox VE, SSH config, Kubernetes, and SOS reports. Sync keeps any triage hints or learnings you added by hand.

Graph analysis

Single points of failure, impact analysis, cycles, orphans. Render the whole graph to HTML, SVG, or GraphML.

Monitoring queries

Prometheus, Loki, CheckMK, and Monit per node, straight from the CLI. --json on every query for scripting.

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.

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. If it finds broken data, it reports the issue instead of throwing a traceback.

07 Schema

Node YAML

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.

08 Tooling

The ic CLI

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, SOS data

ic import Proxmox, SSH config, SOS reports, Kubernetes

ic config env Environment registry for running ic from anywhere

ic mcp MCP server for agent integrations

ic doctor Validate schemas, config, and references

terminal

# 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

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

# Graph analysis

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

ic graph render --open | spof -A # fleet-wide

# Monitoring

# Environment and agents

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

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

09 Permissions

Access tiers

Control what the agent is allowed to do on each node.

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).

10 Setup

Quick start

Up and running in four steps.

STEP · 01 Install

terminal

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

STEP · 02 Initialize

terminal

cd my-project
ic init
ic describe project create prod

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

STEP · 03 Add nodes

terminal

# 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
ic describe source add mypve --type proxmox

STEP · 04 Use it yourself or with an agent

terminal

# 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.