Metadata-Version: 2.4
Name: kaydet
Version: 0.38.1
Summary: Simple and terminal-based personal diary app for your shell.
Author: Mirat Can Bayrak
Project-URL: Homepage, https://github.com/miratcan/kaydet
Project-URL: Repository, https://github.com/miratcan/kaydet
Project-URL: Issues, https://github.com/miratcan/kaydet/issues
Keywords: diary,terminal,cli
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Utilities
Classifier: Topic :: Database
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pre-commit==4.0.1; extra == "dev"
Requires-Dist: ruff==0.6.1; extra == "dev"
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"
Requires-Dist: mcp>=0.9.0; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp>=0.9.0; extra == "mcp"
Dynamic: license-file

# Kaydet — Capture • Query • Remember

<div align="center">
  <img src="assets/logo.png" alt="Kaydet Logo" width="400">
  <br><br>
</div>

[![Tests](https://github.com/miratcan/kaydet/workflows/Tests/badge.svg)](https://github.com/miratcan/kaydet/actions)
[![Coverage](https://img.shields.io/badge/coverage-83%25-brightgreen.svg)](https://github.com/miratcan/kaydet/actions/workflows/test.yml)
[![License](https://img.shields.io/github/license/miratcan/kaydet.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Maintained](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/miratcan/kaydet/graphs/commit-activity)
[![GitHub stars](https://img.shields.io/github/stars/miratcan/kaydet?style=social)](https://github.com/miratcan/kaydet/stargazers)
[![Last commit](https://img.shields.io/github/last-commit/miratcan/kaydet)](https://github.com/miratcan/kaydet/commits/master)

> Your queryable personal database. Plain text storage, SQLite search, zero friction.

Kaydet is not a diary you read—it's a database you query. Capture thoughts, track work, log life—all from your terminal, in plain text.

## Install

```bash
pip install git+https://github.com/miratcan/kaydet.git
```

Or with MCP support for AI integration:

```bash
pip install "git+https://github.com/miratcan/kaydet.git#egg=kaydet[mcp]"
```

> The `kaydet-mcp` command is always installed, but requires the `[mcp]` extra
> to run (otherwise it fails with an import error).

## Quick Start

```bash
# Capture a thought
kaydet "Fixed auth bug #work commit:abc123 time:2h status:done"

# Search by metadata
kaydet --filter "status:done"
kaydet --filter "time:>1"
kaydet --filter "commit:abc123"

# List all tags
kaydet --tags

# Open in editor
kaydet --editor

# Edit or delete by ID
kaydet --edit 42
kaydet --delete 42
```

## Why Kaydet?

**Zero Friction**
One command from your terminal. No app windows, no context switching, no loading screens.

**Plain Text Forever**
Daily `.txt` files you can grep, version with git, sync however you like. No proprietary formats, no lock-in.

**Queryable Database**
SQLite index with full-text search, metadata extraction, and numeric comparisons. Search `time:>2` to find long work sessions.

**AI-Ready**
Built-in MCP server exposes your archive to Claude Desktop. Ask your AI about your own life.

## Features

- **Todo management**: Built-in task tracking with `--todo` and `--done` commands
- **Structured metadata**: `key:value` syntax with numeric comparisons (`time:>2`, `status:done`)
- **Smart tagging**: Hashtags (`#work`) and metadata in one natural string
- **Edit/delete by ID**: Stable numeric identifiers for every entry
- **Plain text storage**: Human-readable `.txt` files, one per day
- **SQLite indexing**: Fast search across thousands of entries
- **Git-friendly**: Version your diary, sync across devices
- **MCP integration**: Connect to Claude Desktop and other AI tools with todo support

## Usage

### Basic Commands

```bash
# Add an entry
kaydet "Morning standup went well #work"

# Add with metadata
kaydet "Deep work session #focus time:3h intensity:high project:kaydet"

# Search
kaydet --filter "#work"
kaydet --filter "project:kaydet status:done"
kaydet --filter "time:>2"

# Todo Management
kaydet --todo "Write unit tests priority:high"
kaydet --done 42           # Mark todo as done
kaydet --todo              # List todos

# Utility
kaydet --tags              # List all tags with counts
kaydet --stats             # Show calendar and stats
kaydet --folder            # Open log directory
kaydet --doctor            # Rebuild index from text files
```

> Need a literal `#` in your note? Escape it as `\#` (e.g.,
> `kaydet "Budget was \#1"`).

### Entry Format

Entries are stored as plain text with this format:

```
14:25 [42]: Fixed auth bug commit:abc123 time:2h status:done #work #urgent
```

- Timestamp and unique ID
- Message
- Metadata (`key:value` pairs)
- Tags (hashtags)

### File Structure

```
~/Documents/Kaydet/          → Synced (storage)
├── 2025-10-26.txt
├── 2025-10-27.txt
├── 2025-10-28.txt
└── ...

~/.local/share/kaydet/       → Local only (index)
  └── index.db
```

### Metadata Queries

Kaydet parses `key:value` pairs and supports:

- **Exact match**: `status:done`, `project:kaydet`
- **Numeric comparison**: `time:>2`, `time:>=1.5`, `time:<5`
- **Ranges**: `time:1..3` (between 1 and 3 hours)
- **Duration parsing**: `2h` → `2.0`, `90m` → `1.5`, `2.5h` → `2.5`

### Configuration

Settings are in `~/.config/kaydet/config.ini`:

```ini
[SETTINGS]
DAY_FILE_PATTERN = %Y-%m-%d.txt
DAY_TITLE_PATTERN = %Y/%m/%d - %A
STORAGE_DIR = ~/Documents/Kaydet
EDITOR = nvim
REMIND_AFTER_HOURS = 4
COLOR_HEADER = bold cyan
COLOR_TAG = bold magenta
COLOR_DATE = green
COLOR_ID = yellow
```

If `STORAGE_DIR` is omitted, Kaydet picks a sensible default on first run:
- macOS / Windows → `~/Documents/Kaydet`
- Linux → `~/Kaydet`
Prefer hidden/XDG dirs? Change `STORAGE_DIR` (e.g., `~/.local/share/kaydet`) in
`config.ini` and rerun `kaydet --config`; the CLI offers to move files for you.

### Color Customization

You can customize the colors of various elements in the output by adding the following settings under the `[SETTINGS]` section in `config.ini`:

```ini
[SETTINGS]
# ... existing settings ...
COLOR_HEADER = bold cyan
COLOR_TAG = bold magenta
COLOR_DATE = green
COLOR_ID = yellow
```

- `COLOR_HEADER`: Color for date separators and section headers.
- `COLOR_TAG`: Color for tags (e.g., `#work`).
- `COLOR_DATE`: Color for timestamps in search results.
- `COLOR_ID`: Color for entry IDs and pending todo counts.

You can use any [Rich color string](https://rich.readthedocs.io/en/stable/style.html#color-names) (e.g., `red`, `bold green`, `rgb(255,100,0)`).

## AI Integration

Connect Kaydet to Claude Desktop via MCP:

```json
// claude_desktop_config.json
{
  "mcpServers": {
    "kaydet": {
      "command": "kaydet-mcp"
    }
  }
}
```

Then ask Claude:
- "What did I work on this week?"
- "How consistent was my fitness routine last month?"
- "Summarize my accomplishments from last sprint"

Your AI assistant with perfect memory of your own data.

### MCP Tools

- `suggest_kaydet_tags` – Suggest tags for assistants by reading `.kaydet.tags` in
  the current project or falling back to the directory name when no override is
  defined.



## Use Cases

**Work Logging**
```bash
kaydet "Shipped analytics feature #work commit:a3f89d pr:142 status:done time:4h"
kaydet "Investigating prod timeout #oncall status:wip time:1.5h"
```

**Time Tracking**
```bash
kaydet "Deep work on ETL pipeline #work time:3h focus:high"
kaydet --filter "time:>2"  # Find long sessions
```

**Personal Journaling**
```bash
kaydet "Morning run felt amazing #fitness time:30m distance:5k"
kaydet "Read Atomic Habits chapter 3 #reading"
```

**Expense Tracking**
```bash
kaydet "Lunch with client #expense amount:850 currency:TRY billable:yes"
kaydet --filter "billable:yes"  # Generate invoice data
```

## Development

```bash
git clone https://github.com/miratcan/kaydet.git
cd kaydet
pip install -e .
```

Run tests:
```bash
pip install -e .[dev]
pytest
ruff check src
```

## Cloud Sync & Mobile

Kaydet separates storage (plain text files) from index (SQLite database), making cloud sync simple and safe.

### How it works

```
~/Documents/Kaydet/        → Synced (Google Drive, iCloud, Dropbox)
  ├── 2025-01-15.txt
  ├── 2025-01-16.txt
  └── ...

~/.local/share/kaydet/     → Local only (not synced)
  └── index.db
```

**Why this works:**
- Plain text files are the single source of truth
- Each device builds its own search index
- No conflicts, no corruption
- Zero infrastructure cost

### Setup for cloud sync

1. **First run** — Kaydet will ask where to store entries:
   ```bash
   kaydet "First entry"

   # Choose your cloud folder:
   Path: ~/Google Drive/Kaydet
   ```

2. **Change location later** — Edit config and migrate:
   ```bash
   kaydet --config

   # Edit storage_dir in your editor
   # Kaydet will offer to move files automatically
   ```

3. **On other devices** — Install Kaydet, set same folder:
   ```bash
   kaydet "First entry on phone"
   Path: ~/Google Drive/Kaydet  # Same path
   ```

### Supported cloud providers

- **Google Drive** (recommended for Android)
- **iCloud Drive** (recommended for iOS/macOS)
- **Dropbox** (cross-platform)
- **Any folder sync** (Syncthing, Resilio, etc.)

**Note:** Index is always local. Each device maintains its own `index.db` for fast search.

## Contributing

Bug reports, feature ideas, and pull requests welcome. Open an issue or submit a PR.
See [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines and the full philosophy.

## License

MIT License. See [LICENSE](LICENSE) for details.

## Links

- [GitHub Repository](https://github.com/miratcan/kaydet)
- [Blog: Why plain text + SQLite beat every cloud note app](https://mirat.dev/articles/nine-years-of-kaydet/)
- [docs/AGENTS.md](docs/AGENTS.md) — agents must read this before interacting with the repo

---

<div align="center">

Built by [Mirat Can Bayrak](https://github.com/miratcan)

</div>
