Taskter

Taskter is a terminal Kanban board CLI tool built with Rust.

Warning This project is currently in a pre-alpha state and is actively maintained. Expect breaking changes and incomplete features.

Features

• Kanban board with tasks (ToDo, InProgress, Done)
• Project description
• Operation logs
• OKRs (Objectives and Key Results)

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 add-agent --prompt "You are a helpful assistant that can run bash commands." --tools "run_bash" --model "gemini-2.5-pro"

You can list all available agents using:

taskter show agents

3. Create a task

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

taskter 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 list

4. Assign the task to an agent

Assign the newly created task to your agent:

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

5. Execute the task

Finally, execute the task:

taskter 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

Build and Installation

Taskter can be installed from prebuilt packages or built from source.

Homebrew

brew tap tomatyss/taskter
brew install taskter

Linux packages

Prebuilt .deb archives are generated with cargo deb and published on the GitHub release page. You can install them with:

sudo dpkg -i taskter_0.1.0_amd64.deb

For Alpine Linux an APKBUILD script is provided under packaging/apk/. Run abuild -r inside that directory to create 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 <repository_url>
   cd taskter
   

2. Build the project:

   cargo build --release
   

The executable will be located at target/release/taskter. To make it available system-wide, you can copy it to a directory that is in your system's PATH.

For example, on macOS or Linux, you can move it to /usr/local/bin:

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

After this, you can run taskter from any directory.

Alternatively, you can install the latest published version from crates.io:

cargo install taskter

You can also install directly from the repository for a development build:

cargo install --path .

Both methods place the taskter executable in your Cargo bin directory (usually ~/.cargo/bin/), which should be in your PATH.

Docker

You can build and run Taskter without installing Rust locally by using Docker. The included Dockerfile uses the official rust:1.88.0 image to build the application.

Build the container image:

docker build -t taskter .

Start the application with Docker Compose. If you use the Gemini integration, pass your API key as an environment variable:

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

Usage

Initialize the board

To start using Taskter, you need to initialize a board in your project's directory:

taskter init

This will create a .taskter directory with the necessary files.

Interactive Board

Taskter also provides an interactive terminal UI to manage the Kanban board.

taskter board

In the interactive board, you can use the following keys:

• q: Quit
• ← / → or Tab: Navigate between columns
• ↑ / ↓: Navigate between tasks
• h / l: Move a task to the previous/next column
• a: Assign an agent to the selected task
• c: Add a comment to the selected task
• n: Create a new task
• u: Edit the selected task
• d: Delete the selected task
• L: View project logs
• A: List available agents
• O: Show OKRs
• ?: Show available commands

Manage tasks

• Add a new task:

  taskter add -t "My new task" -d "A description for my task"
  

• In the interactive board (taskter board), press n to add a task interactively. Enter the title, press Enter, then provide the description and press Enter again.

• Edit a task: Press u while the task is selected in the board to update its title and description.

• Delete a task: Press d while the task is selected in the board.

• List all tasks:

  taskter list
  

• Mark a task as done:

  taskter done <task_id>
  

• Add a comment to a task:

  taskter comment --task-id <task_id> --comment "Your note"
  

Project information

• Show project description:

  taskter show description
  

• Show project OKRs:

  taskter show okrs
  

• Show operation logs:

  taskter show logs
  

Manage OKRs

• Add a new OKR:

  taskter add-okr -o "My objective" -k "Key result 1" "Key result 2"
  

Manage logs

• Add a log entry:

  taskter log "This is a log message"
  

Agents

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

• Add a new agent:

  taskter add-agent --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-ins live under the tools/ directory of the repository. For example email resolves to tools/send_email.json. Other built-ins include create_task, assign_agent, add_log, add_okr, list_tasks, list_agents, get_description, run_bash, and run_python.

• Assign an agent to a task:

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

• Execute a task with an agent:

  taskter execute --task-id 1
  

• List available agents:

  taskter show agents
  

• Delete an agent:

  taskter delete-agent --agent-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.

Email configuration

Agent email tools read credentials from .taskter/email_config.json. At the moment only SMTP settings are required by the send_email tool, but IMAP details can also be provided for future extensions. Create the file with the following structure:

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

All agents will use the same configuration file. If the file is missing, the send_email tool will gracefully fall back to a no-op so tests and offline usage keep working.

Gemini API key

Agent execution uses the Gemini API, so the GEMINI_API_KEY environment variable must be set. For example:

export GEMINI_API_KEY=your_key_here

Example project

If you want to see Taskter in action without manually creating data, run the provided helper script:

./scripts/setup_example_project.sh

The script removes any existing .taskter directory, creates a new board with a few example tasks, sets a project description, defines OKRs and adds an agent using the built-in email tool. Once it finishes you can inspect the board with taskter list or launch the TUI via taskter board.

Development

Run the included helper script before committing changes to ensure the code is formatted, linted and all tests pass:

./scripts/precommit.sh

If you want Git to run it automatically, create a pre-commit hook:

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

Documentation

Rendered documentation is available on GitHub Pages: https://tomatyss.github.io/taskter/.

To contribute to the book, edit the Markdown files under docs/src/ and open a pull request. The Deploy Docs workflow will rebuild the book and publish it automatically when changes land on main.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.