Web UI Guide

Visual interface for managing tasks, documentation, specs, memories, the knowledge graph, code graph, workspace switching, and built-in AI Chat.

Quick Start

knowns browser --open

Opens the Web UI at http://localhost:6420 unless overridden by config or --port.

Options

knowns browser --port 8080      # Custom port
knowns browser --no-open        # Don't open browser
knowns browser --restart        # Restart local server
knowns browser --watch          # Run browser with code watch flow
knowns browser --dev            # Verbose local mode
knowns browser --project /path  # Open a specific project directly
knowns browser --scan ~/work    # Scan directories for projects
knowns browser --tunnel         # Expose via Cloudflare Quick Tunnel

v0.18 Series Highlights

• Workspace-aware startup and switching from the browser experience
• Welcome-page flow when no active project is selected
• Dedicated code graph UX improvements
• Richer chat timeline and runtime status surfaces
• Browser watcher mode for code-aware local workflows

Features

AI Chat

Knowns includes built-in AI Chat with OpenCode as the native foundation.

• Chat in the same local product as tasks and docs
• Project-aware conversations without leaving Knowns
• Faster local experience after the Go rewrite
• Better rendering for tool calls, shell output, and multi-step AI interactions
• Timeline/history flow for searching, jumping, reverting, and forking conversations
• Runtime status surfaces so the UI can expose readiness and failures more clearly

Workspace Switching

The v0.18 browser updates improve project switching across the whole app:

• Start knowns browser from a project or from a neutral directory
• Show a welcome/picker flow when no active project is selected
• Switch projects without restarting the full browser session
• Keep tasks, docs, config, chat, graph, and search aligned to the active workspace

Memory

The Memory page gives you a browser for durable AI knowledge:

• View entries by layer: working, project, global
• Filter by category and tags
• Reuse patterns and decisions across future sessions
• Keep short-lived working context separate from persistent knowledge

Knowledge Graph

The Graph page visualizes how tasks, docs, and memories connect:

• See relationship edges across references and links
• Click any node to inspect details without leaving the graph
• Spot clusters of related knowledge
• Use it as a fast map of project context

Code Graph

The code-aware graph flow introduced in v0.18 makes graph exploration more useful for implementation work:

• Toggle code nodes separately from project knowledge nodes
• Inspect code-linked context without leaving the graph
• Explore relationships between symbols, files, and knowledge references
• Use it as a bridge between docs/tasks and real implementation entry points

Dashboard

The dashboard provides an overview of your project:

Kanban Board

Drag-and-drop task management with columns:

Actions:

• Drag tasks between columns to change status
• Click task to view/edit details
• Create new tasks with + button

Spec Links: Tasks linked to specs show a clickable spec badge on the card.

Task Details

Click any task to open the detail panel:

• View/edit title and description
• Check/uncheck acceptance criteria
• Update status and priority
• Assign to team members
• View implementation plan and notes
• See time tracking history

Rich Text Editor

Task descriptions and documentation use a BlockNote-based rich text editor:

• Formatting: Bold, italic, strikethrough, underline
• Lists: Bullet lists, numbered lists, checklists
• Code: Inline code and fenced code blocks with syntax highlighting
• Mentions: Type @task- or @doc/ for auto-complete suggestions
• Headings: Multiple heading levels for structure

The editor seamlessly converts to/from markdown for CLI compatibility.

Document Browser

Tree view of all documentation:

docs/
├── patterns/
│ ├── auth.md
│ └── caching.md
├── architecture/
│ └── overview.md
└── guides/
└── getting-started.md

Features:

• Click folder to expand/collapse
• Click document to view content
• Markdown preview with syntax highlighting
• Reference badges (@task, @doc) are clickable
• Specs filter: Filter to show only spec documents
• Spec badges: Specs show SPEC badge and status (Draft/Approved/Implemented)
• AC Progress: Spec documents show acceptance criteria completion bar
• Linked Tasks: Expand to see all tasks linked to a spec

Global Search

Press Cmd+K (Mac) or Ctrl+K (Windows) to open search.

Search across:

• Task titles and descriptions
• Document titles and content
• Memory entries and extracted knowledge
• Acceptance criteria

Dark Mode

Automatically follows system preference. Toggle manually in the UI.

Keyboard Shortcuts

Real-time Sync

Changes sync in real-time between:

• Multiple browser tabs
• CLI and Web UI
• Team members (same network)

When you run knowns task edit in CLI, the Web UI updates instantly.

When code watching is enabled, code-aware views can also stay fresh without rerunning a full manual indexing flow.

Server-Sent Events (SSE)

Knowns uses SSE for real-time updates, providing:

• Reliable one-way data streaming from server
• Automatic reconnection after network interruptions
• Better compatibility than WebSocket across proxies/firewalls

Auto-Reconnection

The Web UI automatically reconnects when:

• Your computer wakes from sleep
• Network connection is restored
• Server restarts

No manual refresh required - updates resume seamlessly.

Reference Badges

Task and doc references render as clickable badges:

Click any badge to navigate to that item.

URL Routing

Direct links to specific views:

Architecture

Browser ←→ Knowns local server (Go) ←→ File System (.knowns/)
↕
SSE (real-time sync)

The Web UI connects to the local Knowns server, which reads and writes your .knowns/ project data. All data stays on your machine.

Real-time updates use Server-Sent Events (SSE) for reliable, one-way data streaming with automatic reconnection.

Tunnel (Remote Access)

Expose your local Web UI to the internet using a Cloudflare Quick Tunnel. This is useful for accessing Knowns from a phone, tablet, or remote machine without port forwarding.

Requires cloudflared to be installed.

# Start browser with tunnel
knowns browser --tunnel

# Check the public tunnel URL
knowns tunnel status

# Stop the tunnel
knowns tunnel stop

The tunnel creates a temporary public URL (e.g., https://random-name.trycloudflare.com) that routes to your local server. No Cloudflare account required for quick tunnels.

Troubleshooting

Port in use

knowns browser --port 3002

Browser doesn't open

knowns browser --no-open
# Then manually open http://localhost:6420

Changes not syncing

1. Check if server is running in terminal
2. Refresh the browser
3. Check browser console for SSE connection errors