Taskchampion

Ruby bindings for TaskChampion, the task database that powers Taskwarrior.

This gem supports Ruby 3.2 and later. We follow Ruby's end-of-life (EOL) schedule and drop support for Ruby versions that have reached EOL.

• Ruby 3.2: Supported (EOL: March 2026)
• Ruby 3.3: Supported (Current stable)
• Ruby 3.4: Supported
• Ruby 3.0-3.1: Not supported (reached EOL)

1. Ruby 3.2 or later
2. Rust toolchain (install from https://rustup.rs/)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

bundle install
bundle exec rake compile

bundle exec rake test

require 'taskchampion'

# Create an in-memory replica
replica = Taskchampion::Replica.new_in_memory

# Create an on-disk replica
replica = Taskchampion::Replica.new_on_disk("/path/to/taskdb", true)

# With access mode
replica = Taskchampion::Replica.new_on_disk("/path/to/taskdb", true, :read_only)

# Working with operations
ops = Taskchampion::Operations.new
create_op = Taskchampion::Operation.create(SecureRandom.uuid)
ops << create_op

# Task operations (when Operations integration is complete)
# task = replica.create_task(uuid, ops)
# task.set_description("New task description", ops)
# replica.commit_operations(ops)

# Working with tags and annotations
tag = Taskchampion::Tag.new("work")
puts tag.to_s          # => "work"
puts tag.user?         # => true
puts tag.synthetic?    # => false

annotation = Taskchampion::Annotation.new(DateTime.now, "This is a note")
puts annotation.description  # => "This is a note"

# Status constants
puts Taskchampion::PENDING     # => :pending
puts Taskchampion::COMPLETED   # => :completed
puts Taskchampion::ACCESS_MODES # => [:read_only, :read_write]

This is a Ruby port of the taskchampion-py Python bindings. The implementation follows the plan outlined in the ruby_docs/ directory of the Python project.

• ✅ Basic project structure
• ✅ Magnus and rb-sys configuration
• ✅ Error hierarchy (Error, ThreadError, StorageError, ValidationError, ConfigError)
• ✅ Thread safety utilities
• ✅ Type conversions (DateTime, Option, HashMap, Vec)
• ✅ Replica class with Ruby idiomatic API
• ✅ Task class with Ruby idiomatic API
• ✅ Tag and Annotation classes
• ✅ Status constants (:pending, :completed, :deleted, etc.)
• ✅ Operation and Operations classes
• ✅ Access mode support
• ✅ Minitest testing infrastructure
• ✅ GitHub Actions CI/CD

• WorkingSet class implementation
• DependencyMap class implementation
• Complete Task mutation methods (requires Operations integration)
• Complete test suite porting from Python
• Cross-platform compilation
• YARD documentation
• RubyGems publication

The Ruby API follows Ruby idioms:

• Method names use snake_case
• Boolean methods end with ? (e.g., active?, waiting?)
• Property access doesn't use get_ prefix (e.g., task.uuid not task.get_uuid)
• Keyword arguments for optional parameters
• nil instead of None
• Symbols for enums (e.g., :read_only, :read_write)

All TaskChampion objects are thread-local and will raise Taskchampion::ThreadError if accessed from a different thread than the one that created them.

Bug reports and pull requests are welcome on GitHub at https://github.com/GothenburgBitFactory/taskchampion.