Changea

• Add setNotifyProjectRoot() to cache project root in notify-server
• Call setNotifyProjectRoot() when MCP sets project via set_project tool
• Sync project root in getFileStore() for all MCP tool calls
• Fixes issue where MCP couldn't notify web UI due to process.cwd() mismatch

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.3...v0.11.4

Changes

• Add standalone binary detection with helpful error message
• Auto-increment port when requested port is in use (max 10 retries)
• Write running port to .server-port file for CLI to read
• Fix dark mode flash by setting theme before React loads
• Add background-color to body for proper theme display

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.2...v0.11.3

Fixed

• fix(ci): restructure workflow - version first, then build, then publish HO@howznguyen (#54)

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.1...v0.11.2

v0.11.1

Highlights

🍺 Homebrew Support

Knowns CLI is now available via Homebrew! No Node.js required.

brew install knowns-dev/tap/knowns

🪟 Windows Compatibility Fix

Renamed skill folders from kn:* to kn-* to fix Windows compatibility issues. Windows doesn't allow colons (:) in directory names.

Breaking Change: Skill invocation changed from /kn:init to /kn-init.

What's Changed

Features

• Homebrew tap: brew install knowns-dev/tap/knowns - standalone binary, no Node.js required
• Standalone binaries: macOS (arm64, x64) and Linux (x64) binaries included in releases
• Auto-update Homebrew: Formula automatically updates on new releases

Fixes

• Windows compatibility: Skill folders renamed from kn:* to kn-*
• Deprecated folder cleanup: Old kn:* and knowns.* folders are automatically removed on sync

Docs

• Added Homebrew install instructions to README, user-guide, and mcp-integration docs

Installation

# Homebrew (macOS/Linux) - no Node.js required
brew install knowns-dev/tap/knowns

# npm
npm install -g knowns

# bun
bun install -g knowns

Upgrading

# Homebrew
brew upgrade knowns

# npm
npm update -g knowns

# Re-sync skills to update folder names
knowns sync skills --force

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.0...v0.11.1

v0.11.0 - SDD (Spec-Driven Development) Support

What's New

CLI & Backend

• Add knowns validate --sdd command for SDD coverage reporting
• Add spec AC auto-sync - when task ACs are checked, matching spec ACs are automatically updated
• Add task-spec linking via spec: field in task frontmatter
• Add mermaid diagram rendering support in markdown

Skills

• Rename all skills to kn:* namespace (kn:init, kn:plan, kn:commit, kn:research, kn:implement, kn:extract, kn:template, kn:doc)
• Add kn:spec skill - create spec documents from requirements
• Add kn:verify skill - run SDD verification and coverage reporting

WebUI

• Add Dashboard page with 7 widgets:

  • Tasks overview with completion progress
  • Documentation stats
  • SDD Coverage widget
  • Time Tracking Summary (today/week/total)
  • Recent Activity feed
  • Recent Tasks list
  • Spec Progress Cards

• Add spec link on Kanban task cards - clickable link to spec document

• Add spec badges in Docs page (SPEC badge, status badge)

• Add AC Progress bar for spec documents

• Add expandable linked tasks list in spec view

• Add Specs filter in Docs page

• Add status badge (Draft/Approved/Implemented) to spec cards

• Fix kanban navigation bug when closing task detail

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.6...v0.11.0

Release v0.10.6

Highlights

This release adds MCP Project Detection for global MCP configurations (like Antigravity) and cleans up deprecated agent commands.

What's Changed

Added

• MCP Project Detection Tools - New tools for AI agents using global MCP configs:
  • detect_projects - Scan for Knowns projects in common workspace directories
  • set_project - Set the active project for all MCP operations
  • get_current_project - Verify current project status
• Auto Antigravity MCP Config - Automatically creates MCP config at ~/.gemini/antigravity/mcp_config.json during knowns init
• GEMINI.md sync by default - Now included in default sync targets

Removed

• knowns agents command - Use knowns sync instead
• mcp__knowns__get_guideline tool - Guidelines are now embedded in instruction files (CLAUDE.md, GEMINI.md, AGENTS.md)

Documentation

• Updated MCP integration docs with project detection workflow
• Added Antigravity configuration examples
• Updated all command references to use knowns sync

Migration Guide

For CLI Users

# Before (deprecated)
knowns agents guideline
knowns agents sync

# After
knowns sync
knowns sync --all

For MCP Users (Antigravity/Global Configs)

Add session initialization at the start of each session:

// 1. Detect available projects
mcp__knowns__detect_projects({})

// 2. Set active project
mcp__knowns__set_project({ "projectRoot": "/path/to/project" })

// 3. Verify
mcp__knowns__get_current_project({})

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.5...v0.10.6

Release v0.10.5

What's New

Multi-Timer Support ⏱️

You can now run multiple timers concurrently - one per task. No more stopping your current timer to track time on another task!

• Concurrent timers: Start timers on multiple tasks simultaneously
• Task ID normalization: Use either 42 or task-42 format - both work everywhere
• Interactive selection: When multiple timers are running, CLI prompts you to choose which one to stop/pause

# Start timers on multiple tasks
knowns time start 1
knowns time start 2
knowns time status  # Shows all active timers

# Stop specific timer
knowns time stop 1

Template Import Prefix 📦

Templates from imports are now fully accessible via CLI and MCP using the import prefix.

# View imported template
knowns template knowns/knowns-command

# Run imported template
knowns template run knowns/knowns-command --name myCommand

• CLI/MCP support import-name/template-name syntax
• URL encoding fixed for template names with slashes

TreeView UI 🌳

New hierarchical tree view for better organization:

• DocsPage: Docs organized in collapsible folders
• ImportsPage: Imported files shown in tree structure
• TemplatesPage: Local and imported templates grouped separately
• Orphaned imports: Shows imports on disk but not in config

Bug Fixes 🐛

• Fixed duplicate update notification in CLI
• Fixed URL encoding for imported templates in UI

Changelog

Added

• Multi-timer support with concurrent task tracking
• Task ID normalization (42 and task-42 both valid)
• TreeView component for hierarchical file display
• Import prefix support for templates in CLI/MCP
• resolveTemplate for local and imported template resolution

Changed

• DocsPage, ImportsPage, TemplatesPage now use TreeView
• Update notifier shows only once per session
• Guidelines and skill instructions updated

Fixed

• Duplicate update notification in CLI
• URL encoding for template names with slashes
• Orphaned imports now visible in ImportsPage

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.4...v0.10.5

v0.10.4

Added

• feat(discord): add Discord integration for releases and community HO@howznguyen (#43)

Changed

• feat(discord): add Discord integration for releases and community HO@howznguyen (#43)

Documentation

• feat(discord): add Discord integration for releases and community HO@howznguyen (#43)

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.3...v0.10.4

Fixed

• fix(mcp): fix template handler bugs and add syntax pitfall docs HO@howznguyen (#40)

Documentation

• fix(mcp): fix template handler bugs and add syntax pitfall docs HO@howznguyen (#40)

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.2...v0.10.3

Fix

• Fix syncImport to bypass "already exists" check with isSync option
• Fix syncAllImports to sync all imports (not just autoSync)
• Add toast notifications for sync success/error in web UI
• Add imports field to config API response
• Improve type safety for imports in config handlers
• Fix auto-expand for imported docs in sidebar
• Add sourceUrl display for imported docs/templates in list commands

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.1...v0.10.2

Fix

File changed: scripts/build-cli.js

Change: Rename createRequire → __createRequire in banner to avoid conflict with fdir package

- import { createRequire } from 'module';
+ import { createRequire as __createRequire } from 'module';
- const require = createRequire(import.meta.url);
+ const require = __createRequire(import.meta.url);

Why: The fdir package also imports createRequire, causing SyntaxError: Identifier 'createRequire' has already been declared on Node.js 24

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.0...v0.10.1

v0.10.0

New Features

Template System

• Code generation engine with Handlebars (.hbs) templates
• CLI commands: template list, template run, template create
• MCP handlers for template operations
• Web UI Templates page
• Built-in knowns-command template for scaffolding new CLI commands

Import System

• Import docs/templates from git, npm, or local sources
• Context-aware doc resolution (<GitHubMention username="doc" />/import-name/path)
• Support for import aliases and version pinning
• Commands: import add, import sync, import list

MCP Enhancements

• Full task operations via MCP: addAc, checkAc, uncheckAc, removeAc, plan, notes, appendNotes
• Unified search tool for searching both tasks and docs

Improvements

• Reorganized .knowns/docs into logical folders (ai/, architecture/, core/, development/, github/, templates/)
• Unified CLI/MCP guidelines (removed duplication)
• Added IDE instructions for Cursor and Windsurf
• Broken refs detection with visual indicators in Web UI

Bug Fixes

• Fixed favicon (32x32 and 16x16 versions)
• Static file serving fix for Express server

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.9.0...v0.10.0

v0.9.0

Features

• Skills System: Add knowns sync skills command and 8 Claude Code skills with dot notation (knowns.task, knowns.commit, etc.)
• Smart Doc Reading: Add --smart flag for auto-optimized document reading (full content for small docs, TOC for large docs)
• Section Editing: Add --section with numeric index support for editing specific document sections

Bug Fixes

• UI: Support alphanumeric task IDs in MDRender mentions (<GitHubMention username="task-pdyd2e" /> now renders correctly)

Refactor

• Reference System: Simplify ref format - keep <GitHubMention username="task-xxx" /> and <GitHubMention username="doc" />/xxx as-is instead of expanding to verbose paths
• Guidelines: Update all agent instruction files with simplified ref format

Deprecated

• knowns agents --update-instructions → Use knowns sync agent instead

Documentation

• Add claude-code-skills pattern documentation
• Fix duplicate headers in command-pattern doc

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.9...v0.9.0

New Features

• Smart Document Reading (--smart): New flag for intelligent document reading that automatically handles both small and large documents

  • Small docs (≤2000 tokens): Returns full content automatically
  • Large docs (>2000 tokens): Returns stats + TOC with numbered sections, then use --section <number> to read specific parts
  • Available in both CLI (--smart) and MCP (smart: true)

• Token Count in Doc List: doc list --plain now shows estimated token count for each document, helping AI agents assess document sizes at a glance

Bug Fixes

• Section by Number: Fixed --section to properly support numeric indices from TOC display (e.g., --section 1, --section 4)

Documentation

• Updated CLI and MCP guidelines to recommend using --smart as the default approach for reading documents

Usage

# Always use --smart when reading docs
knowns doc <path> --plain --smart

# If doc is large, smart returns TOC, then read specific section:
knowns doc <path> --plain --section 3

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.8...v0.8.9

Added

• feat(ui): add visual notifications for SSE connection status HO@howznguyen (#30)

Fixed

• [Bug]: [SSE] No visual notification when Server-Sent Events connection is lost (Silent Failure) #28

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.7...v0.8.8

Changed

• refactor(guidelines): split guidelines into cli and mcp variants HO@howznguyen (#26)

Documentation

• refactor(guidelines): split guidelines into cli and mcp variants HO@howznguyen (#26)

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.6...v0.8.7

Changed

• chore(deps): replace react-diff-viewer with react19 fork HO@howznguyen (#25)

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.5...v0.8.6

v0.8.5

Changed

• Guidelines default: Changed default from minimal to full embedded guidelines - AI now has immediate access to all rules without needing to call extra commands
• Sync command: Replaced --full flag with --minimal (knowns agents sync now uses full guidelines by default)
• Guidelines size: Optimized guidelines from ~1200 to ~600 lines (~50% reduction, ~1.7% context usage)
• Husky pre-commit: Fixed deprecated format and replaced bun with npx for CI compatibility

Added

• Context Optimization section: New guidelines section teaching AI how to reduce token consumption:
• Use --plain flag for compact output
• Search before reading all docs
• Selective file reading with offset/limit
• Write compact notes instead of verbose logs

Fixed

• GitHub Actions workflow failing due to bun not being available in CI environment
• Husky pre-commit hook using deprecated v9 format that will fail in v10

Documentation

• Updated docs/commands.md, docs/ai-workflow.md, docs/configuration.md, docs/user-guide.md, docs/mcp-integration.md to reflect new default behavior

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.4...v0.8.5

v0.8.4

Added

• MCP Auto-Setup: New knowns mcp setup command to automatically configure Claude Code integration
  • --project: Creates .mcp.json in project root for auto-discovery
  • --global: Adds knowns to Claude Code global config via claude mcp add-json
• Auto .mcp.json on Init: When selecting "MCP" as AI Guidelines type during knowns init, automatically creates .mcp.json for Claude Code auto-discovery

Changed

• Simplified Init Wizard: Streamlined from 7+ prompts to 4 essential options:
  • Project name
  • Git tracking mode (git-tracked / git-ignored)
  • AI Guidelines type (CLI / MCP)
  • Agent files to create (CLAUDE.md, AGENTS.md, etc.)
• Removed wizard prompts for: default assignee, default priority, default labels, time format (now uses defaults)

Documentation

• Updated docs/user-guide.md with init wizard examples
• Updated docs/mcp-integration.md with auto-setup instructions
• Updated docs/configuration.md with init wizard section
• Updated docs/commands.md with knowns mcp setup command reference

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.3...v0.8.4

Changed

• refactor(guidelines): modular structure with stage-specific options HO@howznguyen (#18)

Documentation

• refactor(guidelines): modular structure with stage-specific options HO@howznguyen (#18)

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.2...v0.8.3

Knowns v0.8.2

What's Changed

Agent Guidelines & Fallbacks

• Unified guidelines now live in shared templates (CLI + MCP + unified) with explicit “must follow” wording.
• MCP agents are instructed to run knowns agents guideline --cli and fall back to CLI commands when MCP tools are missing.
• Added minimal instruction templates for CLI/MCP; removed unused --gemini option and Gemini templates.

CI/CD Fixes

• chore(ci): remove redundant GitHub release step.

Upgrade

npm i -g knowns@0.8.2
# or
pnpm add -g knowns@0.8.2

———

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.1...v0.8.2

Knowns v0.8.1

What's Changed

Global Cache Location

Update notifier cache has been moved from project directory to a global location:

• Before: .knowns/cli-cache.json (inside each project)
• After: ~/.knowns/cli-cache.json (global)

This allows:

• CLI works anywhere, no project context required
• Avoids duplicate cache files across projects
• Consistent with popular CLI tools (~/.npm, ~/.yarn, ...)

CI/CD Fixes

• Auto-bump version from git tag before npm publish
• Removed duplicate workflow file

Upgrade

npm i -g knowns@0.8.1
# or
pnpm add -g knowns@0.8.1

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.0...v0.8.1

Release v0.8.0

What's New

Random 6-Character Task IDs

Task IDs now use random 6-character base36 format instead of sequential numbers:

# Old format
task-1, task-2, task-3

# New format
task-a7f3k9, task-m2x8p4, task-k9y2z7

Benefits:

• ~2.1 billion possible IDs
• No ID collision after archiving tasks
• Backward compatible - legacy IDs (task-1) still work

Update Notifier

CLI now checks for updates automatically:

 UPDATE  v1.0.0 available (current v0.8.0) → npm i -g knowns

• 1-hour cache to avoid slowing commands
• Auto-detects package manager (npm/pnpm/yarn/bun)
• Skips on CI, --plain mode, or NO_UPDATE_CHECK=1

CLI Output Improvements

Task list with separators:

48.1 | todo        | high   | Hub Connection Commands
44   | done        | high   | Create condensed guidelines

Search --plain nested format:

Tasks:
  To Do:
    [HIGH] 48.1 - Hub Connection Commands
  Done:
    [HIGH] 43 - Add interactive agents command

Docs:
  (root):
    readme.md - README

Changelog

• feat: add random 6-char task IDs with collision detection
• feat: add npm update notifier with PM detection
• feat: improve task list output with column separators
• feat: change search --plain from CSV to nested format
• docs: add ID strategy documentation
• docs: add update notifier section to CLI guide
• fix: update notifier tests for spacing changes

Upgrade

npm update -g knowns
# or
bun update -g knowns

Thanks

• OL@OliviaAlter for reporting the task ID collision issue #13

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.7.0...v0.8.0

Added

• CLI: --children option - View subtasks directly from parent task (knowns task <id> --children)
• CLI: Improved tree format - Better AI-readable format with > markers for hierarchy
• CLI: Escape sequence parsing - Support \n, \t, \r in CLI inputs for AI agents
• GitHub Automation:
  • Dependabot for automated dependency updates
  • Stale bot for auto-closing inactive issues/PRs
  • Release Drafter for auto-generated release notes
  • Welcome bot for first-time contributors
  • Auto-labeler based on Conventional Commits
• Documentation:
  • Development workflow guide
  • GitHub bots setup guide
  • Release process guide
  • Branch protection rules guide
  • Code of Conduct
  • Contributing guidelines
  • Issue templates (bug report, feature request)
  • Pull request template

Changed

• UI: Config-based status options - Task forms now use status options from config instead of hardcoded values HA@HarryVu176 (#3)
• Release workflow - Automatically bumps package.json version from release tag

Fixed

• UI: Missing status options - Added blocked and in-review status to task dropdown HA@HarryVu176 (#3)

Contributors

HA@HarryVu176 and HO@howznguyen

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.6.0...v0.7.0

Added

• Git Tracking Mode: Select tracking mode during knowns init
  • git-tracked (default): All .knowns/ files tracked in git (recommended for teams)
  • git-ignored: Only docs tracked, tasks/config ignored (personal use)
  • Automatically updates .gitignore for git-ignored mode
• SSE Auto-Reconnection: Web UI automatically refreshes data on reconnect
  • Detects when connection is restored after sleep/wake
  • Triggers tasks:refresh, time:refresh, docs:refresh events
• New Docs: Added feature documentation
  • features/git-tracking-modes.md - Git tracking modes explained
  • features/real-time-sync.md - SSE sync and reconnection behavior

Changed

• WebSocket → SSE: Migrated real-time updates from WebSocket to Server-Sent Events
  • Simpler protocol with built-in auto-reconnect
  • Better firewall compatibility (standard HTTP)
• Init requires Git: knowns init now checks for .git directory and exits with helpful message if not found
• Documentation Updates:
  • All docs translated to English
  • Updated architecture diagrams (WebSocket → SSE)
  • Added --plain flag clarification (only for view/list/search commands)
  • Added doc organization guide (core docs at root, categorized in folders)

Fixed

• Guidelines clarity: Updated CLI/MCP templates to clarify --plain flag usage
  • --plain only works with view/list/search commands
  • Create/edit commands do NOT support --plain

Added

• BlockNote Rich Text Editor: Replace markdown textarea with BlockNote WYSIWYG editor
  • Task description, implementation plan, and notes now use rich text
  • Docs page uses BlockNote for editing
• Mentions System: Reference tasks and docs with <GitHubMention username="task-X" /> and <GitHubMention username="doc" />/path
  • Autocomplete suggestions when typing @
  • Clickable mention badges with live data (title, status)
  • Works in both BlockNoteEditor and MDRender
• Error Boundary: Gracefully handle BlockNote rendering errors

Fixed

• Mention serialization: Correctly save mentions as <GitHubMention username="task-X" /> format instead of display text
• Mentions in tables: Delete/replace operations now work for mentions inside table cells
• Mentions in code blocks: Preserve raw <GitHubMention username="task-X" />, <GitHubMention username="doc" />/path in code blocks and inline code
  • UI: BlockNoteEditor and MDRender skip mention rendering in code
  • CLI: --plain output keeps mentions raw inside code blocks

Changed

• Editor view mode: Use MDRender for viewing, BlockNoteEditor for editing (better stability)
• Mention badge styles: Synchronized between MDRender and BlockNoteEditor
  • Task badges: green theme
  • Doc badges: blue theme

Added

• Template System: 2x2 matrix of guidelines (type × variant)
  • Types: cli (CLI commands) and mcp (MCP tools)
  • Variants: general (full ~15KB) and gemini (compact ~3KB)
• --gemini flag: Use compact Gemini variant for smaller context windows
  • knowns agents sync --gemini
  • knowns agents --update-instructions --gemini
• Doc list path filter: Filter docs by folder
  • knowns doc list "guides/" --plain
  • knowns doc list "patterns/" --plain
• Doc list tree format: Token-efficient tree view with --plain

Changed

• Restructured templates folder: src/templates/{cli,mcp}/{general,gemini}.md
• Interactive knowns agents now prompts for type and variant
• knowns agents sync supports --type, --gemini, --all options

Fixed

• --plain flag not working: Fixed Commander.js option inheritance for nested commands
  • Added .enablePositionalOptions() and .passThroughOptions() to parent commands
  • Affects: knowns task list --plain, knowns doc list --plain, knowns agents sync --gemini

Fixed

• Clear error message when server port is already in use

Added

• Atomic Design UI refactoring (atoms, molecules, organisms, templates)
• CLI enhancements for AI agents
• File-based content options (--content-file, --append-file)
• Text manipulation commands (doc search-in, doc replace, doc replace-section)
• Validate & repair commands for tasks and docs
• knowns agents sync command

Changed

• UI components reorganized following Atomic Design principles
• Improved shadcn/ui integration

Fixed

• Patch release with minor fixes