Skip to main content

​
Onboarding commands

​
cogniscape init

Save your customer key to the machine-level config. 
cogniscape init <customer-key>
​
customer-key
string
required
Your Cogniscape customer key. Find it in the Cogniscape dashboard under Settings → API Keys.
What it does:
1

Creates ~/.cogniscape/config.json

Saves the customer key at the machine level — shared across all projects on this machine.
2

Installs Claude Code hooks

Merges Cogniscape hooks into ~/.claude/settings.json automatically.
3

Installs Cursor hooks (if detected)

If ~/.cursor/ exists, merges hooks into ~/.cursor/hooks.json automatically.
Running cogniscape init again overwrites the existing key (idempotent).
The install script runs cogniscape init automatically when you pass your customer key. You only need to run this manually if you installed the binary without a key or want to change keys.

​
cogniscape update-key

Update the customer key for the current project. 
cogniscape update-key <new-customer-key>
Fails with an error if the machine has not been initialized with cogniscape init first.

​
cogniscape setup-hooks

Install Claude Code hooks manually. 
cogniscape setup-hooks
Merges Cogniscape hooks into ~/.claude/settings.json, preserving any existing third-party hooks. Creates a backup at ~/.claude/settings.cogniscape-backup.json before modifying. Idempotent — will not duplicate hooks already present.
cogniscape init runs this automatically. Use cogniscape setup-hooks directly only if you need to repair or re-install hooks without changing your customer key.
Claude Code hooks installed:
EventMatcherWhat it captures
SessionStart—Session lifecycle begin
Stop—Session summary + token usage
PostToolUseExitPlanModePlan approval
PostToolUseTaskCreateTask creation
PostToolUseTaskUpdateTask completion
Cursor hooks installed (in ~/.cursor/hooks.json, auto-detected when ~/.cursor/ exists):
EventWhat it captures
sessionStartSession lifecycle begin
stopSession summary (full conversation content)
sessionEndSession lifecycle end

​
cogniscape mcp update

Scan your machine for all AI tools with Cogniscape MCP configurations and update them to the latest format. 
cogniscape mcp update
Detects and updates configurations in Claude Desktop, Claude Code, Cursor, Codex, and OpenCode. Migrates legacy URLs and incompatible formats automatically.
FlagDescription
--dry-runPreview what would change without modifying any files
--verboseShow file paths of modified configs
--only "<tool>"Update only a specific tool (e.g., --only "Claude Desktop")

​
cogniscape mcp setup

Configure the Cogniscape MCP server in Claude Desktop — zero manual JSON editing. 
cogniscape mcp setup
The old cogniscape setup mcp command still works as an alias.
What it does:
1

Reads your customer key

From ~/.cogniscape/config.json (set by cogniscape init).
2

Injects the MCP server entry

Adds or updates the cogniscape-reader entry in Claude Desktop’s config at the platform-specific location:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
3

Preserves existing servers

Any other MCP servers already configured are left untouched.
Idempotent — running it again updates the entry with the current customer key.
Restart Claude Desktop after running this command to activate the MCP connection.
Edge cases handled:
ScenarioBehavior
Config file does not existCreates it
Cogniscape entry already existsUpdates in place
Other MCP servers configuredPreserved
Invalid/corrupted JSONBacks up the file and starts fresh
Customer key not setError with guidance to run cogniscape init first
Uninstall: 
cogniscape mcp setup --uninstall
Removes only the cogniscape-reader entry from Claude Desktop’s config, preserving all other MCP servers.
On Windows, the running binary cannot be deleted by the OS. cogniscape uninstall will remove hooks but print a message asking you to delete the binary manually.

​
cogniscape uninstall

Remove hooks and the binary. 
cogniscape uninstall
Removes Cogniscape hooks from ~/.claude/settings.json and ~/.cursor/hooks.json, then deletes the binary. Idempotent. On Windows, the binary cannot be self-deleted while running — a message will indicate the path for manual removal.

​
cogniscape version

cogniscape version
# cogniscape (go) v1.7.1

​
Authentication

All commands that call the API require a customer key, resolved in this order:
  1. --customer-key flag
  2. COGNISCAPE_CUSTOMER_KEY environment variable
  3. ~/.cogniscape/config.json (machine-level, set by cogniscape init)
  4. Error if none of the above is set
The key is sent as the X-Cogniscape-Customer-Key HTTP header on all requests.

​
Local files

PathPurpose
~/.cogniscape/config.jsonMachine-level customer key. Created by cogniscape init. Shared across all projects.
~/.cogniscape/hooks.logHook execution log. Rotated to the last 1000 lines when it exceeds 80 KB.
~/.cogniscape/hooks-debug.jsonlRaw hook payloads in JSONL format (debug). Same rotation policy.
~/.cogniscape/task-cache/<id>.jsonEphemeral task metadata for create→complete correlation. Purged on session end.
~/.claude/settings.jsonGlobal Claude Code settings. cogniscape setup-hooks adds hooks here.
~/.cursor/hooks.jsonCursor hooks config. Created automatically by cogniscape init when Cursor is detected.
~/.cursor/hooks.cogniscape-backup.jsonBackup of Cursor hooks before modification.
Claude Desktop configcogniscape mcp setup adds the MCP server here. Path varies by OS: macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\, Linux ~/.config/Claude/.