██████╗ ██████╗ ██╗   ██╗
██╔═══██╗██╔══██╗██║   ██║
██║   ██║██████╔╝██║   ██║
██║   ██║██╔══██╗██║   ██║
╚██████╔╝██║  ██║╚██████╔╝
 ╚═════╝ ╚═╝  ╚═╝ ╚═════╝

Personal task manager for the terminal. Designed to be operated by your AI agent.

SQLite database on your machine. No accounts. No cloud. Pass --json to any command for machine-readable output.

Install

curl -fsSL https://oru.sh/install.sh | bash

Requires Node 22+.

Or install via npm:

npm install -g @tchayen/oru

Quick start

oru add "Write README for release"
oru add "Fix login bug" -p high -d friday -l backend
oru add "Water plants" -r "every 3 days" -d today
oru list
oru context                  # what needs your attention right now
oru done <id>                # recurring tasks auto-spawn the next occurrence

Commands

Command	Description
add <title>	Add a new task
list	List tasks (hides done by default)
get <id>	Get a task by ID
update <id>	Update a task
edit <id>	Open task in $EDITOR
done <id...>	Mark tasks as done
start <id...>	Mark tasks as in_progress
review <id...>	Mark tasks as in_review
delete <id...>	Delete tasks
context	Summary of overdue, due soon, in progress, and actionable tasks
labels	List all labels in use
log <id>	Show change history of a task
filter add <name>	Save a named filter (same flags as list)
filter list	List saved filters
filter show <name>	Show a filter's definition
filter remove	Delete a saved filter
sync <path>	Sync with a filesystem remote
backup [path]	Create a database backup snapshot
config init	Create a default config file
completions	Generate shell completions (bash, zsh, fish)
self-update	Update oru to the latest version

Agent usage

oru is built to be operated by AI agents. Pass --json to any command for structured output. Pass --id to add for idempotent task creation. Attach --meta key=value pairs for agent-specific data.

# Agent creates a task with a known ID (idempotent)
oru add "Refactor auth module" --id A1b2C3d4E5f \
  -p high -l backend --meta agent=claude --json

# Agent reads what needs attention
oru context --json

# Agent updates a task (prefix match on IDs)
oru update A1b -s in_progress --meta pr=142 --json

# Create a recurring task (auto-spawns next occurrence when done)
oru add "Weekly standup" -r "every monday" -d "next monday" --json

Set ORU_FORMAT=json or output_format = "json" in config to default to JSON output.

MCP server

oru ships with an MCP server so AI agents can manage tasks through the standardized protocol.

Claude Desktop / Claude Code

Add to your MCP config:

{
  "mcpServers": {
    "oru": {
      "command": "npx",
      "args": ["-p", "@tchayen/oru@latest", "oru-mcp"]
    }
  }
}

Or if oru is installed globally (npm install -g @tchayen/oru):

{
  "mcpServers": {
    "oru": {
      "command": "oru-mcp"
    }
  }
}

Available tools

Tool	Description
add_task	Create a new task
update_task	Update fields on an existing task
delete_task	Delete a task by ID
list_tasks	List tasks with optional filters
get_task	Get a single task by ID
get_context	Summary of what needs attention
add_note	Append a note to a task
list_labels	List all labels in use

Configuration

oru config init # creates ~/.oru/config.toml with documented options

Key options:

• date_format - "mdy" (US) or "dmy" (international)
• first_day_of_week - "monday" or "sunday"
• output_format - "text" or "json"
• backup_path - directory for automatic backups
• backup_interval - minutes between auto-backups (default: 60)

Sync

oru syncs between machines via a shared filesystem (Dropbox, iCloud Drive, NAS, etc.):

oru sync ~/Dropbox/oru-sync

Conflict resolution is automatic: last-write-wins per field, updates beat deletes, notes append with dedup. The oplog is the source of truth.

Data

Everything is stored locally in ~/.oru/oru.db (SQLite). Override with ORU_DB_PATH.