Something went wrong. Try again.
A git-based task manager
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258tsk===
A fast & simple CLI task manager--------------------------------
The motivation for tsk is simple: make managing tasks as fast and easy aspossible with a focus on small, ephemeral tasks.
Secondary goals include:
- Provide the minimum amount of features necessary to be usable by a team- Support local and non-local workspaces- Be adaptable to almost any environment, even employer-mandated JIRA use- Be flexible, within reason
tsk takes inspiration from git and FORTH and is expected to be used alongsidethe former.
Dependencies------------
tsk is written in Rust. To compile from source, a recent Rust toolchain isrequired. As of now, it is developed using Rust 1.81.0.
Additionally, for fuzzy-finding functionality, the fzf command must be installedand in the shell's PATH.
https://github.com/junegunn/fzf
tsk stores its data in git refs (`refs/tsk/*`) inside a host git repository, soany filesystem git itself runs on will work. Use the `tsk git-pull` and`tsk git-push` commands to update/push these refs.
When `tsk git-pull` finds incompatible edits to the same task body, it opens aneditor on a temporary file with conflict markers, then commits the edited resultas a normal two-parent merge commit. Saving an empty resolution aborts that taskmerge and leaves the local task ref unchanged. Incompatible property edits areresolved last-one-wins by the task commit timestamps, and the merge commitmessage records each property conflict and the side that won.
Installation------------
```shcargo install --locked tsk-cli```
With Nix Home Manager, add this flake's module and enable `programs.tsk`:
```nix{ imports = [ inputs.tsk.homeManagerModules.default ];
programs.tsk = { enable = true; installSkill = true; };}```
`installSkill` writes the output of `tsk skill` to`~/.agents/skills/tsk/SKILL.md`.
Building--------
```shcargo install --path .```
Build the optional MCP server with:
```shcargo install --path . --features mcp```
Make sure ~/.cargo/bin is in your PATH.
MCP server----------
Run `tsk mcp` to host an MCP server over standard input and output. Configurethe client to start `tsk mcp` inside the target repository, or pass `-C DIR`.The server exposes each CLI command as a tool, except `mcp` and `serv`.
Overview--------
A summary of commands and their functionality can be seen with:
tsk help
tsk uses virtual text files tracked by special refs in a git repo for itsfunctionality. Any git repo can be made into a tsk workspace.
New tasks are created with the `tsk push` command. A title is always required,but can be modified later. A unique, human-readable identifer is selectedscoped to the namespace and may be used to as a stable reference within thatnamespace.
The contents of the stack may be printed using the `tsk list` command.Open tasks across the active namespace may be printed using `tsk open`; itshows each task id, the queue index or indexes containing it (comma-separated),or `none` when the open task is not currently queued.
Tasks are marked as "completed" and removed from the active queue with the`tsk drop` command. To remove a task from the active queue while leaving itsstatus unchanged, use `tsk abandon`. Completed tasks can be marked open againwith `tsk reopen`; by default this places them at the top of the active queue,or `tsk reopen --no-queue` can leave them unqueued.
Queues are independent ordered stacks; task lifecycle comes from the protected`status` property, not from queue membership. Create one with`tsk queue create NAME`; new queues default to `can-pull=false`, which preventsother queues from pulling tasks out of them. Use `tsk queue create -p NAME` tocreate a pullable queue, or `tsk queue can-pull NAME true|false` to change thatflag later. Inbox items are ordered top-first like queue tasks; `tsk accept`with no key accepts the top inbox item. Use `tsk accept -T tsk-N` to place anopen task that is not currently assigned to any queue onto the active queue.
The priority of a task may be manipulated in any of several ways:
`tsk swap` swaps the top two task on the stack
┌─────────┐ ┌─────────┐ │ tsk-100 │ │ tsk-102 │ └─────────┘ └─┬─────▲─┘ │ │ ┌─────────┐ ┌─▼─────┴─┐ │ tsk-102 │ ───────► │ tsk-100 │ └─────────┘ └─────────┘ ┌─────────┐ ┌─────────┐ │ tsk-108 │ │ tsk-108 │ └─────────┘ └─────────┘
`tsk rot` moves the 3rd task on the stack to the top of the stack and shiftsthe first and second down
┌─────────┐ ┌─────────┐ │ tsk-100 │ │ tsk-108 ◄─┐ └─────────┘ └────┬────┘ │ │ │ ┌─────────┐ ┌────▼────┐ │ │ tsk-102 │ ───────► │ tsk-100 │ │ └─────────┘ └────┬────┘ │ │ │ ┌─────────┐ ┌────▼────┐ │ │ tsk-108 │ │ tsk-102 ├─┘ └─────────┘ └─────────┘
`tsk tor` moves the task on the top of the stack behind the third, shifting thesecond and third tasks up.
┌─────────┐ ┌─────────┐ │ tsk-100 │ │ tsk-102 ├─┐ └─────────┘ └────▲────┘ │ │ │ ┌─────────┐ ┌────┴────┐ │ │ tsk-102 │ ───────► │ tsk-108 │ │ └─────────┘ └────▲────┘ │ │ │ ┌─────────┐ ┌────┴────┐ │ │ tsk-108 │ │ tsk-100 ◄─┘ └─────────┘ └─────────┘
`tsk prioritize` will take a selected task and move it to the top of the stackfrom any other position in the stack. It is selected either by ID or using fuzzyfinding.
`tsk deprioritize` moves a selected task to the bottom of the stack from anyposition.
Roadmap-------
- Configurable workspace-scoped prefix tags (tsk- vs example-)- Task Linking- Export + sync with external task managers - GitLab - GitHub - JIRA - Obsidian - More?- tsk -> html export- Editor plugins - nvim-telescope - nvim - others?- Man page
Format------
The tsk text format can be thought of as a derivative of Markdown and scdoc, butnot quite either. Markdown is a great baseline for rich-text while scdocrestricts itself to rich text formatting that can be displayed effectively in aterminal. As tsk's primary goal is to be a fast, terminal-centric task manager,this property is a *must.*
Additionally, it should be similar enough to Markdown such that it is easy toexport to other applications, as outlined above in the roadmap.
Meanwhile, both Markdown and scdoc have some limitations and make choices that,while appropriate for their domain, are not appropriate for tsk. Some notabledifferences from both:
- There is only one way to do any type of formatting- Hard line breaks are real, not imaginary- Inline formatting control characters must be surrounded by space, newline, or common punctuation
A core feature of the format is *linking*. That is, references to other tasksutilizing wiki-link style links: `[[]]`. The content within the link is mappedto the local workspace if the `tsk-` prefix is used, or a mapped non-localworkspace if another prefix is used. These mappings are specified using a textfile within the .tsk folder.
A quick overview of the format:
- !Bolded! text is surrounded by exclamation marks (!)- *Italicized* text is surrounded by single asterisks (*)- _Underlined_ text is surrounded by underscores (_)- ~Strikethrough~ text is surrounded by tildes (~)- =Highlighted= text is surrounded by equals signs (=)- `Inline code` is surrounded by backticks (`)
Links like in Markdown, along with the wiki-style links documented above.Raw links can also be written as \<https://example.com\>.
New dependent tasks can be created while saving a task by writing a titlebetween `[>` and `<]`. For example, `blocked by [> provision database <]`creates a new task titled `provision database`, replaces that text with aninternal link such as `[[tsk-12]]`, and records protected `depends-on` /`blocks` properties between the two tasks.
Misc----
tsk is heavily inspired by git. It mimics its folder structure and somecommands. The concept of the stack is inspired by FORTH and the observation thatmost of the time, only the top 3 priorities at any given moment matter and taskstend to be created when they are most important. This facilitates small,frequent creation of tasks that help both document problems and managefast-paced work environments.
tsk is not intended to be checked into git, however there is not a reason that itcannot be. This repository's development is managed using tsk itself.
Git does *not* track extended filesystem attributes. If you wish to avoid constantlyre-indexing, use something like metastore:
https://github.com/przemoc/metastore