semvec/pypi-packages huggingface dataset:
task-notes 0.1.1
LLM-friendly Markdown task notes CLI
Requires Python: >=3.13
Keywords: agent, cli, llm, markdown, tasks

# task-notes

[PyPI](https://pypi.org/project/task-notes/) | [GitHub](https://github.com/ackness/task-notes) | [中文文档](https://github.com/ackness/task-notes/blob/main/docs/README.zh-CN.md)

`task-notes` is an LLM/agent-friendly task CLI that stores project plans in Markdown checklists.

It supports nested task trees, selector-based operations (`1`, `1.2`, `2.1.3`), rich terminal output, and machine-safe JSON mode.

## Install

From PyPI:

```bash
pip install task-notes
```

With uvx (no global install):

```bash
uvx --from task-notes task --help
```

Install as a global tool with uv:

```bash
uv tool install task-notes
task --help
```

## Quick Start

```bash
task new app-redesign "Clarify scope" "Implement features" "Ship"
task add app-redesign --parent 2 "Implement ls/show output"
task show app-redesign
task next app-redesign
task check app-redesign --path 1
task edit app-redesign --path 2.1 "Implement ls/show/tree output"
```

## Commands

```bash
task ls [--json]
task show <project> [--json]
task next <project> [--json]
task new <project> <content...> [--json]
task add <project> [--parent <selector>] <content...> [--json]
task edit <project> --path <selector> <content> [--json]
task edit <project> -i [--json]
task del <project> --path <selector> [--json]
task rm <project> [--json]
task check <project> --path <selector> [--json]
task uncheck <project> --path <selector> [--json]
task toggle <project> --path <selector> [--json]
task version [--json]
```

## Data Directory and Safety

- Default tasks directory: `~/.task-notes`
- You can override with `--tasks-dir <path>`
- Non-default directories are blocked by default
- To allow a non-default directory, explicitly add:

```bash
--unsafe-external-dir
```

Example:

```bash
task --unsafe-external-dir --tasks-dir ./tasks ls
```

## Interactive Edit

```bash
task edit <project> -i
```

Keys:

- `Up/Down` or `j/k`: move cursor
- `Space`: select target task
- `Enter`: confirm selection
- `q` or `Esc`: cancel

## JSON Output (Recommended for Tools/LLMs)

```bash
task show app-redesign --json
```

In automation, prefer `--json` to avoid parsing terminal formatting.

## Development

Run tests:

```bash
uv run python -m unittest discover -s tests -p 'test_*.py' -v
```

Build and check package:

```bash
uv build
uvx twine check dist/*
```