Configuration

Configure Knowns CLI for your project

4 min read

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
 
# Interactive mode - select type, variant, and files
knowns agents
 
# Quick sync with full embedded guidelines (~26KB)
knowns agents sync
 
# Sync with minimal instruction only (~1KB)
knowns agents sync --minimal
 
# Sync all files with MCP guidelines
knowns agents sync --type mcp --all

Supported files:

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

Template variants:

general (default): Full guidelines embedded in file
instruction (--minimal): Minimal - tells AI to call knowns agents guideline

Environment Variables

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

Defaults

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