KnownsKnowns/Docs

Configuration

Configure Knowns CLI for your project

Configuration

Knowns stores project configuration in .knowns/config.json.

This file describes what the project wants Knowns to manage locally, including platform integrations, semantic search settings, and generated artifact behavior.

Example

JSON
{
  "name": "my-project",
  "settings": {
    "gitTrackingMode": "git-tracked",
    "gitTracking": {
      "tasks": true,
      "docs": true,
      "templates": true,
      "memories": false
    },
    "semanticSearch": {
      "enabled": true,
      "model": "multilingual-e5-small",
      "provider": "local",
      "dimensions": 384
    },
    "platforms": [
      "claude-code",
      "opencode",
      "codex",
      "kiro",
      "antigravity",
      "cursor",
      "gemini",
      "copilot",
      "agents"
    ],
    "lsp": {
      "enabled": true
    }
  }
}

Important Settings

name

The project name shown in Knowns surfaces.

settings.gitTrackingMode

Controls how Knowns manages Git-related generated content.

ValueBehavior
git-trackedKeep .knowns/ content tracked in Git
git-ignoredKeep config/docs/templates tracked while leaving some local data out of Git
noneDo not let Knowns manage .gitignore

settings.gitTracking

Per-section git tracking toggles. Controls which .knowns/ subdirectories are included or excluded in .gitignore.

FieldDefaultDescription
taskstrueTrack task markdown files
docstrueTrack documentation files
templatestrueTrack code generation templates
memoriesfalseTrack AI memory entries

Set via CLI:

bash
knowns config set gitTracking.tasks true
knowns config set gitTracking.memories false

Changing these toggles automatically regenerates .gitignore.

settings.semanticSearch

Controls local semantic search.

FieldDescription
enabledEnable/disable semantic search
modelModel ID (e.g., multilingual-e5-small)
provider"local" or "ollama"
dimensionsEmbedding dimensions

settings.lsp

Controls LSP-based code intelligence.

FieldDescription
enabledWhether LSP servers are started for code navigation
bash
knowns config set lsp true             # Enable LSP globally
knowns config set lsp.go true          # Enable LSP for Go

settings.platforms

Declares which platform integrations Knowns should manage.

Supported values: claude-code, opencode, codex, kiro, antigravity, cursor, gemini, copilot, agents.

This setting affects what knowns setup, knowns sync, and knowns update create or refresh: instruction files, skills, MCP config, runtime hooks, platform-specific config files.

settings.enableChatUI

Controls whether the browser UI exposes the chat-oriented experience.

settings.autoSyncOnUpdate

Controls whether generated artifacts should be refreshed after upgrading the CLI.

Project Structure

After knowns init, your project contains:

Markdown
.knowns/
├── config.json # Project configuration
├── tasks/ # Task markdown files
│ ├── task-1 - First Task.md
│ └── task-2 - Second Task.md
└── docs/ # Documentation
├── patterns/
├── architecture/
└── guides/

Task Files

Each task is a markdown file with frontmatter:

Markdown
---
id: "42"
title: "Add authentication"
status: "in-progress"
priority: "high"
assignee: "@john"
labels: ["feature", "auth"]
createdAt: "2025-01-15T10:00:00Z"
updatedAt: "2025-01-15T14:30:00Z"
---


## Description

Implement JWT authentication...

## Acceptance Criteria

- [x] User can login
- [ ] JWT token returned

## Implementation Plan

1. Research patterns
2. Implement

## Implementation Notes

Completed login endpoint.

Document Files

Each document is a markdown file with frontmatter:

Markdown
---
title: "Auth Pattern"
description: "JWT authentication pattern"
tags: ["patterns", "security"]
createdAt: "2025-01-10T09:00:00Z"
updatedAt: "2025-01-12T16:00:00Z"
---


# Auth Pattern

This document describes our authentication pattern...

Git Tracking Modes

Choose during knowns init:

ModeDescriptionUse Case
git-trackedTrack all .knowns/ files in git (default)Teams sharing tasks/docs
git-ignoredTrack only docs, ignore tasks/configPersonal use without task noise
noneNo gitignore changes, user manages manuallyCustom setups

Granular toggles (settings.gitTracking) act as overrides within the selected mode. Existing git-tracked, git-ignored, and none modes still work — the per-section toggles provide finer control.

Configuration Commands

bash
# Interactive feature toggle UI
knowns config toggle

# Get a config value
knowns config get defaultAssignee --plain

# Set a config value
knowns config set defaultAssignee "@john"

# Set feature toggles
knowns config set embedding true
knowns config set lsp true
knowns config set enableChatUI true

# List all config
knowns config list

AI Platform Setup

AI integration files are generated via knowns setup, not during knowns init:

bash
knowns setup              # Interactive platform selector
knowns setup claude       # Claude Code: CLAUDE.md, .mcp.json, skills, hooks
knowns setup opencode     # OpenCode: OPENCODE.md, opencode.json, skills, hooks
knowns setup kiro         # Kiro: .kiro steering/settings, skills, hooks
knowns setup copilot      # GitHub Copilot: .github/copilot-instructions.md
knowns setup all          # All supported platforms

Managed artifacts per platform:

PlatformSkillsMCP/configRuntime hooks
Claude Code.claude/skills.mcp.jsonyes
OpenCode.agents/skillsopencode.jsonplugin/runtime
Codex.agents/skills.codex/config.tomlhooks
Kiro.kiro/skills.kiro/settings/mcp.jsonhooks
Antigravity.agents/skills~/.gemini/antigravity/mcp_config.jsonrules + global config
Cursornone.cursor/mcp.jsonno
Gemini CLInoneplatform-managed/globalno
GitHub Copilotinstruction onlynono
Generic agents.agents/skillsnono

Environment Variables

VariableDescription
KNOWNS_PORTDefault port for knowns browser

Machine-Level Runtime State

Global runtime state lives under ~/.knowns/:

  • Install metadata for script-managed installs
  • Runtime logs and process state
  • Shared runtime coordination data used by background indexing and update flows

This machine-level state is separate from each project's own .knowns/ folder.

Defaults

SettingDefault
Web UI port6420
Task prioritymedium
Task statustodo
bash
knowns init                            # First-time project setup
knowns setup                           # AI platform integrations
knowns sync                            # Re-apply config to current machine
knowns config set <key> <value>        # Toggle features
knowns config get <key>                # Read config value
knowns model list                      # Available embedding models
knowns model download multilingual-e5-small
knowns search --status-check
knowns search --reindex
PreviousModel ManagementNextReference System