Lopi

A self-evolving, agent-first CLI mold for managing, debugging, and automating your system.

Lopi (pronounced "LOH-pee") — Icelandic for unspun wool ready to be shaped.

   ┌─ agent ───────────────────────┐                    ┌─ your system ──────────────────┐
   │                               │                    │                                │
   │  /lopi                        │ ───── operates ───▶│  lopi CLI                      │
   │   debug · operate · observe   │                    │    status · troubleshoot       │
   │                               │                    │    env · howto                 │
   └───────────────────────────────┘                    │  ────────────────────────────  │
                                                        │    intel — knowledge base      │
                                                        │              ▲                 │
                                                        │              │ /lopi-learn     │
                                                        │      (incident → lesson)       │
                                                        └────────────────────────────────┘

The agent acts through one structured CLI; the CLI carries the system knowledge (intel) it needs to act well; when a debug session was costly, the operator runs /lopi-learn to capture it as intel, so the system gets smarter the more it's used.

Lopi is a seed, not a finished tool. The installer drops a mold into any repo where you and your agent regularly debug, operate, or observe a system; your agent then customizes it for that system. From there it keeps growing — you extend the CLI with new commands, intel accumulates from gotchas and incidents, and skills get tuned over time.

Installation

git clone git@github.com:gavraz/lopi.git /tmp/lopi
/tmp/lopi/install.sh /path/to/your/repo

Install Lopi wherever a developer or operator would benefit from a structured, agent-friendly interface to their system — there's no single canonical repo. Multiple repos can each host their own Lopi with independent intel and customizations.

After install, paste the printed prompt into your agent — it walks docs/lopi-first-time.md to customize Lopi for that repo. From there your agent can run /lopi or invoke any lopi command directly.

Terminology

• instance — one unit of your system (a server, VM, container host, device)
• cluster — a collection of instances that operate together
• intel — a structured YAML entry in intel/ describing a known issue + workaround

What you get out of the box

• lopi — a Rust CLI with:
  • JSON envelope on every command — agent-friendly output everywhere
  • Schema-validated configuration — type checks, fuzzy typo suggestions, and missing-var detection (ships with .env parsing; pluggable for other formats)
  • Intel knowledge base (lopi intel {list,show,search,validate,encounter,resolve,reopen}) — schema-validated, with structured mutations so the agent never hand-edits YAML
  • Templated command reference (lopi howto)
  • Runtime modules (status, troubleshoot, clean, perf, collect, storage) — stubs you customize during onboarding
• Two agent skills (skills/):
  • /lopi — autonomous agent mode (read-only / confirm / auto)
  • /lopi-learn — operator-triggered capture of lessons from incidents or debugging sessions into intel YAMLs
• scripts/resolve.sh — logical-name → network-address mapping, customized during onboarding
• docs/lopi-first-time.md — the onboarding doc that walks your agent through customizing the mold for your repo

Who this is for

• One CLI, two users — humans and agents share the same structured interface
• Durable system knowledge — incidents and gotchas become intel, not Slack threads or tribal know-how
• Agent skills that fit your system — your agent operates, debugs, observes through lopi

Layout

tools/lopi/
├── src/                   Rust source
├── scripts/               resolve script
├── skills/                agent skills (SKILL.md format)
├── docs/                  onboarding, commands, scripts, remote deploy
├── intel/                 knowledge base (yaml per issue)
├── lopi.toml             [meta] + [[sources]] + [vars.*] + [howto.*]
├── lopido                SSH wrapper for running lopi remotely
├── AGENTS.md / CLAUDE.md  agent context
├── LICENSE                Apache 2.0
├── NOTICE                 attribution (must be preserved on redistribution)
└── README.md              this file

See docs/COMMANDS.md for the full command reference, and docs/SCRIPTS.md for script contracts.

License

Lopi is licensed under the Apache License 2.0. See NOTICE for attribution requirements.

If you use Lopi in your work, I'd appreciate a star, a link back, or a mention in your repo's README — none required, all appreciated.