https://github.com/ackness/task-notes
https://github.com/ackness/task-notes
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/ackness/task-notes
- Owner: ackness
- Created: 2026-02-12T12:12:57.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-02-12T12:23:18.000Z (4 months ago)
- Last Synced: 2026-02-17T04:40:24.706Z (4 months ago)
- Language: Python
- Size: 17.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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 [--json]
task next [--json]
task new [--json]
task add [--parent ] [--json]
task edit --path [--json]
task edit -i [--json]
task del --path [--json]
task rm [--json]
task check --path [--json]
task uncheck --path [--json]
task toggle --path [--json]
task version [--json]
```
## Data Directory and Safety
- Default tasks directory: `~/.task-notes`
- You can override with `--tasks-dir `
- 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 -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/*
```