Documentation Index
Fetch the complete documentation index at: https://docs.cogniscape.app/llms.txt
Use this file to discover all available pages before exploring further.
v1.12.1 — 04/29/2026 7:35 AM
Fix: Cost reports showed $0 for sagas worked on inside developer worktrees When a developer ran a coding session from a Git worktree they created themselves (withgit worktree add), the CLI tagged that session’s token usage with the wrong branch — it recorded main instead of the actual feature branch. As a result, asking the platform for the cost of the related PR or issue returned $0.00 even though real spend existed for that work.
The CLI now recognizes both layouts a developer might use — the AI-managed .claude/worktrees/ directory and the manually-created .worktrees/ directory — and attributes token usage to the correct branch in either case.
- Cost reports for new sessions in developer worktrees will join correctly to the matching PR or issue
- No change for sessions running in the main repository directory or in AI-managed worktrees
- Past token records already tagged with
mainare not retroactively re-attributed
v1.12.0 — 04/16/2026 12:30 PM
New: Update all your MCP configurations with a single command The CLI can now scan your machine for every AI tool that has a Cogniscape MCP connection and update them all at once. If you previously configured Cogniscape in Claude Desktop, Claude Code, Cursor, Codex, or OpenCode, runningcogniscape mcp update will detect outdated configurations and migrate them to the latest format.
- Automatically finds and updates Cogniscape MCP configs across Claude Desktop, Claude Code, Cursor, Codex, and OpenCode
- Preview what would change before committing with
--dry-run - Filter to a specific tool with
--only "Claude Desktop"or see file paths with--verbose - New command namespace:
cogniscape mcp setupandcogniscape mcp update(the oldcogniscape setup mcpstill works)
v1.11.4 — 04/13/2026
Fix: Claude Code hooks failed on Windows with “command not found” On Windows, the CLI wrote the full Windows-style binary path (with backslashes) into the Claude Code hooks configuration. Claude Code on Windows runs hooks through git-bash, which consumes backslashes as escape characters — soC:\Users\name\...\cogniscape.exe became C:Usersname...cogniscape.exe and every hook invocation failed with “command not found”.
The CLI now writes the hook command with forward slashes (C:/Users/name/.../cogniscape.exe), which git-bash handles natively. Developers who already ran setup-hooks on Windows should re-run it after upgrading.
- Fixes
SessionStart,Stop,SubagentStop,StopFailurehooks on Windows - No change for Linux or macOS
v1.11.3 — 04/13/2026
Fix: Windows PowerShell installer failed to copy the binary The Windows installer script was looking for a binary namedcogniscape_windows_arm64.exe (or _amd64.exe) inside the downloaded zip, but the release pipeline now packages it as plain cogniscape.exe so auto-update can find it after extraction. The installer failed with a “PathNotFound” error on every Windows install since v1.11.0.
Linux and macOS were not affected — the shell installer was already updated when the binary was renamed.
- Windows installer now copies
cogniscape.exefrom the extracted archive - Fixes both amd64 and arm64 installs
v1.11.2 (re-release) — 04/07/2026
Rollback: v1.12.0 withdrawn Version 1.12.0 removed the enrichment collection step from the CLI, but the removal was over-scoped — it also deleted compact, high-value fields that were being consumed downstream. A separate change that expanded the reader to use those fields was based on the incorrect assumption that all sessions produce enrichment data (only sessions with the claude-mem plugin do). Both changes have been reverted. The CLI returns to the exact behavior of v1.11.2. Developers on v1.11.2 are unaffected — no action required.- PR #318 — reverts #313 and #314
v1.11.2 — 04/01/2026 7:50 PM
Fix: only one of two parallel agents was recorded when they finished at the same time When two AI agents complete their work at nearly the same time within a session, both should appear as separate entries in the knowledge graph. In practice, only the first one was recorded — the second was silently discarded because the system couldn’t tell the two events apart. The root cause was that each agent’s completion event was identified by information they shared (the session they belonged to), rather than by what made them unique (their individual identity). When two events look identical, the system assumes they’re duplicates and drops one. The fix ensures each agent’s completion carries its own identity in the identifier, so no two agents can ever collide.- Parallel agents that finish close together are now both captured reliably
- No change to existing hook setup or configuration required
v1.11.1
Fix: background agent activity not captured in the knowledge graph When a coding session delegates work to background agents — research assistants that run in parallel while the developer continues working — the outcome of that work was not being recorded. Only agents that ran synchronously (blocking the session until they finished) were tracked. This meant that a significant portion of agent activity was invisible in the knowledge graph. Background agent conclusions are now captured reliably, regardless of how they were dispatched.- Background agent outcomes now appear in the knowledge graph alongside synchronous agent results
- Existing hook installations are updated automatically on next setup
v1.11.0
More accurate AI cost reporting and visibility into session failures Two meaningful gaps in how Cogniscape tracks AI usage have been closed in this release. When Claude Code spawns subagents — specialized assistants that work in parallel on independent parts of a task — those agents do their own AI processing and consume tokens separately. Until now, Cogniscape only counted the tokens used by the main session, missing the work done by subagents entirely. In practice, this meant that cost and usage data shown to managers was significantly understated. Token reporting now captures the full picture: both the main session and all subagents are counted together. Additionally, sessions that end abruptly because of a billing limit, rate limit, or authentication problem now generate an explicit event in the activity feed. Previously these failures were silent — there was no way to know a developer’s session was cut short without them manually reporting it. A new event type records the session error and its cause so team leads can see if a developer was blocked mid-task.- Token usage in session summaries now includes all subagent activity, not just the top-level session
- Sessions that fail due to API errors (billing, rate limit, authentication) now appear as a distinct event rather than disappearing silently
- Existing hook installations are updated automatically on next setup
v1.10.0
CLI version tracking and cleaner event pipeline Cogniscape now tracks which CLI version each developer has installed. This gives team leads a real-time map of update adoption across the organization — no need to ask developers individually or check machines manually. Additionally, three low-value event hooks were removed to reduce unnecessary processing costs. Session summaries already capture the complete picture of what happened during a coding session, making the individual plan-approved, task-created, and task-completed events redundant.- Every event sent by the CLI now includes its version, stored alongside token usage data
- Managers can query version adoption per developer at any time
- Removed hooks that were producing generic or empty data (saving processing and LLM costs)
- Existing machines are cleaned up automatically — obsolete hooks are pruned during the next auto-update
v1.9.0
Richer development insights from AI-powered session analysis When developers use tools that analyze their coding sessions (like claude-mem), the CLI now automatically detects and incorporates those insights into the data sent to Cogniscape. This means your knowledge graph gets richer context about each session — what was investigated, what was learned, what types of changes were made — without any extra configuration.- Sessions are automatically classified by type: bug fix, new feature, refactoring, discovery, or decision
- Structured summaries replace truncated text, giving managers a clearer picture of what happened
- The knowledge graph uses these classifications to build smarter relationships (e.g., “developer fixed X” instead of generic “developer worked on X”)
- Zero setup required — if the analysis tool is present, enrichment happens automatically; if not, everything works as before
v1.8.3
Faster session processing and more reliable event delivery Session data was being extracted by scanning the same transcript file three separate times — once for the summary, once for token usage, and once for metadata (files changed, commands run). This slowed down the session-end hook, especially for long conversations with large transcripts. Additionally, each incoming webhook opened and closed its own connection to the event queue. Under burst traffic, this created connection churn that could exhaust Redis connections.- Session-end hook now processes transcripts in a single pass, reducing I/O and latency
- Event queue uses a shared connection for the lifetime of the server, eliminating per-request connection overhead
- Queue status endpoint no longer opens a throwaway connection
v1.8.2
Fix: subagent conclusions not reaching the knowledge graph After the v1.8.1 fix enabled subagent tracking to fire correctly, the conclusions were still not appearing in the knowledge graph. The server rejected the data because the conclusion text arrived empty — the CLI was not reading the response in the format that AI coding tools actually send it.- Subagent conclusions now appear correctly in the knowledge graph
- The CLI handles multiple response formats for forward compatibility
v1.8.1
Fix: new hooks not applied after auto-update After auto-updating to a new CLI version, newly introduced hooks (such as the subagent tracking added in v1.8.0) were not being registered automatically. Developers had to runcogniscape setup-hooks manually to activate them.
This is now fixed — hook definitions are properly synced immediately after every auto-update, for both Claude Code and Cursor.
v1.8.0
Subagent activity tracking When AI coding tools delegate work to background research agents, Cogniscape now captures the outcome of that work — what was investigated, what was concluded, and which model was used. Previously, only the final result was visible in the knowledge graph; the reasoning behind decisions was lost.- Works in both Claude Code and Cursor
- Captures the agent’s objective, conclusion, type, and model
- Large responses are handled gracefully
v1.7.2
Fix: timestamp inconsistency causing delayed data availability Events from coding sessions and events from GitHub were using different timestamp formats, which occasionally caused data to appear with a delay of several hours in the knowledge graph. All CLI events now use a consistent timestamp format, and data is available within minutes of a session ending.v1.7.1
Fix: empty session summaries from Cursor Cursor session summaries were arriving empty (“no assistant message captured”) because the CLI was using the wrong format to read Cursor transcripts. Cursor and Claude Code use different transcript structures.- Cursor sessions now have a dedicated transcript reader
- Session summaries are correctly extracted from Cursor conversations
v1.7.0
Cursor IDE integration Cogniscape now tracks development sessions from Cursor alongside Claude Code. Sessions from each tool are clearly identified in the knowledge graph, enabling per-tool activity filtering.- Cursor hooks are installed automatically during
cogniscape initwhen Cursor is detected - Three session events are captured: session start, session end, and session summary
- Developer identity is resolved from Cursor’s account email when git config is unavailable
- Hooks are removed cleanly on
cogniscape uninstall - Cursor and Claude Code sessions are labeled separately for easy filtering
Token usage tracking is not yet available for Cursor sessions because Cursor does not provide this data in its hook system. This will be supported once Cursor adds the capability.
v1.6.0
Richer session summaries Sessions that previously produced generic entries like “completed a session” now generate detailed, structured summaries including what was worked on, which files were touched, and what the outcome was.- Session summaries now include: files modified, files read, recent commands, and tool usage counts
- An AI-powered summarizer transforms raw session data into structured narratives with clear objectives and outcomes
- File paths are always shown relative to the project root — no personal directory information is exposed
- Each session gets a unique identifier, fixing an issue where only the first summary from repeated sessions was recorded
v1.5.2
Fix: broken auto-update downloads A naming mismatch between the CLI and the release server was causing auto-update downloads to fail silently. This is now fixed, and both old and new naming conventions are supported for backward compatibility.v1.5.1
Fix: subagent activity attributed to wrong repository When Claude Code delegates work to isolated subagents, the CLI was incorrectly identifying the repository name, causing that activity to disappear from repository-filtered views.- Repository names are now resolved correctly regardless of the working directory
- Task events now include complete metadata (title, description, and status transitions)
v1.5.0
Git branch tracking + silent auto-update Two improvements for enterprise teams: Branch context in every event:- All events now include the current git branch, making it easy to see which feature or initiative a session relates to
- Works gracefully in non-git directories and CI environments
- The CLI now keeps itself up to date automatically — no manual downloads required
- Updates are checked once per day and applied in the background without interrupting your work
- Integrity is verified via checksum before applying any update
- Downgrades are prevented during rollback scenarios
v1.4.0
Windows support The CLI now works on Windows alongside macOS and Linux, removing a platform blocker for enterprise adoption.- Full support for Claude Desktop MCP configuration on all three platforms
- Developer identity is resolved correctly on Windows
- Uninstall works on all platforms (with guidance for Windows-specific limitations)
- New PowerShell install script for Windows environments
- Release pipeline now publishes Windows binaries for both AMD64 and ARM64
v1.3.0
One-command MCP setup for Claude Desktop Reduces onboarding from several minutes of manual configuration to a single command. Particularly important for non-developer users (managers, founders) who want to query the knowledge graph from Claude Desktop.- New command:
cogniscape setup mcp— automatically configures the Cogniscape MCP in Claude Desktop - Supports
cogniscape setup mcp --uninstallfor clean removal without affecting other MCP servers - Safe to run multiple times — updates the configuration in place
- Handles edge cases gracefully: missing config files, existing configurations, and corrupted files (creates a backup before modifying)
v1.2.1
API domain migration Migrated the CLI to the production API domain (api.cogniscape.app). No user action required — the CLI resolves the correct endpoint automatically.
v1.2.0
Project name tracking Session summaries now include the project name, enabling per-project filtering and grouping. The project name is derived from your working directory when the session ends.v1.1.0
Session duration and token usage tracking Two features that together enable ROI estimation: knowing how long a session lasted and how many tokens each AI model consumed.- Sessions now include duration (in seconds) computed from the conversation timeline
- Token usage is tracked per model, enabling accurate cost breakdowns when multiple models are used in a single session
- The Cogniscape MCP includes tools for querying token usage and estimated costs per developer
v1.0.0
Initial release The first stable release of the Cogniscape CLI. Provides the complete pipeline from AI coding tool hooks to knowledge graph ingestion. Onboarding:cogniscape init <customer-key>— saves your customer key and installs hooks automaticallycogniscape update-key <new-key>— updates the customer key without re-running initcogniscape setup-hooks— installs or repairs hooks, preserving any third-party hooks already configuredcogniscape uninstall— removes all Cogniscape hooks and deletes the CLI
- Five events captured automatically: session start, plan approved, task created, task completed, and session summary
- Developer identity resolved from your git configuration
- All errors are logged silently — the CLI never interrupts your coding tool
cogniscape writer add-episode— write custom entries to the knowledge graphcogniscape writer add-facts— create relationship records (e.g., “Alice implemented the payment retry feature”)cogniscape writer add-entity— create named entities with descriptions
cogniscape config show— display your current configurationcogniscape version— print the CLI version- Customer key can be set via command flag, environment variable, or config file