Skip to content

user-guide.md

Latest commit

 

History

History
854 lines (618 loc) · 20.6 KB

user-guide.md

File metadata and controls

854 lines (618 loc) · 20.6 KB

Knowns User Guide

Complete guide for using Knowns - a CLI-first knowledge layer and task management system for development teams.

Getting Started

Installation

# Homebrew (macOS/Linux)
brew install knowns-dev/tap/knowns

# Shell installer (macOS/Linux)
curl -fsSL https://knowns.sh/script/install | sh

# Or with wget
wget -qO- https://knowns.sh/script/install | sh

# npm (requires Node.js 18+)
npm install -g knowns

# bun
bun install -g knowns

# npx (no installation, requires Node.js)
npx knowns <command>
# PowerShell installer (Windows)
irm https://knowns.sh/script/install.ps1 | iex

The macOS/Linux shell installer and the Windows PowerShell installer both auto-run knowns search --install-runtime after installing the binary. If that step fails, rerun it manually.

# Shell uninstaller (macOS/Linux)
curl -fsSL https://knowns.sh/script/uninstall | sh
# PowerShell uninstaller (Windows)
irm https://knowns.sh/script/uninstall.ps1 | iex

Initialize a Project

# In your project directory
knowns init [project-name]

Running knowns init starts an interactive wizard:

🚀 Knowns Project Setup Wizard
   Configure your project settings

? Project name: my-project
? Git tracking mode: Git Tracked (recommended for teams)
? AI Guidelines type: CLI

Wizard Options:

Option Choices Description
Project name Text Name for your project
Git tracking mode git-tracked / git-ignored How tasks are tracked in git
AI Guidelines type CLI / MCP CLI commands or MCP tools format
Agent files Multi-select Which AI instruction files to create

What happens:

  • Creates .knowns/ directory with tasks/, docs/, templates/, config.json
  • If MCP selected: Creates .mcp.json for Claude Code auto-discovery
  • If git-ignored selected: Updates .gitignore to exclude tasks (docs/templates still tracked)
  • Creates selected AI instruction files (CLAUDE.md, AGENTS.md, etc.)

Quick init (skip wizard):

# Use defaults with custom name
knowns init my-project --no-wizard

# Force reinitialize existing project
knowns init --force

Quick Start

# Create your first task
knowns task create "Setup project" -d "Initial project setup"

# View all tasks
knowns task list

# Start the Web UI
knowns browser --open

New in v0.18.0+

  • Workspace-aware browser mode — run knowns browser outside a repo to scan for projects and switch between them without restarting.
  • AST-based code intelligence for Go, TypeScript, JavaScript, and Python via knowns code ingest.
  • Code graph visualization in the browser UI — explore symbols, dependencies, and relationships.
  • Use knowns browser --watch or knowns code watch to keep code search data fresh while you work.
  • Explore richer chat history and runtime status from the browser chat page.
  • Self-update with knowns update — detects install method and upgrades in place.
  • knowns retrieve for structured context retrieval with citations (designed for agent workflows).
  • ONNX Runtime-based local semantic search with SQLite vector store — no external API needed.
  • Kiro IDE and Codex platform support during knowns init.

CLI Command Reference

Task Commands

Create Task

knowns task create "Title" [options]

Options:

Option Short Description
--description -d Task description
--ac Acceptance criteria (repeatable)
--label -l Task label (repeatable)
--priority low | medium | high
--parent Parent task ID
--assignee -a Assign to user (@me, @username)

Examples:

knowns task create "Add login" -d "Implement user login" --ac "Login form works" --ac "JWT tokens stored" -l auth -l feature --priority high

View Task

knowns task <id> [--plain]           # Shorthand
knowns task view <id> [--plain]      # Full command
  • --plain - Plain text output (for AI agents)

List Tasks

knowns task list [options]

Options:

Option Description
--status Filter by status
--assignee Filter by assignee
--priority Filter by priority
--label Filter by label
--tree Show hierarchy tree
--plain Plain text output

Examples:

knowns task list --status in-progress --assignee @me
knowns task list --tree --plain

Edit Task

knowns task edit <id> [options]

Options:

Option Short Description
--title -t Update title
--description -d Update description
--status -s Update status
--priority Update priority
--assignee -a Update assignee
--ac Add acceptance criterion
--check-ac Check AC by index (1-based)
--uncheck-ac Uncheck AC by index
--remove-ac Remove AC by index
--plan Set implementation plan
--notes Set implementation notes
--append-notes Append to notes

Examples:

knowns task edit 42 -s in-progress -a @me
knowns task edit 42 --check-ac 1 --check-ac 2
knowns task edit 42 --append-notes "✓ Feature implemented"

Documentation Commands

Create Document

knowns doc create "Title" [options]

Options:

Option Short Description
--description -d Document description
--tags -t Comma-separated tags
--folder -f Folder path

View Document

knowns doc <path> [--plain]          # Shorthand
knowns doc view "path/name" [--plain] # Full command

Edit Document

knowns doc edit "name" [options]

Options:

Option Short Description
--title -t Update title
--tags Update tags
--content -c Replace content
--append -a Append to content

List Documents

knowns doc list [--tag <tag>] [--plain]

Time Tracking Commands

Start Timer

knowns time start <task-id>

Stop Timer

knowns time stop

Pause/Resume Timer

knowns time pause
knowns time resume

Check Timer Status

knowns time status

Add Manual Entry

knowns time add <task-id> <duration> [-n "note"] [-d "date"]

Examples:

knowns time add 42 2h -n "Code review"
knowns time add 42 30m -d "2025-12-25"

Generate Report

knowns time report [options]

Options:

Option Description
--from Start date (YYYY-MM-DD)
--to End date (YYYY-MM-DD)
--by-label Group by labels
--csv Export as CSV

Search Commands

knowns search "query" [options]

Options:

Option Description
--type all | task | doc | memory
--status Filter by status
--priority Filter by priority
--label Filter by label
--tag Filter by tag
--assignee Filter by assignee
--keyword Force keyword-only search
--limit Limit results (default: 20)
--plain Plain text output
--json JSON output 
knowns retrieve "query" [options]

Options:

Option Description
--expand-references Expand @doc/@task references
--source-types Comma-separated: doc,task,memory
--keyword Force keyword-only retrieval
--limit Limit candidates (default: 20)
--plain Plain text output
--json JSON output

Model Commands

Manage embedding models for semantic search. Requires ONNX Runtime; the install scripts try to install it automatically, or you can run knowns search --install-runtime manually.

List Models

knowns model list

Shows all available models (built-in + custom) with download status.

Download Model

knowns model download <model-id>

Built-in models:

Model Quality Dimensions Best for
multilingual-e5-small Balanced 384 Multilingual (default)
gte-small ★ Balanced 384 English projects
all-MiniLM-L6-v2 Fast 384 Large codebases
gte-base Quality 768 High accuracy
bge-small-en-v1.5 Balanced 384 English retrieval
bge-base-en-v1.5 Quality 768 Top retrieval
nomic-embed-text-v1.5 Quality 768 Long context (8K tokens)

Set Model for Project

knowns model set <model-id>

After changing models, rebuild the search index:

knowns search --reindex

Check Status

knowns model status

Shows downloaded models, disk usage, and current project configuration.

Template Commands

Templates help you generate boilerplate code consistently.

List Templates

knowns template list [--plain]

Run Template

knowns template run <name> [options]

Options:

Option Description
--dry-run Preview without creating files
--<variable> Pre-fill prompt variable
--no-<variable> Set boolean to false

Examples:

# Interactive mode
knowns template run react-component

# With pre-filled values
knowns template run react-component -v name=UserProfile

# Preview only
knowns template run react-component --dry-run

View Template

knowns template view <name>

Create Template

knowns template create <name> [-d "description"] [--doc <path>]

Example:

knowns template create api-service -d "REST API service" --doc patterns/api

Skill Commands

Skills are AI workflow instructions that sync across platforms.

List Skills

knowns skill list [--plain]

Sync Skills

knowns skill sync

This command exists, but project/platform sync is mainly handled by knowns import sync and top-level knowns sync.

Examples:

knowns skill sync

Template Guide

What are Templates?

Templates are code generators that create files from Handlebars templates with interactive prompts. They help you:

  • Generate consistent boilerplate code
  • Follow project patterns automatically
  • Speed up repetitive file creation

Template Structure

.knowns/templates/
└── react-component/
    ├── _template.yaml          # Config: prompts, actions
    ├── {{pascalCase name}}.tsx.hbs
    └── {{pascalCase name}}.test.tsx.hbs

Using Templates

# 1. See available templates
knowns template list

# 2. Preview what will be created
knowns template run react-component --dry-run

# 3. Generate files
knowns template run react-component
# ? Component name? UserProfile
# ? Include test? Yes
# ✓ Created src/components/UserProfile.tsx
# ✓ Created src/components/UserProfile.test.tsx

Creating Your Own Template

# Create template scaffold
knowns template create my-component

# Edit config
# .knowns/templates/my-component/_template.yaml

Example _template.yaml:

name: my-component
description: My custom component

destination: src/components

prompts:
  - name: name
    type: text
    message: "Component name?"
    validate: required

  - name: withTest
    type: confirm
    message: "Include test?"
    initial: true

actions:
  - type: add
    template: "component.tsx.hbs"
    path: "{{pascalCase name}}.tsx"

  - type: add
    template: "component.test.tsx.hbs"
    path: "{{pascalCase name}}.test.tsx"
    when: "{{withTest}}"

Handlebars Helpers

Helper Example Output
pascalCase {{pascalCase "user profile"}} UserProfile
camelCase {{camelCase "user profile"}} userProfile
kebabCase {{kebabCase "user profile"}} user-profile
snakeCase {{snakeCase "user profile"}} user_profile

Template-Doc Linking

Link templates to documentation for context:

# In _template.yaml
doc: patterns/react-component
# In doc

Related: @template/react-component

Web UI Guide

Starting the Web UI

knowns browser --open

This starts the Web UI server and opens it in your browser. Default port is 6420 unless overridden in config or via --port.

Navigation

The sidebar provides access to:

  • Kanban - Visual task board
  • Tasks - Table view of all tasks
  • Docs - Documentation browser
  • Graph - Knowledge graph (tasks, docs, memories + relationships)
  • Config - Project settings

Kanban Board

The Kanban board displays tasks in columns by status:

  • Todo - Tasks not yet started
  • In Progress - Tasks being worked on
  • In Review - Tasks in code review
  • Blocked - Tasks waiting on dependencies
  • Done - Completed tasks

Features:

  • Drag and drop tasks between columns
  • Click task card to view details
  • "New Task" button to create tasks
  • "Batch Archive" to clean up old done tasks

Task Details

Click any task to open the detail panel:

  • View/edit title, description
  • Check acceptance criteria
  • Change status, priority, assignee
  • View/add implementation notes
  • Track time with timer controls

Real-time Sync

The Web UI syncs in real-time with CLI changes:

  • Tasks updated via CLI appear instantly
  • Multiple browser tabs stay synchronized
  • SSE connection for live updates (auto-reconnects on sleep/wake)

Keyboard Shortcuts

Shortcut Action
⌘K / Ctrl+K Open command search
Esc Close dialogs

Time Tracking Guide

Workflow

  1. Start work on a task:

    knowns task edit 42 -s in-progress -a @me
knowns time start 42

  2. Take a break:

    knowns time pause
# ... break ...
knowns time resume

  3. Finish work:

    knowns time stop
knowns task edit 42 -s done

Viewing Time Entries

# Check current timer
knowns time status

# View time report for this month
knowns time report --from "2025-12-01" --to "2025-12-31"

# Export to CSV
knowns time report --csv > report.csv

Manual Entries

For time worked without the timer:

knowns time add 42 1h30m -n "Pair programming session"

MCP Integration Guide (for AI Agents)

Knowns includes a Model Context Protocol (MCP) server for AI integration.

Setup with Claude Code (Recommended)

# Auto setup - creates .mcp.json and configures Claude Code
knowns mcp setup

# Or during init, select "MCP" as AI Guidelines type
knowns init
# ? AI Guidelines type: MCP
# ✓ Created .mcp.json for Claude Code MCP auto-discovery

Manual Setup with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "knowns": {
      "command": "npx",
      "args": ["knowns", "mcp", "--stdio"]
    }
  }
}

Available MCP Tools

Tool Description
get_task Get task details by ID
list_tasks List tasks with filters
create_task Create a new task
update_task Update task fields
delete_task Delete a task (dry-run by default)
get_task_history Get version history of a task
get_doc Get document content
list_docs List all documents
create_doc Create a new document
update_doc Update a document
delete_doc Delete a doc (dry-run by default)
get_doc_history Get version history of a doc
search Unified search (tasks + docs + memories)
retrieve Ranked context retrieval with citations
reindex_search Rebuild semantic search index
code_search Search indexed code with neighbor expansion
code_symbols List indexed code symbols
code_deps List code dependency edges
code_graph Return full code graph (nodes and edges)
list_templates List available templates
get_template Get template config
run_template Run template (use dryRun: true first)
create_template Create new template
validate Validate refs and file integrity
get_board Get kanban board state
add_memory Create a memory entry (project or global layer)
list_memories List memories with filters
get_memory Get memory entry by ID
update_memory Update memory entry
delete_memory Delete memory entry
promote_memory Promote up one layer (working→project→global)
demote_memory Demote down one layer (global→project→working)
add_working_memory Add ephemeral session-scoped memory
list_working_memories List session memories
get_working_memory Get working memory by ID
delete_working_memory Delete a working memory entry
clear_working_memory Clear all session memories
detect_projects Scan for Knowns projects
set_project Set active project (for global MCP configs)
get_current_project Get current active project
start_time Start timer for a task
stop_time Stop active timer
add_time Manual time entry
get_time_report Generate time report

Plain Text Mode

Always use --plain flag when AI agents call CLI commands:

knowns task 42 --plain
knowns task list --plain
knowns doc "README" --plain

Reference System

Tasks, docs, and templates can reference each other:

  • @task-42 → Links to task 42
  • @doc/patterns/module → Links to document
  • @template/react-component → Links to template

References maintain their simple format in all outputs.

AI Guidelines Management

Sync instruction files with Knowns guidelines:

# Quick sync (CLAUDE.md, AGENTS.md) with full guidelines
knowns sync

# Sync only skills
knowns sync --skills

# Sync only instruction files for Claude
knowns sync --instructions --platform claude

Troubleshooting

Common Issues

"Error: Not initialized"

Run knowns init in your project directory first.

"Error: Task not found"

Check the task ID with knowns task list --plain.

"Error: Timer already running"

Stop the current timer with knowns time stop before starting a new one.

Web UI won't start

  • Check if port 6420 is available
  • Try knowns browser --port 6421

Tasks not syncing

  • Refresh the browser
  • Check SSE connection in browser dev tools
  • Wait for auto-reconnection if computer was asleep

Getting Help

# View help for any command
knowns --help
knowns task --help
knowns task create --help

Debug Mode

For detailed logging:

KNOWNS_DEBUG=1 knowns <command>

Self-Update

# Check for updates
knowns update --check

# Update to latest version and sync configs
knowns update

Report Issues

File issues at: https://github.com/knowns-dev/knowns/issues