Overview

Taskter is a powerful, terminal-based Kanban board designed for developers, project managers, and anyone who prefers to manage their tasks directly from the command line. Built with Rust, Taskter is a lightweight and efficient tool that helps you keep track of your projects without leaving the terminal.

Key Features

• Kanban Board: Visualize your workflow with ToDo, In-Progress, and Done columns.
• Task Management: Add, edit, delete, and manage tasks with simple commands.
• Agent System: Automate tasks using LLM-based agents with tool-calling capabilities.
• Project Tracking: Keep track of your project's description, objectives, and key results (OKRs).
• Operation Logs: Maintain a log of all operations performed on the board.
• Interactive TUI: A user-friendly terminal interface for easy navigation and task management.

This book serves as the official documentation for Taskter, providing a comprehensive guide to its features and usage. Whether you're a new user or a seasoned developer, this guide will help you get the most out of Taskter.

Installation

You can install Taskter from prebuilt packages or build from source.

Homebrew

brew tap tomatyss/taskter
brew install taskter

Linux packages

Prebuilt .deb archives are generated using cargo deb and can be downloaded from the GitHub release page. Install them with dpkg -i:

sudo dpkg -i taskter_0.1.0_amd64.deb

For Alpine Linux there is an APKBUILD script in packaging/apk/ which can be used with abuild -r to produce an apk package.

Build from Source

To build Taskter from source, you need to have Rust and Cargo installed.

1. Clone the repository:

   git clone https://github.com/tomatyss/taskter.git
   cd taskter
   

2. Build the project:

   cargo build --release
   

   The executable will be located at target/release/taskter.

3. Install the executable: You can make taskter available system-wide by copying it to a directory in your system's PATH. For example, on macOS or Linux:

   sudo cp target/release/taskter /usr/local/bin/taskter
   

   Alternatively, you can use cargo install:

   cargo install --path .
   

   This will install the taskter executable in your Cargo bin directory (~/.cargo/bin/), which should be in your PATH.

Docker

If you prefer to use Docker, you can build and run Taskter without installing Rust locally.

1. Build the Docker image:

   docker build -t taskter .
   

2. Run the application:

   docker compose run --rm taskter --help
   

   If you plan to use the Gemini integration for agents, you'll need to pass your API key as an environment variable:

   GEMINI_API_KEY=<your_key> docker compose run --rm taskter --help
   

CLI Usage

Taskter exposes multiple subcommands. Run taskter --help to see the available options. The README lists common workflows.

Quick Start

This section provides a quick overview of how to get started with Taskter.

1. Initialize the board

First, navigate to your project's directory and initialize the Taskter board:

taskter init

This will create a .taskter directory to store all your tasks, agents, and project data.

2. Create an agent

Next, create an agent to help you with your tasks. For this example, we'll create a simple agent that can run bash commands:

taskter agent add --prompt "You are a helpful assistant that can run bash commands." --tools "run_bash" --model "gemini-pro"

You can list all available agents using:

taskter agent list

You can list the built-in tools with:

taskter tools list

3. Create a task

Now, let's create a task for your agent to complete:

taskter task add -t "List files in the current directory" -d "Use the ls -la command to list all files and folders in the current directory."

You can see all your tasks by running:

taskter task list

4. Assign the task to an agent

Assign the newly created task to your agent:

taskter task assign --task-id 1 --agent-id 1

5. Execute the task

Finally, execute the task:

taskter task execute --task-id 1

The agent will now run the task. If it's successful, the task will be marked as "Done". You can view the board at any time using the interactive UI:

taskter board

TUI Guide

Taskter's interactive Terminal User Interface (TUI) provides a visual way to manage your Kanban board. To launch it, run:

taskter board

Keybindings

The TUI is controlled with keyboard shortcuts. Here is a list of the available keybindings:

When a task is selected, you can press Enter to view its details, including the full description, any comments, and the assigned agent ID.

Agent System

Taskter supports LLM-based agents that can be assigned to tasks. These agents can execute tasks using a mocked Gemini API for tool-calling.

Creating an Agent

You can create an agent using the agent add subcommand. You need to provide a prompt, a list of tools, and a model.

taskter agent add --prompt "You are a helpful assistant." --tools "email" "calendar" --model "gemini-pro"

The --tools option accepts either paths to JSON files describing a tool or the name of a built-in tool. Built-in tools are located in the tools/ directory of the repository.

Available built-in tools:

• taskter_task
• taskter_agent
• taskter_okrs
• taskter_tools
• get_description
• run_bash
• run_python
• send_email
• web_search

You can display this list at any time with:

taskter tools list

Assigning an Agent to a Task

Once you have created an agent, you can assign it to a task using the assign subcommand:

taskter task assign --task-id 1 --agent-id 1

Executing a Task

To execute a task with an assigned agent, use the execute subcommand:

taskter task execute --task-id 1

When a task is executed, the agent will attempt to perform the task. If successful, the task is marked as "Done". If it fails, the task is moved back to "To Do", unassigned, and a comment from the agent is added.

In the interactive board (taskter board), tasks assigned to an agent will be marked with a *. You can view the assigned agent ID and any comments by selecting the task and pressing Enter.

Updating an Agent

Use the agent update command to modify an existing agent's configuration:

taskter agent update --id 1 --prompt "New prompt" --tools "taskter_task" --model "gemini-pro"

All three options are required and the previous configuration is overwritten.

Scheduling Agents

Taskter can run agents automatically based on cron expressions. A scheduler daemon reads the agent configuration and executes the assigned tasks at the defined times.

Setting a Schedule

Use the agent schedule set command to assign a cron expression to an agent. The expression is parsed in the America/New_York timezone.

# Run every minute
taskter agent schedule set --id 1 --cron "0 * * * * *"

Pass --once to remove the schedule after the first run.

Listing and Removing

List all scheduled agents with:

taskter agent schedule list

Remove a schedule:

taskter agent schedule remove --id 1

Running the Scheduler

Start the scheduler loop with:

taskter scheduler run

The scheduler will execute agents at the configured times and update tasks just as if task execute was run manually.

Configuration

This chapter describes runtime configuration files and environment variables used by Taskter.

Email configuration file

Email-based tools expect credentials in .taskter/email_config.json inside your project. Every agent reads the same file.

{
  "smtp_server": "smtp.example.com",
  "smtp_port": 587,
  "username": "user@example.com",
  "password": "secret",
  "imap_server": "imap.example.com",  // optional
  "imap_port": 993                    // optional
}

Currently only the SMTP fields are used by the send_email tool. The IMAP keys are accepted for future extensions. No default values are provided, so fill in the details that match your mail provider.

If the file is missing the tool outputs Email configuration not found. When Taskter runs without a GEMINI_API_KEY, email tools are skipped entirely so the file is not required for tests.

Environment variables

Taskter looks for a couple of optional environment variables:

• GEMINI_API_KEY — API key for the Gemini model. When set, agents can call the remote API. If absent or empty Taskter stays in offline mode and only uses built-in tools.
• SEARCH_API_ENDPOINT — custom endpoint for the web_search tool. Defaults to https://api.duckduckgo.com.

Set it directly in your shell or via Docker Compose:

export GEMINI_API_KEY=your_key_here

Contributing

Contributions are welcome! This guide will help you get started with setting up your development environment and submitting your changes.

Development Environment

To contribute to Taskter, you'll need to have Rust and Cargo installed. If you haven't already, follow the instructions at rust-lang.org.

Once you have Rust set up, clone the repository and navigate to the project directory:

git clone https://github.com/tomatyss/taskter.git
cd taskter

Pre-commit checks

Before committing any changes, please run the pre-commit script to ensure your code is formatted, linted, and passes all tests:

./scripts/precommit.sh

You can also automatically apply formatting and Clippy suggestions with:

./scripts/fix_lints.sh

You can also set this up as a pre-commit hook to run automatically:

ln -s ../../scripts/precommit.sh .git/hooks/pre-commit

Documentation

The documentation is built with mdBook. To contribute to the docs, edit the Markdown files under the docs/src/ directory.

When you're ready, open a pull request with your changes. The GitHub Actions workflow will automatically build and publish the book when your changes are merged into the main branch.