Metadata-Version: 2.5
Name: taskterm
Version: 0.2.0
Summary: ターミナルで動くTODO・タスク管理アプリ
Project-URL: Homepage, https://github.com/yamato3010/taskterm
Project-URL: Repository, https://github.com/yamato3010/taskterm
Project-URL: Changelog, https://github.com/yamato3010/taskterm/blob/main/CHANGELOG.md
License-Expression: MIT
License-File: LICENSE
Keywords: calendar,task,terminal,todo,tui
Classifier: Environment :: Console
Classifier: Natural Language :: Japanese
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=8.2.5
Description-Content-Type: text/markdown

# taskterm

ターミナルで動くTODO・タスク管理アプリ。

## 使い方

```sh
# PyPI から入れて使う
pipx install taskterm
taskterm

# このリポジトリのソースから入れる場合
pipx install .

# 開発中はリポジトリの仮想環境から
./myenv/bin/taskterm
```

## キー操作

| キー | 動作 |
|---|---|
| `a` | タスクを追加 (期限の初期値はカレンダーで選んでいる日) |
| `e` / `Enter` | 選択中のタスクを編集 |
| `space` | 完了 / 未完了を切り替え (完了扱いのステータスに移す / 戻す) |
| `s` | ステータスを選び直す (一覧から `j` / `k` で選んで `Enter`。`Esc` で取消) |
| `p` | 優先度を 高 → 中 → 低 と切り替え |
| `f` | 絞り込み (ステータス・タグで一覧を絞る。`space` で選択、`Ctrl+S` で適用) |
| `m` | メモを全画面で開く (そこから編集・追記もできる) |
| `o` | リンクを開く (一覧から選んで `Enter`。そこで追加・編集もできる) |
| `c` | チェックリストを開く (項目の追加・完了。`space` で完了を切り替え) |
| `d` | 削除 (確認画面が出ます。`y` で削除、`n` / `Esc` で取消) |
| `u` | 直前の削除を元に戻す |
| `v` | 表示切替 (選択日のみ ⇄ 全件。次の起動でも同じ表示で始まります) |
| `w` | タブ切替 (未完了 ⇄ 完了。タブの右にも案内が出ています) |
| `t` | カレンダーを今日に戻す |
| `,` | 設定画面 (ステータス・タグの追加・編集、四半期表示の切替) |
| `?` | ヘルプ (全キーの一覧。`Esc` で閉じる) |
| `i` | このアプリについて (バージョン・保存先。`Esc` で閉じる) |
| `Tab` | TODOリストとカレンダーの間を移動 |
| `j` / `k` (`↑` `↓`) | リスト: カーソル移動 / カレンダー: 前週・翌週 |
| `h` / `l` | 前日・翌日 (どちらのパネルにいても動く。`←` `→` はカレンダーにいるときだけ) |
| `[` / `]` | 前月・翌月 |
| `q` | 終了 |

追加・編集フォームでは `Enter` で保存、`Esc` で取消。優先度の選択欄にいるときは `Enter` が選択に使われるので、`Ctrl+S` でも保存できます。タグ欄は `space` で選択・解除します (`j` / `k` でも動かせます)。メモは `Ctrl+O` で全画面エディタが、リンクは `Ctrl+L` で一覧が、チェックリストは `Ctrl+T` で一覧が開きます。

## 画面の見かた

- 一覧は**未完了**と**完了**の2つのタブに分かれています。`w` で切り替えます (タブのクリックでも切り替わります)。
- **未完了**タブには完了したタスクは出ません。日々見る一覧に完了が溜まらないようにするためです。
- **完了**タブには完了したタスクだけが、期限に関わらず**全件**、**完了日の新しい順**で出ます。2列目が「期限」ではなく「完了日」になり、完了タブでは `v` の表示切替は効きません (常に全件)。
- `s` のステータス選択では、今のステータスに `▸` が付き、選ぶとタスクが完了タブへ移るものには `(完了タブへ)` と出ます。
- **完了日**は `space` や `s` で**完了扱いのステータスに移した日**です。未完了に戻すと消え、次に完了したときの日付が入ります。完了扱いのまま別の完了ステータスに移した場合は最初に完了した日が残ります。
- 既定ではカレンダーで選んでいる日が期限のタスクだけを表示します。今日を選んでいるときは、**期限切れの未完了タスク**も一緒に出ます。
- **期限なし**のタスクは `v` の全件表示に含まれます (件数は右下の内訳に出ます)。
- カレンダーの印は `•` が未完了のタスクがある日、`·` はその日のタスクが全て完了している日です。
- タイトルの `✎` はメモがあるタスクです。中身は一覧の下の詳細欄に出ます。
- タイトルの `↗` はリンクがあるタスクです。`o` で開けます。
- タイトルの `2/5` はチェックリストの進み具合です (完了した項目数 / 全項目数)。`c` で開けます。
- 一覧の下の**詳細欄**に、選択中のタスクのステータス・期限・優先度・**タグ**が出ます。一覧のタグ列は幅に収まらない分を `…` で切っているので、複数のタグはここで読めます。
- 右下の内訳には、ステータスごとの件数が設定の並び順で出ます。
- **四半期**の欄は既定では出ません。`,` の設定画面で「四半期を表示」をオンにすると、カレンダーの下に今日が属する四半期・その期間・進捗バー・終了までの日数が出ます。年度の開始月も同じ画面で選べます (既定は4月始まり = 1Qが4〜6月)。カレンダーの選択日ではなく**今日**を基準にします。

## 絞り込み

`f` で絞り込み画面が開きます。**ステータス**と**タグ**をそれぞれ複数選べます。

| キー | 動作 |
|---|---|
| `space` | 選択 / 解除 |
| `j` / `k` (`↑` `↓`) | 項目を移動 |
| `Tab` | ステータス欄・タグ欄・ボタンを移動 |
| `Ctrl+S` | 適用して閉じる |
| `Ctrl+R` | 絞り込みを解除して閉じる |
| `Esc` | 変えずに閉じる |

- 「適用」「解除」は画面下のボタンでも押せます (`Tab` で移動して `Enter`、クリックでも)。
- どちらの欄も**何も選ばなければ、その項目では絞りません**。
- **タグを複数選ぶと「いずれかを含む」**タスクが出ます (仕事 + 至急 なら、どちらか一方でも付いていれば出ます)。ステータスとタグの両方を選んだ場合は、その両方に合うタスクだけが出ます。
- 絞り込みは一覧だけでなく**カレンダーの印**と右下の内訳にも効きます。ただし内訳の**ステータス別の件数**は分布を見るためのものなので、ステータスの絞り込みは掛けません (タグの絞り込みは掛かります)。
- 絞り込み中は、左パネルのタイトル (`TODO — 全件 / 進行中・仕事`) と右下の内訳に条件が出ます。
- **完了**タブではステータスの絞り込みは掛かりません (「未着手だけ」に絞ったまま完了タブに移ると必ず空になってしまうため)。タグの絞り込みは掛かります。
- 絞り込みは**アプリを閉じるとリセット**されます (`v` の表示切替と違い、設定には保存しません)。

## チェックリスト

1つのタスクを手順に分解したいときは、タスクに**チェックリスト**を付けられます。項目は**期限・ステータス・優先度を持ちません** (1件のタスクの中身なので、一覧の件数やカレンダーの印も増えません)。項目ごとに日付で管理したくなったら、独立したタスクとして追加してください。

- `c` で開きます。下の入力欄に書いて `Enter` で追加。続けて書けるよう入力欄に残るので、手順をまとめて並べられます。
- `space` (または `Enter`) で完了を切り替え、`e` で書き換え、`d` で削除、`J` / `K` で並べ替えます。
- 上部に進捗バーと「完了数 / 全項目数」が出ます。`Esc` で閉じると保存されます。
- 一覧では、タイトルの後ろに `2/5` の形で進み具合が出ます。詳細欄にも「チェック 2/5」として出ます。
- 追加・編集フォームからは `Ctrl+T` で開けます (フォームの保存で確定します)。

## メモ

メモは複数行で書けます。長さの制限はありません。**markdown** で書くと、全画面表示 (`m`) のときに装飾された見た目で読めます。

- 一覧の下の**詳細欄**に、選択中のタスクのメモが概要行の下に折り返して出ます。入りきらないときは**新しい末尾側**が残り、見出しが「詳細 (m でメモ全文)」に変わります (書き足していくほど最新の分が見えます)。
- `m` で**全画面表示**。`j` / `k` (`↑` `↓` `PgUp` `PgDn` `Home` `End`) でスクロールし、`Esc` で戻ります。
- 全画面表示から `e` で**編集**に切り替わります。書き終えたら `Esc` (`Ctrl+S` でも同じ) で閉じると保存されます。保存後は表示に戻るので、読み返してからもう一度直せます。
- 全画面表示から `a` で**追記**。今日の日付の見出し (`## 2026-08-24`) を末尾に足した状態でエディタが開くので、日付ごとに書き足していけます。同じ日に続けて追記したときは見出しを重ねません。見出しを足しただけで何も書かずに閉じた場合は保存されないので、空の見出しは残りません。
- 追加・編集フォームからは `Ctrl+O` (または「編集」ボタン) でエディタを開きます。フォームには1行目と行数だけが出ます。
- エディタでは `Enter` で改行できます。

### markdown の書きかた

全画面表示では次の記法が装飾されて出ます (詳細欄と一覧には書いたままの文字が出ます)。

- `#` から `######` の**見出し**は、段の深さごとに色を変えた太字になります。
- `**太字**` は黄色、`*斜体*` は斜体、`~~打ち消し~~` は打ち消し線、`` `コード` `` は色を変えて出ます。
- `- ` や `1. ` の**箇条書き**は記号を色分けして出ます (入れ子にもできます)。
- バッククォート3つで囲んだ**コードブロック**は、開きの後ろに言語名 (`python` など) を添えると色分けされます。
- `> ` の**引用**とコードブロックは、左に縦線が付きます。
- `|` で区切った**表**は罫線で枠を描きます。`---` の行は横線になります。
- `[文字](URL)` の**リンク**は下線付きで出て、クリックするとブラウザで開きます。
- markdown 本来の規則とは違い、**段落の中の改行はそのまま改行**になります (markdown を意識せず書いたメモが1行につながらないようにするため)。

## リンク

Teams のスレッドや Backlog のチケットなど、そのタスクの背景を辿るための参照先を、何のリンクかを示すタイトル付きで何件でも持てます。

- `o` で**リンク一覧**が開きます。`j` / `k` で選んで `Enter` (行をクリックでも可) を押すと、既定のブラウザで開きます。
- 一覧の中で `a` 追加 / `e` 編集 / `d` 削除 / `J` `K` 並べ替えができます。変更は `Esc` で閉じたときに保存されます。
- 追加・編集フォームからは `Ctrl+L` (または「編集」ボタン) で同じ一覧を開きます。フォームには1件目と件数だけが出ます。
- タイトルは省略できます。空のままだと一覧にURLをそのまま出します。
- URLはスキームを省いても構いません (`example.com/x` は `https://example.com/x` として開きます)。`msteams:` のようなアプリのスキームはそのまま使えます。

## ステータスとタグ

`,` キーの設定画面で、自分の使うステータスとタグを追加・編集できます。左がステータス、右がタグで、`Tab` で行き来します。

| キー | 動作 |
|---|---|
| `a` | 追加 (名前・色、ステータスは「完了扱い」も指定) |
| `e` / `Enter` | 編集 |
| `d` | 削除 |
| `J` / `K` | 並べ替え |
| `Ctrl+S` | 保存して閉じる |
| `Esc` | 保存せず閉じる |

- 色は端末のANSI 16色から選びます。
- **ステータスの先頭**が、新しいタスクの初期ステータスです。並べ替えで変えられます。
- **「完了扱い」**にしたステータスが `space` の完了先になり、一覧の取り消し線・カレンダーの印・完了件数もこれで判定します。完了扱いのステータスが1つも無いと `space` は効きません (その場合は画面に出ます)。未完了から完了扱いに移した日が**完了日**として記録され、完了タブの並び順に使われます。
- 「使用」列は、そのステータス・タグを使っているタスクの件数です。削除すると、そのステータスのタスクは先頭のステータスに移り、タグは各タスクから外れます。ステータスは最後の1つを消せません。
- 既定では 未着手 / 進行中 / 保留 / 完了 の4つが入っています。タグは空なので、使うものを自分で追加してください。

## データの保存先

| ファイル | 内容 |
|---|---|
| `~/.local/share/taskterm/tasks.json` | タスク (`XDG_DATA_HOME` があればそちら) |
| `~/.config/taskterm/config.json` | ステータス・タグの定義と `v` の表示状態 (`XDG_CONFIG_HOME` があればそちら) |

タスクはステータス・タグをIDで参照しているので、設定画面で名前や色を変えても紐付きは保たれます。

完了日が付くようになる前からある完了タスクは完了日を持ちません。完了タブでは `—` と出て、末尾にまとまります。

タスクファイルが読めない・壊れている場合は `tasks.json.broken` に退避してから空の状態で起動するので、上書きで消えることはありません。設定ファイルが壊れている場合は既定のステータスで起動します。
