Aspect Code logoAspect Code

Quick Start

Get Aspect Code running in under a minute.

Your first minute

This guide walks you through installing Aspect Code and generating your first AGENTS.md. Takes under a minute for most projects.

1. Install the CLI

npm install -g aspectcode

Or run without installing:


npx aspectcode

No account, no signup, no configuration needed.

2. Run in your project

cd your-project
aspectcode

Aspect Code will:

  • Scan your project for supported files (Python, TypeScript, JavaScript, Java, C#)
  • Analyze dependencies and architecture
  • Generate AGENTS.md at your project root
  • If an API key is set, run the evaluator and optimizer to improve the output
  • Enter watch mode, re-analyzing on file changes

    • For most repos, initial analysis takes a few seconds. LLM optimization adds 30–60 seconds.


    > Tip: Set an OPENAI_API_KEY or ANTHROPIC_API_KEY environment variable to enable LLM optimization automatically. Without a key, AGENTS.md is generated through static analysis alone.

    3. Review AGENTS.md

    Open the generated AGENTS.md in your editor. It contains:


  • Project overview — languages, structure, key directories
  • Architecture rules — hub modules, entry points, blast radius
  • Conventions — naming patterns, file organization, import rules
  • Files that change together — co-edit clusters
  • Do/don't rules — specific guardrails for AI assistants

    • The file is plain markdown — you can read, edit, and version-control it.

    4. Commit AGENTS.md

    We recommend committing AGENTS.md to your repo:


    git add AGENTS.md
git commit -m "Add AGENTS.md for AI coding assistants"

    This way your whole team (and their AI assistants) benefit from the same instructions.


    You can also add it to .gitignore if you prefer to keep it local-only.

    5. Start coding with context

    Open Copilot, Cursor, Claude Code, Windsurf, Cline, or any other AI assistant. They read AGENTS.md automatically and make better, convention-aware changes.


    Your assistant now knows:

  • Which modules are high-risk hubs
  • Where entry points are
  • What files change together
  • Your project's naming conventions and rules

    • Next steps

  • AGENTS.md — Understand what's in the generated file
  • LLM Optimization — How the optimization loop works
  • Watch Mode — Auto-update on file changes
  • Knowledge Base — Optional deeper analysis with --kb
  • Troubleshooting — Common issues and solutions
    • Installation