Install

brew install knowns-dev/tap/knowns

or: npm install -g knowns

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

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

verify the install

knowns --version

or run without a global install

npx knowns init

What You Can Build With Knowns

---

Installation

Shell installer (macOS/Linux)

```bash curl -fsSL 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 ```

If semantic search reports a missing local model, run knowns search --setup or download one explicitly with knowns model download <model-id>, then rebuild with knowns search --reindex.

Global install - auto-downloads platform-specific binary

npm install -g knowns

Or run without installing

npx knowns ```

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

Use the method that matches how you installed Knowns:

```bash

Shell installer (macOS/Linux)

curl -fsSL https://knowns.sh/script/uninstall | sh

Go install

rm -f "$(go env GOPATH)/bin/knowns"

PowerShell installer (Windows)

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

If you installed runtime memory adapters, remove them before uninstalling the CLI:

Uninstall removes CLI binaries and PATH entries added by the installer. It leaves project .knowns/ folders, tasks, docs, memories, and AI integration files untouched. Delete .knowns/ only if you intentionally want to discard project context.

---

AI setup

knowns setup agents # lightweight repo-local agent shims only knowns setup codex --global # user-level Codex MCP/skills/hooks knowns setup --global # interactive user-level AI integration setup knowns setup # interactive project integration setup knowns sync ```

---

Quick Start

```bash

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.

---

Example Session

Claude Code example:

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)"

Quick Reference

```bash

Use the MCP code tool for symbols, definitions, references, diagnostics, and edits

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.

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

MCP Integration

Full Model Context Protocol server. Claude Code, Codex, Cursor, OpenCode, and other MCP-compatible assistants get native access to tasks, docs, memory, search, and validation - no copy-pasting required.

AI Integrations

Knowns does not replace your AI assistant. It gives the assistants you already use one shared project context layer: tasks, docs, specs, memory, decisions, search, validation, and code intelligence through MCP and synced skills.

For normal personal setup, use knowns setup <target> --global. Use project-level setup only when you intentionally want config files committed or scoped to one repository.

See Platforms for the full mapping.

---

Agent Skills Workflow

When using Knowns with an agent runtime such as Claude Code or Codex, skills provide a guided workflow:

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

Tiny change:
/kn-init -> /kn-research -> /kn-plan -> /kn-implement -> /kn-review -> /kn-commit

Feature / approved spec:
/kn-init -> /kn-research -> /kn-spec -> /kn-flow -> /kn-commit