<p align="center">
  <img src="./images/logo.png" alt="Knowns" width="120">
</p>

<h1 align="center">Knowns</h1>

<p align="center">
  <a href="https://go.dev/"><img src="https://img.shields.io/badge/go-%3E%3D1.24.2-00ADD8?style=flat-square&logo=go" alt="Go"></a>
  <a href="https://www.npmjs.com/package/knowns"><img src="https://img.shields.io/npm/v/knowns.svg?style=flat-square" alt="npm"></a>
  <a href="https://github.com/knowns-dev/knowns/actions/workflows/ci.yml"><img src="https://github.com/knowns-dev/knowns/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="#installation"><img src="https://img.shields.io/badge/platform-win%20%7C%20mac%20%7C%20linux-lightgrey?style=flat-square" alt="Platform"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/knowns-dev/knowns?style=flat-square" alt="License"></a>
</p>

<p align="center">
  <a href="https://knowns.sh">Homepage</a> |
  <a href="./README.vi.md">Tiếng Việt</a> |
  <a href="./docs/README.md">Documentation</a>
</p>

<p align="center">
  <strong>Give your AI coding assistant structured access to tasks, docs, specs, and decisions - so it stops guessing and starts building.</strong>
</p>

---

Every time you start a new AI coding session, you re-explain your architecture, paste docs, repeat conventions, and clarify past decisions. Your AI assistant is powerful - but it forgets everything between sessions.

**Knowns fixes that.** It gives AI assistants like Claude, Cursor, Copilot, and others structured, persistent access to your project's tasks, documentation, specs, acceptance criteria, and architectural decisions. Instead of prompting from scratch, your AI reads what it needs and picks up where you left off.

If you believe AI should truly understand software projects, consider giving **Knowns** a star.

<p align="center">
  <a href="https://player.cloudinary.com/embed/?cloud_name=dkxhoyenc&public_id=knowns-full-pipeline_uwhyk1">
    <img src="./images/knowns-full-pipeline-20s.gif" alt="Knowns full pipeline demo preview" width="100%">
  </a>
</p>
<p align="center">
  <em>Click the preview to watch the full pipeline demo video.</em>
</p>

## Table of Contents

- [Why Knowns?](#why-knowns)
- [Before & After](#before--after)
- [What is Knowns?](#what-is-knowns)
- [Who It's For](#who-its-for)
- [How It Works](#how-it-works)
- [Quick Start](#quick-start)
- [Core Capabilities](#core-capabilities)
- [What You Can Build](#what-you-can-build-with-knowns)
- [Claude Code Skills Workflow](#claude-code-skills-workflow)
- [Installation](#installation)
- [Documentation](#documentation)
- [Roadmap](#roadmap)
- [Development](#development)
- [Links](#links)

---

## Why Knowns?

AI coding assistants are stateless. Every session starts from zero.

That means you end up doing the same work over and over:

- **Re-explaining** your architecture and design patterns
- **Pasting** documentation into chat windows
- **Repeating** coding conventions and project rules
- **Clarifying** decisions that were already made last week
- **Rebuilding** context that took 20 minutes to set up

The AI doesn't lack intelligence. **It lacks access to what your project already knows.**

Knowns gives it that access.

---

## Before & After

| Without Knowns | With Knowns |
|---|---|
| "We use the repository pattern with..." _(paste 50 lines)_ | AI reads `@doc/patterns/repository` automatically |
| "Here's the task, the acceptance criteria are..." _(re-type everything)_ | AI reads the task, its ACs, linked specs, and related docs |
| "Remember, we decided last week to..." _(hope it sticks)_ | Decision is stored in project memory - AI recalls it every session |
| "The auth flow works like this..." _(explain for the 4th time)_ | AI follows `@doc/architecture/auth` and builds on it |
| "Are we done? Let me check the requirements again..." | AI checks acceptance criteria and validates completion itself |
| Session starts cold - 10 min of context-setting | Session starts warm - AI already knows the project |

---

## What is Knowns?

Knowns is a **local-first, self-hostable project context layer** for AI-native development.

It stores your project knowledge in structured, AI-readable files - and exposes them to AI assistants through CLI and [MCP (Model Context Protocol)](https://modelcontextprotocol.io/).

<p align="center">
  <img src="./images/how-knowns-works.png" alt="How Knowns Works" width="100%">
</p>

Concretely, Knowns manages:

- **Tasks** with acceptance criteria, implementation plans, and status tracking
- **Documentation** in nested markdown folders with cross-references
- **Specs** that define what "done" looks like for a feature
- **Memory** - project-level, session-level, and global knowledge that AI can recall
- **Templates** for code generation with Handlebars
- **References** like `@task-42` and `@doc/patterns/auth` that AI can follow and resolve
- **Code intelligence** - LSP-based symbols, definitions, references, diagnostics, and safe edits

Everything lives in a `.knowns/` directory in your repo. Plain files. Committable to Git. No cloud required.

---

## Who It's For

- **Solo developers** who pair with AI daily and want it to remember project context across sessions
- **Teams** building with AI assistants and tired of everyone re-explaining the same architecture
- **Open-source maintainers** who want contributors (human or AI) to onboard faster
- **Anyone** who uses Claude, Cursor, Copilot, Windsurf, or other AI coding tools and wants them to actually understand the project

---

## How It Works

Knowns sits alongside your existing tools. Your stack stays the same.

<p align="center">
  <img src="./images/architecture.png" alt="Knowns Architecture" width="100%">
</p>

1. **You structure your project knowledge** - tasks, docs, specs, decisions - using the Knowns CLI or Web UI
2. **AI reads it** - through MCP integration or CLI commands, your AI assistant accesses exactly the context it needs
3. **AI acts on it** - follows references, checks acceptance criteria, updates task status, and builds with full awareness
4. **Knowledge accumulates** - decisions, patterns, and conventions persist across sessions instead of disappearing

Your specs -> understood. Your tasks -> connected. Your docs -> usable. Your decisions -> remembered.

---

## Quick Start

```bash
# Install
brew install knowns-dev/tap/knowns
# or: npm install -g knowns
# or: curl -fsSL https://knowns.sh/script/install | sh
# or on Windows PowerShell:
# irm https://knowns.sh/script/install.ps1 | iex

# verify the install
knowns --version

# Initialize in your project
cd your-project
knowns init
# Creates .knowns/ plus KNOWNS.md, CLAUDE.md, and AGENTS.md by default

# or run without a global install
npx knowns init

# Create your first task
knowns task create "Add user authentication" \
  -d "JWT-based auth with login and register endpoints" \
  --ac "User can register with email/password" \
  --ac "User can login and receive JWT token" \
  --ac "Protected routes reject unauthenticated requests"

# Add project documentation
knowns doc create "Auth Architecture" \
  -f "architecture" \
  -d "Authentication design decisions and patterns"

# Open the Web UI
knowns browser --open

# Update Knowns later
knowns update

# Connect to your AI assistant via MCP
# See: docs/en/guides/mcp-integration.md
```

Now when your AI reads the project, it sees structured tasks with acceptance criteria, linked documentation, and clear definitions of done - instead of guessing.

---

## Core Capabilities

### Task & Workflow Management

Create tasks with acceptance criteria, implementation plans, and status tracking. AI can read tasks, follow plans, check off ACs, and know exactly when work is complete.

```bash
knowns task create "Title" --ac "Criterion 1" --ac "Criterion 2"
knowns task edit <id> -s in-progress
knowns task edit <id> --check-ac 1
```

### Structured Documentation

Organize project knowledge in nested markdown folders. Cross-reference with `@doc/path` and `@task-id`. AI follows these references to load exactly the context it needs.

```bash
knowns doc create "API Design" -f "architecture"
knowns doc "architecture/api-design" --smart --plain
```

### Project Memory

Three-layer memory system - **project**, **session**, and **global** - so AI recalls decisions, patterns, and conventions without you repeating them.

```bash
knowns memory add "We use repository pattern for data access" --category decision
knowns memory list --plain
```

### Semantic Search

Search by meaning, not just keywords. Runs locally with ONNX models - fully offline, no API keys needed.

```bash
knowns search "how does authentication work" --plain
```

### MCP Integration

Full [Model Context Protocol](https://modelcontextprotocol.io/) server. Claude, Cursor, and other MCP-compatible assistants get native access to tasks, docs, memory, search, and validation - no copy-pasting required.

### Code Intelligence

LSP-based code intelligence for supported languages. List symbols, jump to definitions, find references, inspect diagnostics, and make safe symbol-aware edits through MCP.

```bash
knowns lsp list
knowns lsp install <language>
```

### Templates & Code Generation

Handlebars-based templates for scaffolding. Define patterns once, generate consistently.

```bash
knowns template list
knowns template run <name> --name "UserService"
```

### AI Agent Workspaces

Multi-phase agent orchestration with git worktree isolation, live terminal streaming, and automatic phase progression (research -> plan -> implement -> review).

### Web UI

Kanban board, document browser, knowledge graph visualization, and mermaid diagram support - all in a local browser UI.

```bash
knowns browser --open
```

---

## What You Can Build With Knowns

| Capability | What It Does |
|---|---|
| **Task Management** | Tasks with acceptance criteria, plans, status, and time tracking |
| **Documentation** | Nested markdown folders with cross-references and mermaid support |
| **Semantic Search** | Meaning-based search with local AI models (fully offline) |
| **Time Tracking** | Built-in timers and reports per task |
| **Context Linking** | `@task-42` and `@doc/patterns/auth` references AI can resolve |
| **Validation** | Detect broken references and incomplete tasks with `knowns validate` |
| **Template System** | Code generation with Handlebars (`.hbs`) templates |
| **Import System** | Import docs and templates from git, npm, or local sources |
| **Memory System** | Project / session / global memory for persistent AI recall |
| **MCP Server** | Native AI assistant integration with full tool access |
| **AI Workspaces** | Multi-phase agent orchestration with worktree isolation |
| **Code Intelligence** | LSP-based symbols, definitions, references, diagnostics, and safe edits |
| **Web UI** | Kanban board, doc browser, knowledge graph, mermaid diagrams |

---

## Claude Code Skills Workflow

When using Claude Code with Knowns, skills (slash commands) provide a guided workflow:

<p align="center">
  <img src="./images/workflow.png" alt="Knowns AI Workflow" width="100%">
</p>

```
/kn-init      -> Read project docs, understand context
/kn-plan      -> Take task, gather context, create plan (wait for approval)
/kn-implement -> Follow plan, check ACs, track progress
/kn-commit    -> Commit with conventional format
```

### Example Session

```
You: /kn-init
Claude: [Reads README, ARCHITECTURE, checks task backlog]
        "Project uses NestJS with CQRS pattern. 3 tasks in-progress..."

You: /kn-plan 42
Claude: [Takes task, reads refs, searches docs]
        "Task #42: Add user authentication

         ## Implementation Plan
         1. Review @doc/patterns/auth
         2. Create AuthModule with JWT strategy
         3. Add login/register endpoints
         4. Write unit tests

         Approve this plan?"

You: Yes

You: /kn-implement 42
Claude: [Follows plan, generates code, checks ACs]
        "✓ AC1: User can login - DONE
         ✓ AC2: JWT token returned - DONE
         ✓ AC3: Tests pass - DONE

         All acceptance criteria complete. Ready to commit?"

You: /kn-commit
Claude: [Creates conventional commit]
        "feat(auth): add JWT authentication

         - Add AuthModule with passport JWT strategy
         - Add login/register endpoints
         - Add unit tests (94% coverage)"
```

### All Skills

| Skill | Description |
|---|---|
| `/kn-init` | Initialize session - read docs, load memory, understand project |
| `/kn-plan <id>` | Take task, gather context, create implementation plan |
| `/kn-implement <id>` | Execute plan, track progress, check acceptance criteria |
| `/kn-research` | Search codebase, find patterns, explore before coding |
| `/kn-commit` | Create conventional commit with verification |
| `/kn-spec` | Create specification document for features (SDD) |
| `/kn-go <spec>` | Full pipeline from approved spec (no review gates) |
| `/kn-verify` | Run SDD verification and coverage report |
| `/kn-review` | Multi-perspective code review (P1/P2/P3 severity) |
| `/kn-doc` | Create or update documentation |
| `/kn-extract` | Extract reusable patterns into docs, templates, and memory |
| `/kn-template` | List, run, or create code templates |
| `/kn-debug` | Debug errors and failures with memory-backed triage |

---

## Installation

### Homebrew (macOS/Linux)

```bash
brew install knowns-dev/tap/knowns
```

### Shell installer (macOS/Linux)

```bash
curl -fsSL https://knowns.sh/script/install | sh

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

# Install a specific version
curl -fsSL https://knowns.sh/script/install | KNOWNS_VERSION=0.18.0 sh
```

### PowerShell installer (Windows)

```powershell
irm https://knowns.sh/script/install.ps1 | iex

# Install a specific version
$env:KNOWNS_VERSION = "0.18.0"; irm https://knowns.sh/script/install.ps1 | iex
```

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

### npm

```bash
# Global install - auto-downloads platform-specific binary
npm install -g knowns

# Or run without installing
npx knowns
```

### From source (Go 1.24.2+)

```bash
go install github.com/howznguyen/knowns/cmd/knowns@latest

# Or clone and build
git clone https://github.com/knowns-dev/knowns.git
cd knowns
make build        # Output: bin/knowns
make install      # Install to GOPATH/bin
```

### Uninstall

```bash
# macOS/Linux
curl -fsSL https://knowns.sh/script/uninstall | sh

# Windows
irm https://knowns.sh/script/uninstall.ps1 | iex
```

The uninstall scripts only remove installed CLI binaries and PATH entries added by the installer. They leave project `.knowns/` folders untouched.

---

## Quick Reference

```bash
# Tasks
knowns task create "Title" -d "Description" --ac "Criterion"
knowns task list --plain
knowns task <id> --plain
knowns task edit <id> -s in-progress -a @me
knowns task edit <id> --check-ac 1

# Documentation
knowns doc create "Title" -d "Description" -f "folder"
knowns doc "doc-name" --plain
knowns doc "doc-name" --smart --plain
knowns doc "doc-name" --section "2" --plain

# Templates
knowns template list
knowns template run <name> --name "X"
knowns template create <name>

# Imports
knowns import add <name> <source>
knowns import sync
knowns import list

# Time, Search & Validate
knowns time start <id> && knowns time stop
knowns search "query" --plain
knowns validate

# Code intelligence
knowns lsp list
knowns lsp install <language>
# Use the MCP code tool for symbols, definitions, references, diagnostics, and edits

# AI setup
knowns setup agents        # KNOWNS.md + AGENTS.md only
knowns setup codex --global # user-level Codex MCP/skills/hooks
knowns setup               # full interactive project integration setup
knowns sync
```

---

## Documentation

| Guide | Description |
|---|---|
| [User Guide](./docs/en/guides/user-guide.md) | Getting started and daily usage |
| [Command Reference](./docs/en/reference/commands.md) | Core CLI commands with examples |
| [Workflow Guide](./docs/en/guides/workflow.md) | Recommended human + AI workflow |
| [MCP Integration](./docs/en/guides/mcp-integration.md) | MCP setup and supported platforms |
| [Reference System](./docs/en/reference/reference-system.md) | How `@doc/` and `@task-` linking works |
| [Semantic Search](./docs/en/reference/semantic-search.md) | Setup and usage of semantic search |
| [Templates](./docs/en/integrations/templates.md) | Code generation and template workflows |
| [Web UI](./docs/en/guides/web-ui.md) | Board, docs, graph, and chat UI |
| [Configuration](./docs/en/reference/configuration.md) | Project config and platform IDs |
| [Skills](./docs/en/integrations/skills.md) | Skill paths and regeneration |
| [Developer Guide](./docs/en/contributing/developer-guide.md) | Notes for contributors |
| [Platforms](./docs/en/integrations/platforms.md) | Platform integration mapping |

---

## Roadmap

### AI Agent Workspaces ✅ (Active)

Multi-phase agent orchestration - assign tasks to AI agents with git worktree isolation, live terminal streaming, and automatic phase progression (research -> plan -> implement -> review).

### Self-Hosted Team Sync 🚧 (Planned)

Optional self-hosted sync server for shared visibility without giving up local-first workflows.

- **Real-time visibility** - See who is working on what
- **Shared knowledge** - Sync tasks and documentation across the team
- **Full data control** - Self-hosted, no cloud dependency

---

## Development

Requires **Go 1.24.2+** and optionally **Node.js + pnpm** for UI development.

```bash
make build              # Build binary -> bin/knowns
make dev                # Build with race detector
make test               # Run unit tests
make test-e2e           # Run CLI + MCP E2E tests
make test-e2e-semantic  # E2E tests including semantic search
make lint               # Run golangci-lint
make cross-compile      # Build for all 6 platforms
make ui                 # Rebuild embedded Web UI (requires pnpm)
```

### Project Structure

```
cmd/knowns/          # CLI entry point
internal/
  cli/               # Cobra commands
  models/            # Domain models
  storage/           # File-based storage (.knowns/)
  server/            # HTTP server, SSE, WebSocket
    routes/          # REST API handlers
    workspace/       # Agent orchestrator, process manager, worktree
  mcp/               # MCP server (stdio)
  search/            # Semantic search (ONNX)
ui/                  # Embedded React UI (built assets)
tests/               # E2E tests
```

---

## Links

- [npm](https://www.npmjs.com/package/knowns)
- [GitHub](https://github.com/knowns-dev/knowns)
- [Discord](https://discord.knowns.dev)
- [Changelog](./CHANGELOG.md)

For design principles and long-term direction, see [Philosophy](./PHILOSOPHY.md).

For technical details, see [Architecture](./ARCHITECTURE.md) and [Contributing](./CONTRIBUTING.md).

---

## Star History

<a href="https://www.star-history.com/?repos=knowns-dev%2Fknowns&type=date&legend=top-left">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=knowns-dev/knowns&type=date&theme=dark&legend=top-left" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=knowns-dev/knowns&type=date&legend=top-left" />
   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=knowns-dev/knowns&type=date&legend=top-left" />
 </picture>
</a>

---

<p align="center">
  <strong>What your AI should have knowns.</strong><br>
  Built for dev teams who pair with AI.
</p>
