Skip to content

AI Agent Instructions

Reference for the cosalette package CLI commands that manage AI support in downstream app repositories. For a task-oriented walkthrough, see AI-Assisted Development.

cosalette ai init

Installs or refreshes the packaged instruction file in the current repository.

cosalette ai init              # install
cosalette ai init --force      # refresh with latest packaged version
cosalette ai init --check      # report staleness without modifying anything
cosalette ai init --target PATH  # install to a custom path
cosalette init                 # shorthand; supports the same flags
cosalette init --force         # shorthand
cosalette init --check         # shorthand

Default target: .github/instructions/cosalette.instructions.md

--check flag: Reports whether the installed instruction file is up to date with the packaged template. Exits 0 when current; exits 1 and prints a unified diff when the file is stale or missing. Downstream frontmatter keys added by other tools are ignored — a file that differs only by extra frontmatter keys is reported as up to date. Suitable for pre-commit hooks and CI staleness gates.

--force refresh is non-destructive: The body of the instruction file is replaced with the packaged version, but any frontmatter keys outside the framework-owned description and applyTo fields (e.g. a paths: key added for Claude Code) are preserved verbatim.

GitHub Copilot discovers instruction files from .github/instructions/ automatically. The default path requires no editor configuration.

What gets installed: A compact framework guide covering:

  • App composition-root pattern
  • @app.telemetry(), @app.command(), @app.device() declarative registration
  • @app.device() handlers must be async generators; yield is the reaction boundary
  • @app.react() for domain-event reactors (state stays pure, I/O in top-level reactors)
  • Type-based dependency injection via init=
  • Settings, lifecycle, testing, and error-handling patterns
  • Pointers to local CLI help topics

Compatibility pointer files: Canonical installs (without --target) also manage these files:

  • AGENTS.md — created if absent; managed pointer block created or updated
  • CLAUDE.md — managed pointer block updated only if the file already exists; skipped when the file already imports AGENTS.md (via an @AGENTS.md line or a symlink to AGENTS.md) to avoid duplicate context

The pointer blocks reference .github/instructions/cosalette.instructions.md rather than duplicating its content. Custom --target installs skip this management entirely.

MCP side-effect: When cosalette[mcp] is installed, cosalette ai init also writes .vscode/mcp.json registering the MCP server with the IDE. See MCP server commands below.

cosalette ai prime

Prints a concise bootstrap summary for downstream agents and developers.

cosalette ai prime    # canonical
cosalette prime       # shorthand

cosalette ai help

Prints curated framework guidance on a specific topic.

cosalette ai help architecture      # design principles and composition patterns
cosalette ai help telemetry         # device registration and publishing
cosalette ai help testing           # unit and integration testing
cosalette ai help configuration     # settings and environment conventions
cosalette ai help react             # domain-event reactors + async-generator device semantics

Topic help is namespaced under cosalette ai help <topic>. There is no top-level shorthand for topic help.

MCP Server Commands

Available when cosalette[mcp] (uv add 'cosalette[mcp]') is installed.

cosalette ai mcp serve

Starts the cosalette MCP server.

cosalette ai mcp serve                                  # stdio transport (default)
cosalette ai mcp serve --transport sse --port 8080      # SSE transport
python -m cosalette.mcp                                 # alternative stdio entrypoint
Option Default Description
--transport / -t stdio Transport type: stdio or sse
--port / -p 8080 Port number for SSE transport

stdio is the correct transport for IDE integration (VS Code Copilot, Cursor, Windsurf, Claude Code). In normal IDE workflows the IDE starts the server automatically via .vscode/mcp.json — manual invocation is only needed for SSE or non-IDE setups.

.vscode/mcp.json

Written by cosalette ai init when cosalette[mcp] is installed:

{
  "servers": {
    "cosalette": {
      "command": "cosalette",
      "args": ["ai", "mcp", "serve"],
      "env": {}
    }
  }
}

If the file already exists, cosalette merges the cosalette server entry rather than overwriting the file.

For the full MCP tool reference, see the MCP Server guide.