🧠 LMAgent: The Universal AI Agent Runtime

██╗     ███╗   ███╗ █████╗  ██████╗ ███████╗███╗   ██╗████████╗
██║     ████╗ ████║██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝
██║     ██╔████╔██║███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   
██║     ██║╚██╔╝██║██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   
███████╗██║ ╚═╝ ██║██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   
╚══════╝╚╚═╝     ╚═╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   
                                                  by QuBit

"Separate the reasoning from the execution."
LMAgent is the foundational runtime that empowers your AI Agents with standardized Skills, Rules, and Workflows across any IDE (Cursor, Windsurf, VSCode, Zed, Qodo).

🚀 Quick Start Guide

The recommended way to use LMAgent is via npx, ensuring you always run the latest version without managing global packages.

⚡ Instant Run (No Install)

Run these commands directly in your terminal:

# 1. Initialize Project (Context)
#    Copies AGENTS.md & CLAUDE.md to your root.
npx lmagent init

# 2. Install/Update Skills (Tools)
#    Configures your IDE (.cursor, .vscode, .windsurf, etc.)
npx lmagent install

# 3. Optimize & Verify
#    Checks your environment health.
npx lmagent doctor

📦 Global Installation (Optional)

If you prefer having the lmagent command available globally:

# Install
npm install -g @qubiit/lmagent

# Run
lmagent init
lmagent install

🛠️ Developer Setup

If you are contributing to the framework:

git clone https://github.com/QuBit/lmagent.git
cd lmagent
npm install
npm link
lmagent doctor

🏛️ Architecture: Global Brain vs. Local Project

LMAgent uses a Hybrid Architecture to balance Centralized Updates with Project Portability.

The Problem it Solves

• Global Installs run the risk of breaking projects if they rely on your specific machine paths.
• Local Copies become stale and are hard to update across 10+ projects.

The Solution: "Symlink Bridge"

Why init and install are separate?

1. lmagent init: Creates the Portable Structure (files that must exist in the repo to work, like CLAUDE.md).
2. lmagent install: Builds the Bridge (Symlinks) specific to your machine's environment.

Best Practice: Commit CLAUDE.md and AGENTS.md. Do NOT commit the .cursor/skills folder (add it to .gitignore), as each developer should run lmagent install to link their own brain.

🛠️ Creating New Skills

Need a custom agent? Use the interactive generator:

# Verify structure of existing skills
npx lmagent validate

# Create a new skill interactively
npx lmagent create-skill

This will generate the standard directory structure and SKILL.md template for you.

🛠️ CLI Reference

LMAgent includes a powerful CLI to manage your AI context.

📂 Universal Project Structure

When you install LMAgent in your project, it creates a pristine environment:

/
├── .agents/                    # [UNIVERSAL BRAIN]
│   ├── rules/                  # Core Behavior (00-master, personality, etc.)
│   ├── skills/                 # Capabilities (backend-engineer, etc.)
│   ├── workflows/              # Procedures (SOPs)
│   ├── templates/              # Project scaffolds
│   ├── memory/                 # Documentation & Logs
│   ├── scripts/                # Utility scripts
│   └── config/                 # Global settings
│
├── AGENTS.md                   # [PILLAR 1] Capability Catalog (Root)
├── CLAUDE.md                   # [PILLAR 2] Context & Instructions (Root)
│
└── package.json

🧠 The Two Pillars

1. AGENTS.md: The catalog of all capabilities. It tells the agent what it can do and where to find instructions.
2. CLAUDE.md: The context file. It tells the agent how to behave and points to the Master Rule in .agents/rules/00-master.md.

🏛️ The 3-Pillar Architecture

LMAgent organizes AI capabilities into three distinct pillars, enforcing a clear separation of concerns.

graph TD
    A["🤖 AI Agent"] --> B("🛠️ Skills")
    A --> C("📜 Rules")
    A --> D("⚡ Workflows")
    
    B --> B1["{ide}/skills/"]
    B --> B2["Executable Tools & Scripts"]
    
    C --> C1["{ide}/rules/"]
    C --> C2["Behavioral Guardrails & Context"]
    
    D --> D1["{ide}/workflows/"]
    D --> D2["Standard Operating Procedures (SOPs)"]

1. 🛠️ Skills (Capabilities)

Executable units that allow the Agent to interact with the world.
Location: {ide}/skills/ or ~/.agents/skills/

2. 📜 Rules (Context & Guardrails)

Constraints and guidelines that shape Agent behavior.
Location: {ide}/rules/ or ~/.agents/rules/

3. ⚡ Workflows (SOPs)

Step-by-step guides for complex tasks.
Location: {ide}/workflows/ or ~/.agents/workflows/

💎 Features & IDE Support

🌍 Centralized "Brain" (~/.agents)

LMAgent creates a Single Source of Truth in your home directory.

• Update Once, Reflect Everywhere: Modify a rule in ~/.agents/rules/code-style.md, and every project using Symlinks updates instantly.
• Zero-Copy Efficiency: No more valid/duplicate .md files cluttering every repo.

🧩 Multi-IDE Support

🤝 Contributing

We welcome contributions to expand the Universal Agent Brain. Check out CONTRIBUTING.md to add new Skills, Rules, or IDE support.

Built with ❤️ by QuBit