This repository contains the code for OpenHands, an automated AI software engineer. It has a Python backend (in the openhands directory) and React frontend (in the frontend directory).

General Setup:

To set up the entire repo, including frontend and backend, run make build. You don't need to do this unless the user asks you to, or if you're trying to run the entire application.

Running OpenHands with OpenHands:

To run the full application to debug issues:

export INSTALL_DOCKER=0
export RUNTIME=local
make build && make run FRONTEND_PORT=12000 FRONTEND_HOST=0.0.0.0 BACKEND_HOST=0.0.0.0 &> /tmp/openhands-log.txt &

Local run troubleshooting notes:

• If the backend fails with nc: command not found, install netcat-openbsd.
• If local runtime startup fails with duplicate session: test-session, clear the stale tmux session on the default socket: tmux -S /tmp/tmux-$(id -u)/default kill-session -t test-session.
• Local runtime browser startup expects Playwright browsers under ~/.cache/playwright; if needed run PLAYWRIGHT_BROWSERS_PATH=$HOME/.cache/playwright poetry run playwright install chromium.
• In this sandbox environment, an inherited SESSION_API_KEY can make /api/v1/settings return 401 in the browser. Unset it before make run when you want to use the local web UI directly.
• In this sandbox, frontend's npm run dev:mock / dev:mock:saas can start but still be awkward to browse through the work-host proxy. For PR QA screenshots, a reliable fallback is to npm run build with the desired VITE_MOCK_* env, then serve build/ with a tiny custom HTTP server that returns the minimal mock JSON endpoints needed by the settings page.

IMPORTANT: Before making any changes to the codebase, ALWAYS run make install-pre-commit-hooks to ensure pre-commit hooks are properly installed.

Before pushing any changes, you MUST ensure that any lint errors or simple test errors have been fixed.

• If you've made changes to the backend, you should run pre-commit run --config ./dev_config/python/.pre-commit-config.yaml (this will run on staged files).
• If you've made changes to the frontend, you should run cd frontend && npm run lint:fix && npm run build ; cd ..
• If you've made changes to the VSCode extension, you should run cd openhands/app_server/integrations/vscode && npm run lint:fix && npm run compile ; cd ../../..

The pre-commit hooks MUST pass successfully before pushing any changes to the repository. This is a mandatory requirement to maintain code quality and consistency.

If either command fails, it may have automatically fixed some issues. You should fix any issues that weren't automatically fixed, then re-run the command to ensure it passes. Common issues include:

• Mypy type errors
• Ruff formatting issues
• Trailing whitespace
• Missing newlines at end of files

Git Best Practices

• Prefer specific git add <filename> instead of git add . to avoid accidentally staging unintended files
• Be especially careful with git reset --hard after staging files, as it will remove accidentally staged files
• When remote has new changes, use git fetch upstream && git rebase upstream/<branch> on the same branch

GitHub Actions

• Pin external third-party actions to a full 40-character commit SHA, with the version tag in a trailing comment (e.g. uses: owner/repo@<sha> # v1.2.3). Do not use mutable tags (@v1) or branches for third-party actions.
• GitHub-authored (actions/*, github/*) and first-party (OpenHands/*) actions are currently exempt.
• Dependabot's github-actions ecosystem bumps the pinned SHA and the trailing comment under the configured cooldown, so pinning does not block security or version updates.

Lockfile Regeneration (Preserve Original Tool Versions)

When regenerating lockfiles (poetry.lock, uv.lock, etc.), you MUST use the same tool version that originally generated the lockfile to avoid unnecessary diff noise. Each lockfile contains a version header indicating which tool version was used.

Poetry (poetry.lock)

1. Extract the version from the lockfile header:

   POETRY_VERSION=$(grep -m1 "^# This file is automatically @generated by Poetry" poetry.lock | sed 's/.*Poetry \([0-9.]*\).*/\1/')
   

2. If a version is found, install that specific version:

   pipx install poetry==$POETRY_VERSION --force
   

3. Then regenerate the lockfile:

   poetry lock --no-update
   

uv (uv.lock)

1. Extract the version from the lockfile header:

   UV_VERSION=$(grep -m1 "^# This file was autogenerated by uv" uv.lock | sed 's/.*uv version \([0-9.]*\).*/\1/')
   

2. If a version is found, install that specific version:

   pipx install uv==$UV_VERSION --force
   

3. Then regenerate the lockfile:

   uv lock
   

This ensures that lockfile updates only contain actual dependency changes, not tool version migration artifacts.

PR-Specific Artifacts (.pr/ directory)

When working on a PR that requires design documents, scripts meant for development-only, or other temporary artifacts that should NOT be merged to main, store them in a .pr/ directory at the repository root.

Usage

.pr/
├── design.md       # Design decisions and architecture notes
├── analysis.md     # Investigation or debugging notes
├── logs/           # Test output or CI logs for reviewer reference
└── notes.md        # Any other PR-specific content

How It Works

1. Notification: When .pr/ exists, a comment is posted to the PR conversation alerting reviewers
2. Auto-cleanup: When the PR is approved, the .pr/ directory is automatically removed via .github/workflows/pr-artifacts.yml
3. Fork PRs: Auto-cleanup cannot push to forks, so manual removal is required before merging

Important Notes

• Do NOT put anything in .pr/ that needs to be preserved after merge
• The .pr/ check passes (green ✅) during development — it only posts a notification, not a blocking error
• For fork PRs: You must manually remove .pr/ before the PR can be merged

When to Use

• Complex refactoring that benefits from written design rationale
• Debugging sessions where you want to document your investigation
• E2E test results or logs that demonstrate a cross-repo feature works
• Feature implementations that need temporary planning docs
• Any analysis that helps reviewers understand the PR but isn't needed long-term

Repository Structure

Backend:

• Located in the openhands directory
• The current V1 application server lives in openhands/app_server/. make start-backend still launches openhands.server.listen:app, which includes the V1 routes by default unless ENABLE_V1=0.
• For V1 web-app docs, LLM setup should point users to the Settings UI.
• Testing:
  • All tests are in tests/unit/test_*.py
  • To test new code, run poetry run pytest tests/unit/test_xxx.py where xxx is the appropriate file for the current functionality
  • Write all tests with pytest

Frontend:

• Located in the frontend directory
• Prerequisites: A recent version of NodeJS / NPM
• Setup: Run npm install in the frontend directory
• Testing:
  • Run tests: npm run test
  • To run specific tests: npm run test -- -t "TestName"
  • Our test framework is vitest
• Building:
  • Build for production: npm run build
• Environment Variables:
  • Set in frontend/.env or as environment variables
  • Available variables: VITE_BACKEND_HOST, VITE_USE_TLS, VITE_INSECURE_SKIP_VERIFY, VITE_FRONTEND_PORT
• Internationalization:
  • Generate i18n declaration file: npm run make-i18n
• Data Fetching & Cache Management:
  • We use TanStack Query (fka React Query) for data fetching and cache management
  • Data Access Layer: API client methods are located in frontend/src/api and should never be called directly from UI components - they must always be wrapped with TanStack Query
  • Custom hooks are located in frontend/src/hooks/query/ and frontend/src/hooks/mutation/
  • Query hooks should follow the pattern use[Resource] (e.g., useConversationSkills)
  • Mutation hooks should follow the pattern use[Action] (e.g., useDeleteConversation)
  • Architecture rule: UI components → TanStack Query hooks → Data Access Layer (frontend/src/api) → API endpoints
  • For SaaS organization management screens, prefer deriving the selected organization from useOrganizations() plus the selected org ID store instead of adding a dedicated single-org fetch when only list-level fields (for example name) are needed.

VSCode Extension:

• Located in the openhands/app_server/integrations/vscode directory
• Setup: Run npm install in the extension directory
• Linting:
  • Run linting with fixes: npm run lint:fix
  • Check only: npm run lint
  • Type checking: npm run typecheck
• Building:
  • Compile TypeScript: npm run compile
  • Package extension: npm run package-vsix
• Testing:
  • Run tests: npm run test
• Development Best Practices:
  • Use vscode.window.createOutputChannel() for debug logging instead of showErrorMessage() popups
  • Pre-commit process runs both frontend and backend checks when committing extension changes

Enterprise Directory

The enterprise/ directory contains additional functionality that extends the open-source OpenHands codebase. This includes:

• Authentication and user management (Keycloak integration)
• Database migrations (Alembic)
• Integration services (GitHub, GitLab, Jira, Linear, Slack)
• Billing and subscription management (Stripe)
• Telemetry and analytics (PostHog, custom metrics framework)

Enterprise Development Setup

Prerequisites:

• Python 3.12
• Poetry (for dependency management)
• Node.js 22.x (for frontend)
• Docker (optional)

Setup Steps:

1. First, build the main OpenHands project: make build
2. Then install enterprise dependencies: cd enterprise && poetry install --with dev,test (This can take a very long time. Be patient.)
3. Set up enterprise pre-commit hooks: poetry run pre-commit install --config ./dev_config/python/.pre-commit-config.yaml

Running Enterprise Tests:

# Enterprise unit tests (full suite)
PYTHONPATH=".:$PYTHONPATH" poetry run --project=enterprise pytest --forked -n auto -s -p no:ddtrace -p no:ddtrace.pytest_bdd -p no:ddtrace.pytest_benchmark ./enterprise/tests/unit --cov=enterprise --cov-branch

# Test specific modules (faster for development)
cd enterprise
PYTHONPATH=".:$PYTHONPATH" poetry run pytest tests/unit/telemetry/ --confcutdir=tests/unit/telemetry

# Enterprise linting (IMPORTANT: use --show-diff-on-failure to match GitHub CI)
poetry run pre-commit run --all-files --show-diff-on-failure --config ./dev_config/python/.pre-commit-config.yaml

Running Enterprise Server:

cd enterprise
make start-backend  # Development mode with hot reload
# or
make run  # Full application (backend + frontend)

Key Configuration Files:

• enterprise/pyproject.toml - Enterprise-specific dependencies
• enterprise/Makefile - Enterprise build and run commands
• enterprise/dev_config/python/ - Linting and type checking configuration
• enterprise/migrations/ - Database migration files

Database Migrations: Enterprise uses Alembic for database migrations. When making schema changes:

1. Create migration files in enterprise/migrations/versions/
2. Test migrations thoroughly
3. The CI will check for migration conflicts on PRs

Integration Development: The enterprise codebase includes integrations for:

• GitHub - PR management, webhooks, app installations
• GitLab - Similar to GitHub but for GitLab instances
• Jira - Issue tracking and project management
• Linear - Modern issue tracking
• Slack - Team communication and notifications

Each integration follows a consistent pattern with service classes, storage models, and API endpoints.

Important Notes:

• Enterprise code is licensed under Polyform Free Trial License (30-day limit)
• The enterprise server extends the OpenHands server through dynamic imports
• Database changes require careful migration planning in enterprise/migrations/
• Always test changes in both OpenHands and enterprise contexts
• Use the enterprise-specific Makefile commands for development
• When the openhands-ai package (root project) version has been updated, run poetry lock in the enterprise/ folder to update the version in the enterprise poetry lockfile.

Enterprise Testing Best Practices:

Database Testing:

• Use SQLite in-memory databases (sqlite:///:memory:) for unit tests instead of real PostgreSQL
• Create module-specific conftest.py files with database fixtures
• Mock external database connections in unit tests to avoid dependency on running services
• Use real database connections only for integration tests

Import Patterns:

• Use relative imports without enterprise. prefix in enterprise code
• Example: from storage.database import a_session_maker not from enterprise.storage.database import a_session_maker
• This ensures code works in both OpenHands and enterprise contexts

Test Structure:

• Place tests in enterprise/tests/unit/ following the same structure as the source code
• Use --confcutdir=tests/unit/[module] when testing specific modules
• Create comprehensive fixtures for complex objects (databases, external services)
• Write platform-agnostic tests (avoid hardcoded OS-specific assertions)

Mocking Strategy:

• Use AsyncMock for async operations and MagicMock for complex objects
• Mock all external dependencies (databases, APIs, file systems) in unit tests
• Use patch with correct import paths (e.g., telemetry.registry.logger not enterprise.telemetry.registry.logger)
• Test both success and failure scenarios with proper error handling

Coverage Goals:

• Aim for 90%+ test coverage on new enterprise modules
• Focus on critical business logic and error handling paths
• Use --cov-report=term-missing to identify uncovered lines

Troubleshooting:

• If tests fail, ensure all dependencies are installed: poetry install --with dev,test
• For database issues, check migration status and run migrations if needed
• For frontend issues, ensure the main OpenHands frontend is built: make build
• Check logs in the logs/ directory for runtime issues
• If tests fail with import errors, verify PYTHONPATH=".:$PYTHONPATH" is set
• If GitHub CI fails but local linting passes: Always use --show-diff-on-failure flag to match CI behavior exactly

Template for Github Pull Request

If you are starting a pull request (PR), please follow the template in .github/pull_request_template.md.

• The PR template now starts with a HUMAN: section, the human-tested checkbox, and an AGENT: section.
• .github/workflows/pr-readiness-confirm.yml checks non-draft PRs for non-empty text between HUMAN: and the human-tested checkbox; if present it adds a 👍 reaction, and if absent it posts a reminder comment.

Implementation Details

These details may or may not be useful for your current task.

Conversation State Management

Agent State and Sandbox Status:

The frontend uses useAgentState hook (frontend/src/hooks/use-agent-state.ts) to determine the current conversation state. This hook:

• Returns curAgentState (AgentState enum) for UI state determination
• Returns isArchived flag when sandbox_status === "MISSING" (archived conversations)
• Prioritizes live WebSocket execution status over cached API data

Archived Conversations (sandbox_status === "MISSING"):

When a conversation's sandbox is no longer available (archived):

• useAgentState returns AgentState.STOPPED and isArchived: true
• Chat input is replaced with an archived banner (ArchivedBanner component)
• VS Code tab, Terminal, and Planner show read-only messages instead of loading states
• All interactive elements that require a running sandbox are disabled

Testing useAgentState:

When mocking useAgentState in tests, always include the isArchived property:

vi.mock("#/hooks/use-agent-state", () => ({
  useAgentState: () => ({
    curAgentState: AgentState.AWAITING_USER_INPUT,
    isArchived: false,
  }),
}));

Microagents

Microagents are specialized prompts that enhance OpenHands with domain-specific knowledge and task-specific workflows. They are Markdown files that can include frontmatter for configuration.

Types:

• Public Microagents: Located in microagents/, available to all users
• Repository Microagents: Located in .openhands/microagents/, specific to this repository

Loading Behavior:

• Without frontmatter: Always loaded into LLM context
• With triggers in frontmatter: Only loaded when user's message matches the specified trigger keywords

Structure:

---
triggers:
- keyword1
- keyword2
---
# Microagent Content
Your specialized knowledge and instructions here...

Frontend

Action Handling:

• Actions are defined in frontend/src/types/action-type.ts
• The HANDLED_ACTIONS array in frontend/src/state/chat-slice.ts determines which actions are displayed as collapsible UI elements
• To add a new action type to the UI:
  1. Add the action type to the HANDLED_ACTIONS array
  2. Implement the action handling in addAssistantAction function in chat-slice.ts
  3. Add a translation key in the format ACTION_MESSAGE$ACTION_NAME to the i18n files
• Actions with thought property are displayed in the UI based on their action type:
  • Regular actions (like "run", "edit") display the thought as a separate message
  • Special actions (like "think") are displayed as collapsible elements only

Adding User Settings:

• To add a new user setting to OpenHands, follow these steps:
  1. Add the setting to the frontend:
     • Add the setting to the Settings type in frontend/src/types/settings.ts
     • Add the setting to the ApiSettings type in the same file
     • Add the setting with an appropriate default value to DEFAULT_SETTINGS in frontend/src/services/settings.ts
     • Update the useSettings hook in frontend/src/hooks/query/use-settings.ts to map the API response
     • Update the useSaveSettings hook in frontend/src/hooks/mutation/use-save-settings.ts to include the setting in API requests
     • Add UI components (like toggle switches) in the appropriate settings screen (e.g., frontend/src/routes/app-settings.tsx)
     • Add i18n translations for the setting name and any tooltips in frontend/src/i18n/translation.json
     • Add the translation key to frontend/src/i18n/declaration.ts
  2. Add the setting to the backend:
     • Add the setting to the Settings model in openhands/storage/data_models/settings.py
     • Update any relevant backend code to apply the setting (e.g., in session creation)

Settings UI Patterns:

There are two main patterns for saving settings in the OpenHands frontend:

Pattern 1: Entity-based Resources (Immediate Save)

• Used for: API Keys, Secrets, MCP Servers
• Behavior: Changes are saved immediately when user performs actions (add/edit/delete)
• Implementation:
  • No "Save Changes" button
  • No local state management or isDirty tracking
  • Uses dedicated mutation hooks for each operation (e.g., use-add-mcp-server.ts, use-delete-mcp-server.ts)
  • Each mutation triggers immediate API call with query invalidation for UI updates
  • Example: MCP settings, API Keys & Secrets tabs
• Benefits: Simpler UX, no risk of losing changes, consistent with modern web app patterns

Pattern 2: Form-based Settings (Manual Save)

• Used for: Application settings, LLM configuration
• Behavior: Changes are accumulated locally and saved when user clicks "Save Changes"
• Implementation:
  • Has "Save Changes" button that becomes enabled when changes are detected
  • Uses local state management with isDirty tracking
  • Uses useSaveSettings hook to save all changes at once
  • Example: LLM tab, Application tab
• Benefits: Allows bulk changes, explicit save action, can validate all fields before saving

When to use each pattern:

• Use Pattern 1 (Immediate Save) for entity management where each item is independent
• Use Pattern 2 (Manual Save) for configuration forms where settings are interdependent or need validation
• Git provider tokens in the local/OSS integrations settings are managed through the V1 secrets endpoints (POST/DELETE /api/v1/secrets/git-providers). Do not reuse the logout flow for disconnecting tokens; useLogout is for actual app logout and still targets legacy OSS logout behavior.

Adding New LLM Models

To add a new LLM model to OpenHands, you need to update multiple files across both frontend and backend:

Model Configuration Procedure:

1. Frontend Model Arrays (frontend/src/utils/verified-models.ts):

   • Add the model to VERIFIED_MODELS array (main list of all verified models)
   • Add to provider-specific arrays based on the model's provider:
     • VERIFIED_OPENAI_MODELS for OpenAI models
     • VERIFIED_ANTHROPIC_MODELS for Anthropic models
     • VERIFIED_MISTRAL_MODELS for Mistral models
     • VERIFIED_OPENHANDS_MODELS for models available through OpenHands provider

2. Backend CLI Integration (openhands/cli/utils.py):

   • Add the model to the appropriate VERIFIED_*_MODELS arrays
   • This ensures the model appears in CLI model selection

3. Backend Model List (openhands/utils/llm.py):

   • CRITICAL: Add the model to the openhands_models list (lines 57-66) if using OpenHands provider
   • This is required for the model to appear in the frontend model selector
   • Format: 'openhands/model-name' (e.g., 'openhands/o3')

4. Backend LLM Configuration (openhands/llm/llm.py):

   • Add to feature-specific arrays based on model capabilities:
     • FUNCTION_CALLING_SUPPORTED_MODELS if the model supports function calling
     • REASONING_EFFORT_SUPPORTED_MODELS if the model supports reasoning effort parameters
     • CACHE_PROMPT_SUPPORTED_MODELS if the model supports prompt caching
     • MODELS_WITHOUT_STOP_WORDS if the model doesn't support stop words

5. Validation:

   • Run backend linting: pre-commit run --config ./dev_config/python/.pre-commit-config.yaml
   • Run frontend linting: cd frontend && npm run lint:fix
   • Run frontend build: cd frontend && npm run build

Model Verification Arrays:

• VERIFIED_MODELS: Main array of all verified models shown in the UI
• VERIFIED_OPENAI_MODELS: OpenAI models (LiteLLM doesn't return provider prefix)
• VERIFIED_ANTHROPIC_MODELS: Anthropic models (LiteLLM doesn't return provider prefix)
• VERIFIED_MISTRAL_MODELS: Mistral models (LiteLLM doesn't return provider prefix)
• VERIFIED_OPENHANDS_MODELS: Models available through OpenHands managed provider

Model Feature Support Arrays:

• FUNCTION_CALLING_SUPPORTED_MODELS: Models that support structured function calling
• REASONING_EFFORT_SUPPORTED_MODELS: Models that support reasoning effort parameters (like o1, o3)
• CACHE_PROMPT_SUPPORTED_MODELS: Models that support prompt caching for efficiency
• MODELS_WITHOUT_STOP_WORDS: Models that don't support stop word parameters

Frontend Model Integration:

• Models are automatically available in the model selector UI once added to verified arrays
• The extractModelAndProvider utility automatically detects provider from model arrays
• Provider-specific models are grouped and prioritized in the UI selection

CLI Model Integration:

• Models appear in CLI provider selection based on the verified arrays
• The organize_models_and_providers function groups models by provider
• Default model selection prioritizes verified models for each provider

Environment Variable Enable Toggles

When adding a new boolean enable toggle read from an environment variable (e.g. FEATURE_ENABLED, SLACK_WEBHOOKS_ENABLED), the check must accept both 'true' and '1' as truthy values. Older Helm chart versions default to '1' rather than 'true', so accepting only one form silently disables the feature in those deployments.

Required pattern:

os.getenv('MY_FEATURE_ENABLED', 'false').lower() in ('true', '1')

Do not use:

os.getenv('MY_FEATURE_ENABLED', 'false').lower() == 'true'  # breaks when value is '1'
os.getenv('MY_FEATURE_ENABLED', 'false') == '1'             # breaks when value is 'true'
bool(os.getenv('MY_FEATURE_ENABLED'))                       # treats any non-empty string as True

This applies anywhere an env var gates a feature: backend config, web client config injectors, integration service initialization, etc. Add a unit test for the '1' case alongside the 'true' case.

Sandbox Settings API (SDK Credential Inheritance)

The sandbox settings API allows SDK-created conversations to inherit the user's SaaS credentials (LLM config, secrets) securely via LookupSecret. Raw secret values only flow SaaS→sandbox, never through the SDK client.

User Credentials with Exposed Secrets (in openhands/app_server/user/user_router.py):

• GET /api/v1/users/me?expose_secrets=true → Full user settings with unmasked secrets (e.g., llm_api_key)
• GET /api/v1/users/me → Full user settings (secrets masked, Bearer only)

Auth requirements for expose_secrets=true:

• Bearer token (proves user identity via OPENHANDS_API_KEY)
• X-Session-API-Key header (proves caller has an active sandbox owned by the authenticated user)

Called by workspace.get_llm() in the SDK to retrieve LLM config with the API key.

Sandbox-Scoped Secrets Endpoints (in openhands/app_server/sandbox/sandbox_router.py):

• GET /sandboxes/{id}/settings/secrets → list secret names (no values)
• GET /sandboxes/{id}/settings/secrets/{name} → raw secret value (called FROM sandbox)

Auth: X-Session-API-Key header, validated via SandboxService.get_sandbox_by_session_api_key()

Related SDK code (in software-agent-sdk repo):

• openhands/sdk/llm/llm.py: LLM.api_key accepts SecretSource (including LookupSecret)
• openhands/workspace/cloud/workspace.py: get_llm() and get_secrets() return LookupSecret-backed objects
• Tests: tests/sdk/llm/test_llm_secret_source_api_key.py, tests/workspace/test_cloud_workspace_sdk_settings.py

Issue Triage Automation

• .github/workflows/issue-opened.yml has a second issue-opened job that auto-applies good first issue after the duplicate check completes.
• The duplicate check is used only as a veto/guardrail for good first issue automation: duplicate or overlapping-scope issues should not be auto-labeled.
• The OpenHands classifier logic for newcomer suitability lives in scripts/issue_good_first_issue_check_openhands.py, with focused unit coverage in tests/unit/test_issue_good_first_issue_check_openhands.py.

Awesome Agent Conventions

A curated field guide to the convention files AI agents read, write, and act on.

22 conventions across 11 categories. From common project instruction files to newer agent-web discovery and trust formats.

Agent tools increasingly rely on plain files in a repository or website root: instructions, memory, rules, tool connections, prompt assets, discovery metadata, and protocol hints. The names are easy to mix up, and the adoption levels vary a lot.

This repo keeps the map practical:

• Know what a file is for. Each entry names the convention, usual filename, primary readers, and spec or source.
• Study real examples. Examples are fetched from public repositories by script, with provenance kept at the top of each file.
• Separate practice from proposal. Maturity labels show what is widely used, what is early, and what is still only proposed.

Contents

• Instruction & context · category page
  • 🟢 AGENTS.md
  • 🟢 CLAUDE.md
  • 🟢 Tool-specific instruction files
  • 🟠 OKF (Open Knowledge Format)
• Memory & state · category page
  • 🟢 MEMORY.md
  • 🟢 Memory Bank
• Spec-driven development · category page
  • 🟢 Spec Kit
  • 🟢 Kiro steering files
• Skills & prompt assets · category page
  • 🟢 SKILL.md
  • 🟢 Prompt asset files
  • 🟢 Claude Code commands
  • 🟢 Copilot prompt & instruction files
• Tooling & connections · category page
  • 🟢 MCP server config
• Rules & ignore files · category page
  • 🟢 Rules files
  • 🟢 AI ignore files
• Design · category page
  • 🟢 DESIGN.md
• Web & discoverability · category page
  • 🟢 llms.txt
  • 🟢 pricing.md
• Agent-web trust · category page
  • 🟠 auth.md
  • 🔵 ai.txt
• Identity & protocols · category page
  • 🟠 Agent Cards (A2A)
• Proposed namespace · category page
  • 🔵 The protocols.md namespace

What counts

This list is intentionally narrow. A file belongs here when it is a convention for agent behavior or agent-readable metadata: instructions, memory, skills, rules, tool config, prompt assets, or web-discovery hints.

Any file type can qualify - .md, .txt, .prompty, .json, dotfiles, or a directory pattern. Human-first project docs such as README.md, CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md stay out unless the file has become an agent convention in its own right.

Maturity tiers

The badge is a claim about adoption, not quality. It keeps a proven convention from being presented the same way as a new idea.

Badge	Tier	Meaning
🟢	Adopted	Used in production by multiple tools, projects, or teams.
🟠	Emerging	Published by a real organization, but still early or limited in adoption.
🔵	Proposed	Publicly described, but without clear adoption beyond the proposal.

Instruction & context

Standalone page: categories/instruction-context.md

	Convention	Files	Read by	Spec
🟢	AGENTS.md	AGENTS.md	Most coding agents - OpenAI Codex, Cursor, Jules, Aider, Gemini CLI, Zed, and others	spec ↗
🟢	CLAUDE.md	CLAUDE.md	Claude Code, and tools that read the Claude memory convention	spec ↗
🟢	Tool-specific instruction files	GEMINI.md AGENT.md QWEN.md WARP.md CONVENTIONS.md copilot-instructions.md	Each file is read by its namesake tool - Gemini CLI, Amp, Qwen Code, Warp, Aider, GitHub Copilot - often alongside or as a bridge to AGENTS.md	spec ↗
🟠	OKF (Open Knowledge Format)	.md	Agents over MCP (okfy, openknowledge, superops okf CLIs); Google's knowledge-catalog ingests bundles	spec ↗

• AGENTS.md - A plain-Markdown "README for agents" - build/test commands, conventions, and gotchas an agent needs before touching the code. The most widely adopted cross-tool instruction file.
• CLAUDE.md - Anthropic's memory file for Claude Code - loaded automatically at session start to carry project commands, style rules, and standing instructions across turns.
• Tool-specific instruction files - Per-tool instruction files that predate or coexist with AGENTS.md. Some tools now default to AGENTS.md while keeping legacy filenames alive, so these variants still matter when auditing real repositories.
• OKF (Open Knowledge Format) - A machine-first organizational knowledge base: a version-controlled folder of typed Markdown files (one concept per file) that any agent reads as ground-truth context. Open-sourced by Google Cloud in 2026 as the content layer to MCP's transport.

Memory & state

Standalone page: categories/memory-state.md

	Convention	Files	Read by	Spec
🟢	MEMORY.md	MEMORY.md	Claude Code's auto-memory - the per-project MEMORY.md index it writes and re-reads each session	spec ↗
🟢	Memory Bank	projectbrief.md productContext.md activeContext.md systemPatterns.md techContext.md progress.md	Cline, Roo Code, and Cursor (via the Memory Bank custom-instructions pattern)	spec ↗

• MEMORY.md - A persistent, agent-maintained index of durable facts - written and re-read across sessions so an agent accumulates project memory instead of relearning each time.
• Memory Bank - Cline's structured memory system - a set of Markdown files an agent reads at the start of every task to reconstruct full project context after its session memory resets. The six files shown are Cline's set; tools like Roo Code use an overlapping but different variant.

Spec-driven development

Standalone page: categories/spec-driven-development.md

	Convention	Files	Read by	Spec
🟢	Spec Kit	constitution.md spec.md plan.md tasks.md	GitHub Spec Kit's slash-command agents (Copilot, Claude, Gemini, Cursor, and more)	spec ↗
🟢	Kiro steering files	product.md structure.md tech.md	AWS Kiro (steering files are largely Kiro-specific)	spec ↗

• Spec Kit - GitHub's spec-driven workflow - a constitution plus per-feature spec → plan → tasks files that drive an agent through structured, reviewable implementation.
• Kiro steering files - Kiro's always-on steering docs - product, structure, and tech files that give the agent persistent project context outside of any single spec.

Skills & prompt assets

Standalone page: categories/skills-prompt-assets.md

	Convention	Files	Read by	Spec
🟢	SKILL.md	SKILL.md	Claude Agent Skills, Claude Code, Amp, Agent Skills-compatible tools	spec ↗
🟢	Prompt asset files	.prompty .prompt system_prompt.txt	Prompty tooling, Azure AI / Semantic Kernel, and apps that load externalized prompts	spec ↗
🟢	Claude Code commands	.md	Claude Code - project .claude/commands/ and user ~/.claude/commands/	spec ↗
🟢	Copilot prompt & instruction files	.prompt.md .instructions.md	GitHub Copilot in VS Code / Copilot CLI	spec ↗

• SKILL.md - A self-contained, model-invoked capability file that tells an agent when to load a reusable procedure and how to execute it.
• Prompt asset files - Externalized prompt files - Prompty's YAML-front-mattered .prompty, plain .prompt templates, and system_prompt.txt - that pull the prompt out of source code so it can be versioned and edited on its own. Only .prompty has a formal spec (prompty.ai); .prompt and system_prompt.txt are ad-hoc externalized-prompt filenames.
• Claude Code commands - A Markdown file Claude Code exposes as a /slash-command - a reusable, version-controlled prompt workflow, with optional frontmatter (allowed-tools, model, argument-hint) and $ARGUMENTS and shell placeholders (@file references are a general Claude Code prompt feature, not command-specific). Now converging with Agent Skills, but still widely committed in its own right.
• Copilot prompt & instruction files - Modular, path-scoped Copilot context: *.instructions.md auto-attach to matching files via an applyTo glob, while *.prompt.md are reusable prompts you invoke by name - the granular cousins of a single .github/copilot-instructions.md.

Tooling & connections

Standalone page: categories/tooling-connections.md

	Convention	Files	Read by	Spec
🟢	MCP server config	.mcp.json	Claude Code, Cursor, VS Code / Copilot, and Claude Desktop - every MCP host reads the same mcpServers schema, though the filename and path differ per tool	spec ↗

• MCP server config - A JSON file that tells an agent which Model Context Protocol servers to launch and how (command, args, env) - making a project's tool and data integrations portable, shareable, and version-controlled across every MCP-capable client.

Rules & ignore files

Standalone page: categories/rules-ignore-files.md

	Convention	Files	Read by	Spec
🟢	Rules files	.cursorrules .mdc .clinerules .clinerules/ (pattern) .windsurfrules	Cursor (.cursorrules / .mdc), Cline (.clinerules/ and legacy .clinerules), Windsurf (.windsurfrules)	spec ↗
🟢	AI ignore files	.aiignore .cursorignore .codeiumignore .aiexclude	JetBrains Junie (.aiignore), Cursor (.cursorignore), Codeium/Windsurf (.codeiumignore)	spec ↗

• Rules files - Per-tool rule files that scope agent behavior - older single-file forms (.cursorrules, .clinerules, .windsurfrules) and newer directory-based, glob-scoped forms (.cursor/rules/.mdc, .clinerules/, .windsurf/rules/.md).
• AI ignore files - gitignore-syntax files that fence an AI agent out of paths - secrets, vendored code, generated output - so they're never sent to the model as context.

Design

Standalone page: categories/design.md

	Convention	Files	Read by	Spec
🟢	DESIGN.md	DESIGN.md	Google Stitch natively; and coding agents (e.g. Claude Code) when pointed at it as design context	spec ↗

• DESIGN.md - A structured, machine-readable design specification - tokens, components, and layout intent - that an agent reads to generate or keep UI consistent with an established system. Open-sourced by Google Labs in 2026 as a cross-tool draft spec.

Web & discoverability

Standalone page: categories/web-discoverability.md

	Convention	Files	Read by	Spec
🟢	llms.txt	llms.txt llms-full.txt (pattern)	Docs sites publish it for LLM tools and crawlers - though no major provider has confirmed reading it	spec ↗
🟢	pricing.md	pricing.md	Agents and LLM browsers fetching a clean, parse-able pricing page	spec ↗

• llms.txt - A proposed-turned-widely-published standard: a root-level Markdown file giving LLMs a curated, link-rich map of a site's docs. Published across hundreds of developer-docs sites - though whether the major LLM providers actually read it remains unproven.
• pricing.md - The Markdown twin of a pricing page - same URL with a .md suffix - so an agent gets structured plans and numbers instead of scraping marketing HTML. A concrete, shipping instance of the page.md pattern.

Agent-web trust

Standalone page: categories/agent-web-trust.md

	Convention	Files	Read by	Spec
🟠	auth.md	auth.md	Agents discovering how to authenticate to a service (early adopters)	spec ↗
🔵	ai.txt	ai.txt	AI training/data-mining crawlers that voluntarily honor AI usage preferences; crawler support is not yet reliable	spec ↗

• auth.md - A Markdown file that tells an agent how to authenticate with a service - discovery of auth endpoints and flows. Shipped by WorkOS as a real, working convention, but adoption beyond it is still early.
• ai.txt - A text file declaring machine-readable consent, licensing, or policy preferences for AI training and data-mining. Spawning popularized the deployed root-file pattern, and a 2026 Internet-Draft now proposes a well-known URI; adoption and crawler obedience are still thin, so it stays 🔵.

Identity & protocols

Standalone page: categories/identity-protocols.md

	Convention	Files	Read by	Spec
🟠	Agent Cards (A2A)	agent-card.json agent.json (pattern)	A2A-compatible agents discovering another agent's capabilities	spec ↗

• Agent Cards (A2A) - The Agent2Agent (A2A) capability card - a JSON document at a well-known path advertising an agent's skills, endpoints, and auth so other agents can discover and call it. Now a Linux Foundation project at v1.0; adoption is growing but early.

Proposed namespace

Standalone page: categories/proposed-namespace.md

	Convention	Files	Read by	Spec
🔵	The protocols.md namespace	proof.md	- (no demonstrated readers; aspirational)	spec ↗

• The protocols.md namespace - A single maintainer's pre-registered namespace of ~74 aspirational .md "protocols" (proof.md, signature.md, reputation.md, …) staked as Schelling points for a future agent web. Published concept, no demonstrated adoption - see the page for the audited, honest caveats.

Maintaining examples

Example files are fetched, not invented. The extractor pulls them from public sources, stores them under conventions/<slug>/examples/<source>/<filename>, and adds a line-1 provenance comment. The examples remain under their upstream owners' licenses and terms; see THIRD_PARTY_EXAMPLES.md before reusing them.

To refresh everything:

pip install -r scripts/requirements.txt
python scripts/extract.py          # fetch real files + rebuild each convention's README
python scripts/build_readme.py     # rebuild this README from scripts/targets.json

Re-running is idempotent. A missing target prints a miss and is skipped. Examples are representative samples: any file over 256 KB (for example, a multi-MB llms-full.txt) is truncated with a marker pointing back to the full source. scripts/targets.json remains the source of truth for conventions that have not been migrated yet; the skill-md pilot uses local convention metadata instead. Edit the relevant source and re-run both scripts.

Shortcut targets are available in the Makefile:

make verify          # schema + generated files + example provenance + links
make extract         # refetch public examples and rebuild generated docs
make license-report  # summarize upstream licenses for vendored examples

CI keeps the generated files and links honest. The verify workflow checks that generated docs match catalog metadata and migrated local metadata, and that every spec, example, and instance URL still resolves on each pull request and weekly. Run the same link check locally with python scripts/check_links.py.

Contributing

Read CONTRIBUTING.md. In short: an entry must pass the filter above and carry evidence for its maturity tier. Add sources to scripts/targets.json for non-migrated conventions, run the scripts, and open a PR. The skill-md pilot uses local convention metadata instead. Do not hand-write example files.

Before proposing adjacent standards, check WATCHLIST.md. Project direction lives in ROADMAP.md.

License

The curation, scripts, and original prose in this repository are MIT. Vendored example files remain under their upstream owners' licenses and terms; see THIRD_PARTY_EXAMPLES.md.