agenv-cli

agenv

Generate portable AI workspace configs for any web development project — one manifest for Copilot, Claude, Codex, MCP, Cursor, and Windsurf.

Define one canonical ai-workspace.json manifest, then generate tool-specific configuration files for all six targets from a single source of truth.

Quick Start

# Install once:
npm install -g agenv-cli

# Then in any web project directory:
agenv init --yes
agenv generate

That's it. agenv inspects your repo, creates ai-workspace.json, and generates tool-specific files for your enabled targets.

What It Does

• Inspects your repo — detects framework, package manager, existing AI config files
• Creates ai-workspace.json — a single manifest describing your AI workspace
• Plans which files to generate based on your targets and setup mode
• Generates shared docs, prompts, and tool-specific files (AGENTS.md, copilot-instructions, .claude/, .mcp.json)

Supports seven project types: dashboard, web-app, api-service, full-stack, library, cli-tool, and mobile.

Install

npm install -g agenv-cli
agenv --help

Commands

Command	Description
agenv init	Create ai-workspace.json from repo inspection + interactive prompts
agenv init --yes	Non-interactive mode with recommended defaults
agenv generate	Generate all planned files from the manifest
agenv generate --dry-run	Preview what would be generated without writing
agenv generate --force	Overwrite files modified outside agenv
agenv diff	Show what generate would change
agenv doctor	Validate manifest and repo compatibility
agenv templates list	List available starter templates

How It Works

agenv init          →  ai-workspace.json (your manifest)
agenv generate      →  AGENTS.md, .github/copilot-instructions.md,
                       .claude/*, .mcp.json, docs/ai-prompts/*
agenv diff          →  preview changes before writing
agenv doctor        →  validate everything is consistent

Generated files include a header comment so agenv knows which files it manages. Files you edit by hand are protected from overwrite (unless you use --force). Backups are created in .agenv-backups/ before any overwrite.

Supported Targets

Target	Output
codex	AGENTS.md
copilot	.github/copilot-instructions.md
claude	.claude/README.md, .claude/skills/*.md, .claude/agents/*.md, .claude/settings.local.json
mcp	.mcp.json, .mcp.local.json
cursor	.cursor/rules/context.mdc, .cursor/rules/coding-style.mdc, .cursor/rules/framework.mdc, .cursor/rules/code-review.mdc
windsurf	.windsurf/rules/context.md, .windsurf/rules/coding-style.md, .windsurf/rules/framework.md, .windsurf/rules/code-review.md

Project Types

Type	Description
dashboard	Internal data/admin dashboard
web-app	Consumer-facing web application
api-service	Backend API service
full-stack	Combined frontend + backend (e.g. Next.js full-stack)
library	Reusable npm package or component library
cli-tool	Node.js command-line tool
mobile	React Native / Expo mobile app

MCP Presets

Built-in presets with trust annotations: filesystem, github, fetch, memory, postgres, sqlite, puppeteer, sequential-thinking, notion, stripe, atlassian.

Select presets during agenv init or add them to generated.mcpPresets in your manifest. Non-safe presets include _trustLevel and _trustNote annotations in .mcp.json.

Documentation

Doc	Purpose
Getting Started	Contributor onboarding
Product Requirements	Product goals and scope
Technical Requirements	Architecture and technical design
CLI Spec	Command contract and flag reference
Manifest Spec	Manifest schema and field definitions
Output Map	Which files are generated and when
Adapter Contract	How adapters work

Contributing

See CONTRIBUTING.md for setup, development commands, and PR guidelines.

Security

See SECURITY.md for the vulnerability reporting policy.

npm install
npm run build
npm test
npm run typecheck

License

MIT