Configuration

Customize Knowns behavior with configuration options.

Project Configuration

Located at .knowns/config.json:

{
  "project": "my-project",
  "version": "1.0.0",
  "defaultAssignee": "@me",
  "defaultPriority": "medium",
  "defaultLabels": ["docs"],
  "timeFormat": "24h",
  "gitTrackingMode": "git-tracked",
  "settings": {
    "semanticSearch": {
      "enabled": true,
      "model": "gte-small"
    }
  }
}

Options

Key	Type	Description
`project`	string	Project name
`version`	string	Config version
`defaultAssignee`	string	Default assignee for new tasks
`defaultPriority`	string	Default priority (`low`, `medium`, `high`)
`defaultLabels`	string[]	Default labels for new tasks
`timeFormat`	string	Time format (`12h` or `24h`)
`gitTrackingMode`	string	`git-tracked` or `git-ignored`
`settings.semanticSearch.enabled`	boolean	Enable semantic search
`settings.semanticSearch.model`	string	Model ID (e.g., `gte-small`)

Project Structure

After knowns init, your project contains:

.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:

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

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

The .knowns/ folder is designed to be committed to git:

git add .knowns/
git commit -m "Add project knowledge base"

.gitignore

You may want to ignore certain files:

# Ignore time tracking state (optional)
.knowns/.timer

Git Tracking Modes

Choose during knowns init:

Mode	Description	Use Case
`git-tracked`	Track all `.knowns/` files in git (default)	Teams sharing tasks/docs
`git-ignored`	Track only docs, ignore tasks/config	Personal use without task noise

Git-Tracked Mode (default)

Commit the entire .knowns/ folder for full history and sharing.

Git-Ignored Mode

During init Knowns auto-adds:

# knowns (ignore all except docs)
.knowns/*
!.knowns/docs/
!.knowns/docs/**

Docs stay tracked, tasks/config stay local.

Configuration Commands

Manage project configuration via CLI:

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

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

# List all config
knowns config list

AI Agent Guidelines

Knowns provides on-demand guidelines and instruction file sync:

# Output guidelines to stdout (AI agents call this at session start)
knowns agents guideline

# Legacy-compatible sync
knowns agents --sync
knowns agents --sync --force

# Current sync command
knowns sync
knowns sync --skills
knowns sync --instructions --platform claude

Supported files:

CLAUDE.md - For Claude Code (default)
OPENCODE.md - For OpenCode
AGENTS.md - For Agent SDK (default)
GEMINI.md - For Google Gemini
.github/copilot-instructions.md - For GitHub Copilot

Environment Variables

Variable	Description
`KNOWNS_PORT`	Default port for `knowns browser`

Machine-Level Runtime State

The later v0.18 releases add more global runtime state under ~/.knowns/.

Typical examples include:

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

Setting	Default
Web UI port	3001
Task priority	medium
Task status	todo

Configuration

On this page