Tasklynx

A local-first task manager for developers — Git-style branches, a terminal Kanban board, and a fast web dashboard.

Documentation · AI Reader · Releases · Issues · Docs source

---

Overview

Tasklynx keeps your tasks in a single local JSON file, with no account, no daemon, and no network dependency for core task management. It borrows the parts of a Git workflow that are useful for planning — branches for parallel streams of work, short prefix IDs, and fast filtering — and gives you three ways to use it:

• CLI (tasklynx or the short alias tx) for scripting and quick capture.
• TUI (tx board) for an interactive Kanban board in the terminal.
• Web (tx web) for a responsive browser dashboard on 127.0.0.1.

Everything is written atomically to disk, so a crash can't leave a half-written task store.

Current release: v0.0.1-b4 — Git-aware planning, optional AI previews in source builds, recurring work, dependencies, time tracking, reminders, and calendar export.

Features

• Local-first — tasks live on your machine; nothing is sent anywhere unless you explicitly run an AI command.
• Git-style branches — keep work for different features or releases separate.
• Short IDs — any unique prefix of a task UUID works in commands.
• Priorities, due dates, and recurrence — low, normal, high, urgent, with daily/weekly/monthly/yearly repeats.
• Projects, tags, and saved views — group work and reuse filters instantly.
• Dependencies and subtasks — block work, create child tasks, and inspect the tree.
• Three interfaces — CLI, terminal Kanban TUI, and a web dashboard.
• Time tracking and reminders — local timers, estimates, desktop notifications, and iCalendar export.
• Git-aware workflow — branch mapping, commit/PR/issue links, TODO scanning, and optional commit trailers.
• Opt-in AI planning — draft plans, breakdowns, triage, standups, reviews, and questions with local Ollama or OpenAI-compatible providers behind the ai build feature.
• Safe edits — undo mutations and restore deleted tasks from trash.
• Cross-platform — Linux, macOS, Windows, and Android (Termux), with ARM and x86 builds.
• Single binary — no runtime dependencies; tx self update keeps it current.

Screenshots

Kanban Board	Task Modal Editor

More images and descriptions in the screenshots gallery.

Installation

Package managers

Manager	Platform	Command
APT	Debian / Ubuntu	curl -LO https://github.com/peekstore/tasklynx/releases/download/v0.0.1-b4/tasklynx_0.0.1-b4_amd64.deb && sudo apt install ./tasklynx_0.0.1-b4_amd64.deb
npm	Cross-platform	npm install -g tasklynx / npx tasklynx
pipx	Cross-platform	pipx install git+https://github.com/peekstore/tasklynx.git#subdirectory=packaging/pipx
Chocolatey	Windows	choco install tasklynx
Cargo	Universal (Rust)	cargo install --git https://github.com/peekstore/tasklynx.git --locked

One-line installer

Linux / macOS / Termux

curl -fsSL https://raw.githubusercontent.com/peekstore/tasklynx/main/installer.sh | sh

The installer places tasklynx and the tx alias in ${XDG_CONFIG_HOME:-$HOME/.config}/peekstore/tasklynx/bin and adds that directory to your shell PATH.

Pin a specific version:

TASKLYNX_VERSION=v0.0.1-b4 \
  curl -fsSL https://raw.githubusercontent.com/peekstore/tasklynx/main/installer.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/peekstore/tasklynx/main/installer.ps1 | iex

The installer writes to %USERPROFILE%\.config\peekstore\tasklynx\bin, updates PATH, and creates a Start Menu shortcut.

Android (Termux)

Install Termux from F-Droid, then run the Linux installer:

pkg install curl
curl -fsSL https://raw.githubusercontent.com/peekstore/tasklynx/main/installer.sh | sh

The installer detects your CPU ABI (arm64-v8a, armeabi-v7a, or x86_64) and downloads the matching build.

Manual download

Download standalone binaries or archives from Releases and place them on your PATH. Verify checksums with:

sha256sum -c SHA256SUMS.txt

From source

git clone https://github.com/peekstore/tasklynx.git
cd tasklynx
cargo build --release
install -Dm755 target/release/tasklynx ~/.local/bin/tasklynx

Requires Rust 1.75 or newer.

Quick start

tx init
TASK_ID=$(tx add "Implement authentication" \
  --project api --tag backend,auth --priority high --due 2026-12-31 \
  --description "Password login, session cookies, and logout" --estimate 90)
tx list                                              # tasks on the current branch
tx next --explain                                    # ranking inputs for the next task
tx start "$TASK_ID"                                  # start a local timer
tx complete "$TASK_ID"
tx agenda --days 14                                  # upcoming, overdue, and recurring work
tx board                                             # terminal Kanban board
tx web                                               # dashboard at http://127.0.0.1:8787
tx git status                                        # Git branch and task context

tx add prints only the new task UUID, so it composes with shell variables. Every command also accepts any unique ID prefix.

Dependencies, subtasks, and recurrence

API_ID=$(tx add "Draft API schema" --project api --priority high)
AUTH_ID=$(tx add "Implement authentication" --project api --priority high)
tx block "$AUTH_ID" --by "$API_ID"

PARENT_ID=$(tx add "Ship billing" --project api --due 2026-11-15 --repeat monthly --repeat-until 2027-11-15)
tx subtask "$PARENT_ID" "Add invoice export"
tx tree "$PARENT_ID"
tx unblock "$AUTH_ID" --by "$API_ID"

tx next skips blocked tasks unless --include-blocked is passed. Completing a recurring task creates the next occurrence with its due date advanced.

Branches

tx branch create feature-auth
tx branch switch feature-auth
tx list                    # only tasks on feature-auth
tx list --all              # tasks on every branch
tx branch switch main
tx branch delete feature-auth

Git-aware workflow

tx git status                         # repo, branch, HEAD, dirty state, recent commits
tx git scan --apply --project backend # turn TODO/FIXME/HACK comments into tasks
GIT_TASK=$(tx add "Wire authentication" --project api)
tx git activate "$GIT_TASK"           # task used by the optional commit hook
tx git hook install                   # review and install the prepare-commit-msg hook
git commit -m "Wire authentication"
tx git sync                           # link tasks from trailers or subject IDs
tx git link "$GIT_TASK" --commit "$(git rev-parse --short HEAD)"
tx git open "$GIT_TASK" --print       # commit, PR, or issue URL
tx git deactivate

Git integration only reads local repository metadata. It never pushes, rewrites history, or contacts a remote.

Templates, views, and bulk actions

tx add --template review
tx list --save api --project api
tx list --view api
tx complete --done-before 2026-10-31
tx duplicates

Templates fill in common task fields. Saved views keep frequently used filters in config.toml, bulk completion closes overdue work in one undoable step, and tx duplicates flags similar open titles.

Time tracking

tx add "Write migration" --estimate 45
tx start <id>
tx stop
tx time
tx time <id>

Timers are local and daemon-free. Only one runs at a time; completing or deleting a task stops its active timer automatically.

Search, reminders, export, and stats

tx search auth
tx today
tx remind --days 7
tx remind --notify
tx stats
tx export --format json > tasks.json
tx export --format md > TASKS.md
tx export --format ics > tasklynx.ics

CLI at a glance

Command	Description
tx init	Initialize the data store and config
tx add <title>	Add a task (--project, --tag, --priority, --due, --estimate, --description, --repeat, --template)
tx list	List tasks (--project, --tag, --status, --search, --all, --view)
tx view <save|list|show|run|delete>	Manage saved filters
tx doing <id>	Mark a task in progress
tx start <id> / tx stop	Track time locally
tx time [id]	Show tracked time versus estimates
tx complete <id>	Mark a task done (--commit <sha> links a commit)
tx complete --done-before <date>	Bulk-complete due work
tx reopen <id>	Reopen a completed task
tx next	Show the best next task to work on
tx edit <id>	Edit title, description, priority, project, due date, or tags
tx duplicate <id>	Duplicate a task
tx duplicates	Find similar task titles
tx delete <id>	Move a task to trash
tx undo	Undo the most recent CLI mutation
tx trash <list|restore|purge>	Manage deleted tasks
tx block <id> --by <id>	Add a task dependency
tx subtask <parent> <title>	Create a subtask
tx tree [id]	Show subtask trees (--all includes every branch)
tx search <query>	Search titles, descriptions, and tags
tx today	Show tasks due today or overdue
tx agenda --days 14	Show upcoming, overdue, and recurring work
tx remind	Show due and overdue work (--days, opt-in --notify)
tx stats	Show task and branch totals
tx branch <list|create|switch|delete>	Manage branches
tx git ...	Inspect Git context, link commits, scan TODOs, and manage commit hooks
tx ai plan <goal>	Draft a task plan with an opt-in AI provider
tx ai breakdown <id>	Draft subtasks for an existing task
tx ai triage	Rank next tasks with offline fallback
tx ai standup / tx ai review	Summarize recent or branch work
tx ai ask <question>	Ask a question about task context
tx ai doctor	Check AI provider and model configuration
tx export --format <json|md|ics>	Export tasks
tx import [path]	Import JSON or Markdown (--replace, --format)
tx board	Open the terminal Kanban board
tx web	Start the web dashboard
tx completions <shell>	Generate bash, zsh, fish, elvish, or PowerShell completions
tx man	Render the roff manual page
tx config <init|show>	Manage configuration
tx self <update|uninstall>	Manage the installation (--purge removes data/config)

Run tx <command> --help for the full flag list. See the CLI reference.

Configuration

For focused walkthroughs, see Git integration and AI setup.

Configuration lives at:

~/.config/peekstore/tasklynx/config.toml

On Windows this is %USERPROFILE%\.config\peekstore\tasklynx\config.toml; on macOS the same ~/.config convention is used. XDG_CONFIG_HOME is respected.

Create or inspect it with:

tx config init
tx config show

host = "127.0.0.1"
port = 8787
accent = "#ff453a"
background = "#070809"
panel = "#101216"
foreground = "#f5f5f5"
muted = "#8f949e"
font_family = "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
default_project = "default"

[git]
auto_branch = true
branch_prefix = "tx/"
link_commits = true
hooks = false

[ai]
provider = "none"
model = "llama3.1"
endpoint = "http://127.0.0.1:11434"
max_context_tasks = 50
include_descriptions = true
redact = true

AI providers

AI is disabled by default. To use it, build with the optional networking feature and select a provider:

cargo build --features ai

# config.toml
[ai]
provider = "ollama"
model = "llama3.1"
endpoint = "http://127.0.0.1:11434"

The ollama and openai-compatible providers require a feature-enabled build. Official release binaries are built without the ai feature, so installers and package-manager releases support offline triage but not provider-backed AI. For hosted OpenAI-compatible endpoints, set TASKLYNX_AI_API_KEY in the environment instead of writing keys to config.toml. Use tx ai doctor to verify reachability and model availability.

cargo install --git https://github.com/peekstore/tasklynx.git --locked --features ai

Google Gemini through AI Studio works through the OpenAI-compatible provider:

[ai]
provider = "openai-compatible"
model = "gemini-2.5-flash"
endpoint = "https://generativelanguage.googleapis.com/v1beta/openai"

Preview AI plans before writing them:

tx ai plan "Ship the billing API"
tx ai plan "Ship the billing API" --apply
tx ai breakdown <id>
tx ai breakdown <id> --apply
tx ai triage
tx ai triage --offline --include-blocked
tx ai standup --days 1 --project api
tx ai review feature-auth --days 14
tx ai ask "What should I do next?"
tx ai ask "What changed this week?" --branch main --project api

Triage falls back to deterministic tx next ranking when no provider is configured. The web dashboard has an AI copilot panel with preview and apply controls, and the terminal board exposes triage and breakdown previews in its detail pane. Use TASKLYNX_AI_LOG=1 to log prompt sizes and latency without logging prompt contents.

Data storage

Tasks are stored as tasks.json:

Platform	Path
Linux	~/.local/share/tasklynx/tasks.json
macOS	~/Library/Application Support/tasklynx/tasks.json
Windows	%LOCALAPPDATA%\tasklynx\tasks.json

Set TASKLYNX_HOME to relocate the store; the file is written to $TASKLYNX_HOME/tasklynx/tasks.json.

Development

cargo build
cargo test
cargo test --all-targets --features ai
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --features ai -- -D warnings
cargo fmt --all -- --check

See CONTRIBUTING.md for the workflow and docs/development.md for project layout and the release process.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md first. For security issues, follow SECURITY.md.

Brand assets

Logos, icons, and banners live in Tasklynx-logos/. Use them for articles, packages, and integrations.

License

Released under the MIT License. Copyright © 2026 RK Riad Khan.

_{Built with ❤️ by RK Riad Khan (Website) at peekstore · peekstore.github.io · Documentation}