Lousy Agents

Turn "lousy" AI outputs into production-grade code.

TL;DR

Lousy Agents is a set of published npm packages for agentic software development, with @lousy-agents/cli as the main entry point. Run npx @lousy-agents/cli init to create a new project with testing, linting, and GitHub Copilot configuration. Run npx @lousy-agents/cli copilot-setup in existing projects to generate a workflow that gives Copilot your environment context. Add @lousy-agents/mcp for MCP integrations and @lousy-agents/agent-shell for npm script telemetry when you need them.

---

Lousy Agents is an npm workspace monorepo that publishes focused packages for scaffolding, MCP integrations, and npm script telemetry. The CLI package gives you a production-ready development environment with testing, linting, and AI assistant configuration in one command.

Quick Start

# Scaffold a new webapp project (no install required)
npx @lousy-agents/cli init --kind webapp

# Or use interactive mode to choose your project type
npx @lousy-agents/cli init

# Generate GitHub Copilot setup workflow from your project configuration
npx @lousy-agents/cli copilot-setup

Table of Contents

• Start Here
• Who This Is For
• Why This Exists
• Features
• Installation
• Usage
• Contributing
• Roadmap
• Documentation
• Reference Examples

Start Here

If you're adopting Lousy Agents for the first time, use this order:

1. Scaffold a project with npx @lousy-agents/cli init
2. Add repository-specific setup with npx @lousy-agents/cli copilot-setup
3. Add deeper integrations only if you need them:
   • @lousy-agents/mcp for MCP clients like VS Code and hosted Copilot
   • @lousy-agents/agent-shell for npm script telemetry

Lousy Agents is an npm workspace monorepo. Most users only need one published package at a time:

Package	Install / Run	Use it when
@lousy-agents/cli	npx @lousy-agents/cli init	You want the scaffolding CLI for new or existing projects
@lousy-agents/mcp	npx -y -p @lousy-agents/mcp lousy-agents-mcp	You want Lousy Agents tools available through an MCP client
@lousy-agents/agent-shell	npm install -g @lousy-agents/agent-shell	You want an audit trail for npm script execution
@lousy-agents/lint	npm install @lousy-agents/lint	You want programmatic lint checks in your own tooling or web app

Who This Is For

• Software Engineers: Frustrated by inconsistent AI output and looking for proven patterns to improve results.
• Curious Beginners: Interested in AI-assisted coding but unsure how to set things up for success.
• Team Leads: Exploring how to standardize AI tooling across a team or project.
• Platform Engineers: Need to automate project scaffolding in scripts or CI/CD pipelines.

No prior experience with coding agents is required—just curiosity and a willingness to experiment.

Why This Exists

AI coding assistants work best when given clear constraints. Without structure, they guess—and often guess wrong. Lousy Agents provides the scaffolding they need to succeed:

• Instructions & Specs: Templates that clearly communicate your intent, so agents produce code that matches your vision.
• Feedback Loops: Pre-configured testing (Vitest) and linting (Biome) that let agents catch and fix their own mistakes immediately.
• Copilot Configuration: Settings and workflows that ground AI assistants in your specific engineering standards.

Features

CLI Commands

• **[init](docs/init.md