# Configuration

Configure Knowns CLI for your project

## 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 | 6420 |
| Task priority | medium |
| Task status | todo |

---

Knowns v0.20.5

A new version is available