Claude Prompts

As of the August 2026 updates, the Semantic LLM Side-Client and the SemanticGateService have been retired. This change removes the ability to use an LLM-based side-client for semantic analysis and gate services, moving the system toward a unified, unconditional compositional gate service model.

Key Changes for Consumers:

• Semantic Analysis: The SemanticIntegrationFactory has been removed. Consumers (such as MCP tools) should now call createContentAnalyzer(logger, config) directly.
• Gate Services: GateServiceConfig no longer accepts llmIntegration options. The GateService is now unconditional and always returns a compositional service.
• Type Narrowing: The GateService.serviceType and GateValidationResult.validatedBy fields have been narrowed from 'compositional' | 'semantic' to just 'compositional'.
• CLI Changes: The CLI help text has been updated to remove retired *.mode spellings, repointing to canonical keys. The analysis mode remains but is marked as deprecated.

The project uses a governance model to ensure that AI agent instructions, architecture documentation, and actual code dependencies remain synchronized.

Core Principles:

• Authored Guidance: CLAUDE.md and scoped project rules (found in .claude/rules/*.md) are the only sources of truth for project guidance.
• Generated Projections: AGENTS.md is a generated, byte-checkable semantic projection of the authored guidance. It is intended to be consumed by agents but should not be edited manually.
• Semantic Boundaries: Modules are defined by semantic boundaries. Any direct child of a boundary declaring children: semantic must have a corresponding module.yaml file.
• Observed Facts: dependency-cruiser provides the observed import facts used to validate architecture and populate the module catalog.
• Deterministic Documentation: The docs/reference/module-catalog.md file is a generated, deterministic file used to track the module landscape and is checked for drift against the actual code structure.

When using the claude-prompts MCP server, be aware that prompt content is treated as direct instruction to the AI model. Specifically, the following fields can reach the client and influence the model's behavior:

• systemMessage: Sent on invocation, or via list detail:"full" if not present.
• userMessageTemplate: Sent on invocation.
• description: Sent at connection via the MCP prompts/list method.
• Argument descriptions: Sent at connection via the MCP prompts/list method.

Security Warning: Because the MCP prompts/list method is typically called by clients automatically upon connection, a malicious or 'poisoned' description in a prompt pack can land in the model's context without explicit user action. This is considered an 'instruction-surface poisoning' risk, which is an accepted characteristic of the product. However, the server prevents this from escalating to arbitrary code execution (e.g., sh -c) through established security tiers.

When using claude-prompts as a plugin in Claude Code, data persistence is handled via specific environment variables and directory structures. This ensures that plugin state (like settings or history) survives updates and is separated from the source code.

Key Environment Variables

• CLAUDE_PLUGIN_ROOT: The root directory of the plugin.
• CLAUDE_PLUGIN_DATA: The dedicated directory for persistent plugin data. This is substituted in .mcp.json env and args.
• MCP_WORKSPACE: In claude-prompts, this is set to ${CLAUDE_PLUGIN_ROOT}. Note that the plugin's own environment may override this.

Data Directory Naming

The location of your persistent data depends on how the plugin was loaded:

• Manual/Development Load: If loaded via --plugin-dir, the data directory is named ~/.claude/plugins/data/<plugin-name>-inline/.
• Marketplace Install: If installed via a marketplace, the directory follows the pattern ~/.claude/plugins/data/<plugin-name>-<marketplace>/.

Persistence Behavior

• What is persistent: When a plugin is updated, the data directory remains. However, if you are developing locally and the plugin is loaded from a source checkout, the data directory is treated as a separate entity from the source files.
• What is transient: Files located in {CLAUDE_PLUGIN_ROOT}/server/runtime-state (such as hooks-state.db) are considered transient session rows and are not moved to the durable data directory unless explicitly handled.

Hooks enable the use of operators (>>, -->, ==>, ::) directly in conversation, making workflows feel native rather than mediated.

Key capabilities unlocked by Hooks:

• Auto-routing: >>research_chain topic:'X' triggers the correct MCP tool call automatically.
• Chain continuity across compaction: Multi-step chains preserve state even when the LLM context is compacted mid-execution.
• Cross-step verdict tracking: Gate pass/fail results are shared across all steps without the LLM needing to re-derive them.
• Native agent handoffs: ==> automatically routes to the client's subagent system.
• Session persistence: Workflow state is preserved during context compaction.

Client Support:

• Full Support: Claude Code, OpenCode.
• Partial Support: Gemini CLI.
• Experimental Support: Codex (requires a one-time /hooks trust review; off by default).

The project is migrating to a 'Single Source Tree, Rendered Distributions' model for Agent Plugins. This migration affects how different surfaces interact with the core claude-prompts engine.

Key surfaces and their end states:

• npm package (claude-prompts): Remains the single engine. It is declared in mcp.json.
• Hooks: The root hooks/ directory is the single source of truth and is consumed via npm. Other clients like Gemini and Codex ship thin ADAPTERS over these hooks because their event models differ. Note that Agent Plugins 1.0.0 does not define core hooks or a client namespace string.
• Marketplaces: The minipuft-plugins repository serves as a 2-file index that lists claude-prompts (referencing this repo's dist) and codex-prompts. URLs in these listings are permanent and do not change.
• GitHub workflows: The release process moves from version-sync PRs to a render-based flow: npm → extensions → dist → render the Claude Code projections → drift check.

To use hooks with the Codex CLI, ensure the following platform requirements are met:

• Feature Flag: Hooks are experimental and must be enabled in config.toml using [features] hooks = true.
• OS Support: Hooks are not supported on Windows.
• Minimum Version: Requires Codex hooks version >=0.117.
• Timeout Units: Timeouts are measured in seconds (consistent with Claude Code, unlike Gemini's milliseconds).
• Hosted Tools: Tools like WebSearch do not trigger Pre/PostToolUse events.
• Context Limits: The additionalContextLimit defaults to approximately 2500 tokens. If the context overflows, it spills to disk and only a preview is shown to the model, which can break imperative directives.
• Trust Model: Plugin hooks require explicit user approval via the /hooks command. Trust is recorded against the hook's hash and must be re-verified if the hook changes.

When configuring or extending claude-prompts (or its sibling repositories like gemini-prompts and opencode-prompts), be aware of how environment variables are used for path resolution. Misconfigurations in these variables can lead to startup refusals or silent failures:

• MCP_RESOURCES_PATH: Used to locate resources. In some setups (like gemini-prompts), this is set to ${extensionPath}/node_modules/claude-prompts/resources. Note that if a client clones a repository without installing dependencies, node_modules/ will be missing, making this path invalid.
• MCP_WORKSPACE: Used for workspace-relative path resolution. Some installers (like opencode-prompts) use relative paths like ./node_modules/claude-prompts resolved from the server's working directory. If this variable is invalid or missing, certain CLI commands or hooks may fail or skip operations silently.

Warning for skills-sync users: The skills-sync CLI contains a silent fallback for MCP_RESOURCES_PATH (server/src/modules/skills-sync/service.ts:50-51). If you have a typo in this variable, the CLI may default to exporting a bundled set into client skill directories instead of failing, which can lead to unexpected behavior.