AI-Assisted Development¶

cosalette provides two complementary layers of AI support for downstream app repositories — a baseline that works in any environment, and an optional MCP server that gives IDE agents structured, app-aware access to framework knowledge.

Both layers are bootstrapped from the installed package. There is nothing to manually copy or download from the hosted documentation.

Baseline Setup¶

The baseline works with any AI assistant and has no extra dependencies. It is the right starting point for all cosalette app repositories.

Install the instruction file¶

Run the bootstrap command in your app repository after installing cosalette:

cosalette ai init    # canonical
cosalette init       # shorthand

This installs .github/instructions/cosalette.instructions.md. GitHub Copilot discovers instruction files from .github/instructions/ automatically — no editor configuration needed.

cosalette also creates or updates a managed pointer block in AGENTS.md. If CLAUDE.md already exists, the same block is updated there. These pointer files let tools that read top-level agent context files locate the instruction file — they do not duplicate its content.

opencode.ai and kilo.ai¶

For kilo.ai, opt in explicitly:

cosalette ai init --kilo              # create/update kilo.jsonc (comments preserved)
cosalette ai init --opencode          # deprecated — use --kilo instead

--kilo adds the instruction file path to kilo.jsonc. Existing JSONC comments in the file are preserved. --opencode still works but prints a deprecation notice; prefer --kilo for new setups.

Use CLI help topics¶

For deeper context on demand:

cosalette ai prime                  # concise bootstrap overview
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 prime is a supported shorthand for cosalette ai prime. Topic help stays under cosalette ai help <topic>.

Refresh after upgrades¶

After upgrading cosalette, sync the installed instruction file with the new package version:

cosalette ai init --force    # refresh with latest packaged version
cosalette init --force       # shorthand

--force is non-destructive: the instruction body is replaced, but any extra frontmatter keys you or another tool added (e.g. paths: for Claude Code) are preserved.

Check for staleness¶

Verify whether the installed file matches the packaged version without modifying anything:

cosalette ai init --check    # exits 0 if current; exits 1 + prints diff if stale
cosalette init --check       # shorthand

Use this as a pre-commit hook or CI gate to detect stale instruction files.

MCP Server¶

When cosalette[mcp] is installed, cosalette ai init also writes .vscode/mcp.json, registering the MCP server with your IDE. IDE agents using VS Code Copilot, Cursor, Windsurf, or Claude Code then have access to fourteen structured tools covering framework guidance, app introspection, configuration schemas, code scaffolding, and ADR context.

Install¶

uv add 'cosalette[mcp]'
# or
pip install 'cosalette[mcp]'

Bootstrap¶

cosalette ai init

cosalette ai init detects cosalette[mcp] and writes .vscode/mcp.json automatically alongside the instruction file. No manual server configuration is needed.

Start the server¶

cosalette ai mcp serve                                  # stdio (IDE default)
cosalette ai mcp serve --transport sse --port 8080      # SSE (team / remote)
python -m cosalette.mcp                                 # alternative stdio entrypoint

Your IDE reads .vscode/mcp.json and starts the server automatically when needed. Manual invocation is only required for SSE or non-IDE setups.

For the full tool reference, transport options, and app-aware introspection setup, see the MCP Server guide.

For the complete command reference, see AI Agent Instructions.