# Web UI

Local interface for tasks, docs, memories, code graph, workspace switching, and built-in AI Chat

# [Web UI Guide](https://knowns.sh/docs/web-ui#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](https://knowns.sh/docs/web-ui#quick-start)

```
knowns browser --open
```

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

### [Options](https://knowns.sh/docs/web-ui#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](https://knowns.sh/docs/web-ui#v018-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](https://knowns.sh/docs/web-ui#features)

### [AI Chat](https://knowns.sh/docs/web-ui#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](https://knowns.sh/docs/web-ui#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](https://knowns.sh/docs/web-ui#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](https://knowns.sh/docs/web-ui#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](https://knowns.sh/docs/web-ui#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](https://knowns.sh/docs/web-ui#dashboard)

The dashboard provides an overview of your project:

| Widget | Description |
| --- | --- |
| **Tasks Overview** | Completion progress across all tasks |
| **Documentation Stats** | Total docs, recently updated |
| **SDD Coverage** | Tasks linked to specs percentage |
| **Time Tracking** | Today/week/total time summary |
| **Recent Activity** | Latest changes across tasks and docs |
| **Recent Tasks** | Quick access to recently updated tasks |
| **Spec Progress** | Cards showing spec completion status |

### [Kanban Board](https://knowns.sh/docs/web-ui#kanban-board)

Drag-and-drop task management with columns:

| Column | Status |
| --- | --- |
| To Do | `todo` |
| In Progress | `in-progress` |
| In Review | `in-review` |
| Blocked | `blocked` |
| Done | `done` |

**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](https://knowns.sh/docs/web-ui#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](https://knowns.sh/docs/web-ui#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](https://knowns.sh/docs/web-ui#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](https://knowns.sh/docs/web-ui#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](https://knowns.sh/docs/web-ui#dark-mode)

Automatically follows system preference. Toggle manually in the UI.

## [Keyboard Shortcuts](https://knowns.sh/docs/web-ui#keyboard-shortcuts)

| Shortcut | Action |
| --- | --- |
| `Cmd/Ctrl + K` | Open search |
| `Escape` | Close modal/panel |

## [Real-time Sync](https://knowns.sh/docs/web-ui#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)](https://knowns.sh/docs/web-ui#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](https://knowns.sh/docs/web-ui#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](https://knowns.sh/docs/web-ui#reference-badges)

Task and doc references render as clickable badges:

| Type | Appearance |
| --- | --- |
| `@task-pdyd2e` | Green badge with task title and status dot |
| `@doc/patterns/auth` | Blue badge with document title |

Click any badge to navigate to that item.

## [URL Routing](https://knowns.sh/docs/web-ui#url-routing)

Direct links to specific views:

| URL | View |
| --- | --- |
| `/#/kanban` | Kanban board |
| `/#/kanban/pdyd2e` | Kanban with task open |
| `/#/docs` | Document browser |
| `/#/docs/patterns/auth.md` | Specific document |

## [Architecture](https://knowns.sh/docs/web-ui#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)](https://knowns.sh/docs/web-ui#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`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) 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](https://knowns.sh/docs/web-ui#troubleshooting)

### [Port in use](https://knowns.sh/docs/web-ui#port-in-use)

```
knowns browser --port 3002
```

### [Browser doesn't open](https://knowns.sh/docs/web-ui#browser-doesnt-open)

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

### [Changes not syncing](https://knowns.sh/docs/web-ui#changes-not-syncing)

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