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 ```

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.

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

```bash

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 ```

---

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

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, Cursor, and other MCP-compatible assistants get native access to tasks, docs, memory, search, and validation - no copy-pasting required.

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