Documentation

Overview

Cognetivy gives your AI coding assistant an operational layer: versioned workflows, run tracking, step events, and schema-backed collections. All state lives in a local .cognetivy/ workspace - no cloud, no LLMs inside the engine. Your agent (Cursor, Claude Code, OpenClaw, or any MCP client) drives the CLI or MCP server; you inspect everything in Studio.

• Workflows - Directed acyclic graphs of nodes (prompts, inputs/outputs). Versioned and validated; no cycles.
• Runs - One execution of a workflow. Tracked with status, current node(s), and next-step hints for the agent.
• Events - NDJSON log per run (step_started, step_completed, run_completed, custom).
• Collections - Schema-backed data per run (sources, ideas, outputs). Optional traceability: citations, derived_from, reasoning.

Install

Run once with npx (no global install required):

npx cognetivy

The interactive installer will create a .cognetivy/ workspace in the current directory, prompt you to choose your coding agent(s), install the Cognetivy skill where needed, optionally apply a workflow template, and open Studio in your browser.

For use from any directory and for MCP, install globally:

npm install -g cognetivy

After a global install, run cognetivy install <target> to add the skill to Cursor, Claude Code, OpenClaw, or workspace. See Set up your agent below.

Set up your agent

Choose your coding agent for step-by-step setup (agent skills and/or MCP):

Claude Code

Full agent skills + MCP

Cursor

Skills + MCP server

OpenClaw

Agent skill + MCP

GitHub Copilot

MCP or Agent Skills bundle

Gemini CLI

MCP or Agent Skills bundle

OpenAI Codex

MCP or Agent Skills bundle

Amp

MCP or Agent Skills bundle

Cursor Agent CLI

MCP or Agent Skills bundle

OpenCode

MCP or Agent Skills bundle

Factory Droid

MCP or Agent Skills bundle

Qwen Code

MCP or Agent Skills bundle

MCP - any client

Standard protocol

Core concepts

Cognetivy organizes agent work into workflows, runs, and collections. The run engine computes the next step from the workflow DAG and current run state; your agent follows the hint (run_node, run_nodes_parallel, complete_node, complete_run).

Workflow structure

A workflow is a single connected DAG: nodes (prompts) connected by input/output collections. Cycles are not allowed and are rejected at validation. Each node can declare required_skills and required_mcps. Workflows are versioned; the workspace has a current workflow and current version.

Run lifecycle

Start a run with run start --input <file>. The CLI (and MCP) return COGNETIVY_NEXT_STEP with action, node_id(s), and hint. Use run step to start the next node or complete a node with collection payload. When the action is run_nodes_parallel, spawn one sub-agent per runnable node unless the user says otherwise. End with event append run_completed and run complete.

Collections and traceability

Collection schema is workflow-scoped (kinds and item_schema). Every kind except run_input supports optional citations, derived_from, and reasoning. Populate these so outputs are traceable to sources and chain of thinking. Use Markdown in long text fields for better display in Studio.

Create a workflow and run it

Once your agent is connected, ask it to create a workflow and start a run. Example prompts:

“Create a workflow with three nodes: one that gathers requirements, one that writes a plan, one that writes a summary. Save it as the current workflow.”

Then start a run:

“Start a run with input topic ‘user onboarding’.”

Open Studio to inspect the run, events, and collected data.

Onboarding: choose a template in the CLI

When you run npx cognetivy, the installer creates your workspace and installs skills. As part of onboarding, it then prompts you to choose a workflow template from the CLI. You pick one (e.g. bug triage, PR review, product PRD), and Cognetivy creates a workflow from that template and sets it as the current one. You can skip or change it later via cognetivy workflow apply-template.

Studio

Studio is the read-only web UI for your workspace. Open it with cognetivy studio or from the installer. You can:

• View the workflow DAG, node prompts, and collection schema
• Browse runs, run detail, and event timeline
• Inspect collections and collection items (with traceability)
• Compare workflow versions and apply templates from the gallery

More →

CLI reference

Commands are run from the project root (directory containing .cognetivy/). MCP tools mirror the CLI.