Aspect Research logoAspect Research

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 and log in

npm install -g aspectcode
aspectcode login

This installs the CLI globally and opens your browser to sign in with Google. A free account is required — your learned preferences sync to the cloud.

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 and scoped rules in .claude/rules/
  • If an API key is set, run the evaluator and optimizer to improve the output
  • Enter watch mode — monitoring for changes, learning your preferences

    • 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.

    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
  • Watch Mode — Assessments, learning, and dream cycles
  • Cloud Sync — How preferences sync across machines
  • LLM Optimization — How the probe-and-refine loop works
  • Troubleshooting — Common issues and solutions
    • Installation