1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
# Ranger
A personal task tracker inspired by Pivotal Tracker, built in Rust.
Ranger strips Pivotal Tracker down to its essentials: tasks, tags, and two lists. No projects, no user management, no role hierarchies — just a focused tool for tracking work.
## Why Ranger
Pivotal Tracker does too much. Most of its features — story types, epics, multi-user workflows — serve teams, not individuals. Ranger keeps what matters for solo work and discards the rest.
## Design
### Tasks
Every item is a task. No stories, bugs, chores, or features — just tasks. Each task has:
- **Title** and **description**
- **Comments** for ongoing notes
- **Subtasks** for breaking work down
- **Blockers** for expressing dependencies
- **Tags** for grouping related work
### States
A task is always in one of four states:
| State | Meaning |
|---|---|
| **Icebox** | Captured but not committed to |
| **Queued** | Committed and ordered by priority |
| **In Progress** | Actively being worked on |
| **Done** | Finished |
### Tags Instead of Projects
Tags replace projects. Filter any backlog by tag to see a focused slice of work. No rigid project boundaries, no duplication when a task spans concerns.
### Interface
The webapp uses an expanding modal for editing tasks — no cluttered inline editing. Design is minimalist, built with [Utopia](https://utopia.fyi/) fluid responsive CSS.
## Getting Started
Build and install:
```
cargo install --path .
```
Or run directly:
```
cargo run --bin ranger -- <command>
```
### Quick start
```
ranger backlog create "my-project"
ranger task create "First thing to do" --backlog my-project
ranger task create "Second thing" --backlog my-project --state ready --tag urgent
ranger task list --backlog my-project
ranger task edit <key> --state in_progress
ranger comment add <key> "Started working on this"
ranger task show <key>
```
Use `--json` on any command for machine-readable output. Backlogs are identified by name. Tasks are referenced by key prefix — type just enough characters to be unique.
Set `RANGER_DEFAULT_BACKLOG` to skip `--backlog` on every command.
The database lives at `$XDG_DATA_HOME/ranger/ranger.db` by default. Override with `--db <path>` or `RANGER_DB` env var.
## Architecture
Ranger is a single Rust crate with a library and binary target:
- **Library** (`ranger`) — core data model, database operations, key generation
- **CLI** (`ranger` binary) — clap-based binary for humans and AI agents
- **Webapp** — for human use (planned)
The CLI exists primarily so AI agents can manage tasks programmatically. The webapp exists for humans who prefer a visual interface.
## Releases
Ranger uses a two-forge release pipeline:
1. **Gitea** (`git.kejadlen.dev`) is the source of truth. CI runs on every push to `main` (and on PRs). When CI passes, a `vYYYY-MM-DD+<short-sha>` tag is created automatically.
2. Tags mirror to **GitHub** (`github.com/kejadlen/ranger`). A tag push triggers the release workflow, which builds macOS and Linux binaries, creates a GitHub release, and publishes Dotslash configuration.
The version format is calver: the date of the commit plus its short SHA (e.g., `v2026-04-21+abc1234`).
## Roadmap
**First milestone:** self-host Ranger so an AI agent can use it for task management while building Ranger itself.
After that:
- Claude Code plugin for AI agent task management
- Public read-only sharing with permissions
- Configurable backlog views
- Browsing completed work