io.github.ozten/cantrip

Start here. Connect this workspace to a Cantrip project by writing a .cantrip.json file. All subsequent commands will target this project automatically. Call without arguments to check the current connection.

Create a new entity. Automatically marked as 'accepted'. Fields vary by type: - icp: name, description, demographics, jobs_to_be_done, willingness_to_pay, current_alternatives, priority, is_beachhead - pain_point: description, severity (low|medium|high|critical), frequency (rare|occasional|frequent|constant), evidence - value_prop: framing (required — use instead of 'name'; 'description' is stored in extensions), tagline, evidence - channel: name, channel_type, lifecycle_stage (exploring|testing|scaling|maintaining|killed), cac, estimated_reach, conversion_rate (note: 'description' maps to 'notes' column) - experiment: title (required — use instead of 'name'), hypothesis, description, status (proposed|designed|active|completed|analyzed|abandoned), success_metrics, outcome_notes, value_prop_id, channel_id - competitor: name, description, url, positioning, strengths, weaknesses, pricing_model - contact: name, email, phone, company, role, source, url, notes Extra fields (any field not in the schema above) are stored in extensions. After adding entities, pause and confirm with the user before adding more.

Edit an existing entity. Fields vary by type (same as cantrip_entity_add). Pass well-known fields directly, and any additional fields in the 'fields' object. Extra fields are stored in extensions.

Query the append-only audit trail of all actions taken on the project

Create a new project and connect this workspace to it. Pass 'brief_text' (product brief as text) to auto-extract ICPs, pain points, and value props as inferred entities (costs 5 credits). Or pass 'brief_path' (absolute file path) and the file will be read locally. Without a brief, the project is created empty (free) and you add entities manually. Writes .cantrip.json automatically after creation. After creating a project, add a few entities and confirm them with the user before going deeper.

Check remaining credits. Returns available credits, reserved credits (held by in-progress operations), and total balance.

View recent credit transactions. Shows usage debits, purchases, and running balance.

View available credit packs. Shows tier name, credits included, and price.

List gap-analysis opportunities — things that would move the project closer to ideal state. Each opportunity has a stable UUID that you can pass to cantrip_next_prompt or cantrip_next_run. Opportunities persist across calls; re-running gap analysis updates existing opportunities rather than replacing them. Review the project snapshot with the user before running opportunities.

Generate a context-rich LLM prompt for an opportunity. Returns a ready-to-use prompt with all relevant ontology context baked in. Zero credit cost.

Execute an enrichment opportunity with AI. Runs the LLM-powered enrichment inline — either updating existing entities' missing fields (targeted) or generating new entities (bulk). Returns when complete with a summary of what was created or updated. Parallelism: you may run different loop types concurrently (e.g. enrich ICPs + enrich competitors), but the daemon blocks concurrent runs of the same loop type for safety.

Manage projects. Actions: - list (default): List all projects in the current team. - update: Update a project's name or description. Uses the connected project unless 'slug' is provided. - delete: Delete a project and all its data. Uses the connected project unless 'slug' is provided.

List all items pending review (inferred entities and open escalations)

Accept an inferred entity, marking it as verified ground truth

Dismiss an inferred entity or open escalation. For entities: removes from review queue without accepting or rejecting (kept for history). For escalations: closes without resolving.

Reject an inferred entity (soft-delete, kept for history)

Resolve an open escalation with a resolution message

Browse project data at three zoom levels. No args: project overview with entity counts by type and review state, gaps, and review queue size. entity_type only: list all entities of that type (e.g. 'icps', 'pain-points', 'channels'). entity_type + entity_id: show full detail for one entity. This is the primary tool for listing and inspecting entities.

Check daemon health, authentication, and current project. Returns daemon reachability, authenticated identity (user, team), and the active project from .cantrip.json. When CANTRIP_API_KEY is missing, returns setup instructions with config examples for common MCP clients.