01. What is tama?
Tama is a terminal-based task managing program that writes tasks
to markdown files in a tasks directory.
It provides a simple CLI for creating, filtering, tracking and modifying tasks.
02. Why make tama?
After stumbling across Tsoding's recreational programming streams and seeing him use his tatr application for tracking tasks related to his different projects, I decided I wanted one of my own.
So, instead of using someone else's clone of tatr, I decided to implement my own version from scratch. This became tama.
03. Design
Tama tasks are stored in folders within the tasks folder.
> ls tasks
tasks
├──20260804-093138
├──20260804-093140
├──20260804-094106
├──20260804-124128
├──20260804-124413
├──20260804-185036
└──20260806-105511
The task-ids for each task are created from the timestamp at which the task was
created. Currently, tasks that are created within the same second are suffixed
with -1, -2 etc.
Each task comes with TASK.md and LOG.md files.
The TASK.md file contains the task's title and body along with task-relevant metadata.
Each tasks contains the following fields by default, with extra fields serialised and deserialised but not modifiable through the CLI.
- priority (integer)
- status (OPEN / CLOSED)
- tags (tag1,tag2,tag3)
- author
- parent
- blockers
- related tasks
The LOG.md file stores a running log per task, and is writeable with
tama log [task-id] [contents].
04. Task relationships
By default, tasks ship with empty "parent", "blocked-by" and "relates-to" fields. These fields allow for more complex relationships between tasks than a regular TODO-list.
The "parent" and "relates-to" fields serve as documentation to track tasks that fall under the same group of tasks or reference each other.
The "blocked-by" field lets users track a hierarchy of tasks, closing all blocking tasks leaves a task ready for the next round of edits.
Users can use the inbuilt filter .READY to track un-blocked tasks for iterative
development.
05. Filtering
Examples using filtering:
> tama ls .READY
> tama ls .TAGGED
> tama ls .bug or .issue
> tama ls .OPEN and not .TAGGED
The filtering system consists of 4 keywords:
- TAG
- AND
- OR
- NOT
Tama's ls command combines tags with the 3 predicates to generate a tree of
filtering nodes where not has the highest binding power followed by and and
then or.
06. The CLI
Tama is designed around simple commands like cat and ls that can be composed
with Unix tools. Most commands return human-readable output from task-ids as
input but commands like ls, cat and sum can optionally emit JSON for scripting.
Sample tama workflow:
> tama new "Implement filters" -p 20 -t cli,feature
> tama ls .OPEN
> tama edit 12
> tama log 12 "Finished parser"
> tama close 12
07. What I learned
One of the biggest lessons from Tama was that designing a proper data model early matters more than I expected. I had originally implemented a very naive format for reading the task files which resulted in awkward memory copying and struct formatting when I wanted to add more fields.
Switching to a deserialise -> modify fields array -> serialise pipeline made adding
new features such as parent and blocked-by easier.
08. Future plans
I plan on adding a migrate command which can convert stray TODO: tasks into tama
tasks throughout the codebase and replace the marker with the task-id of the newly
created task.
A dashboard to view dependencies and tracked tasks across repos and better task searching with hash-based ids are also possible angles I am considering.