rostr

Rostr is a fast, text-based CLI tool for managing a team's capacity, skills, and project allocations.

Built with an Event-Sourced architecture, Rostr doesn't just store your current state—it maintains an immutable ledger of every staffing change you make. It provides instant, beautifully formatted terminal dashboards to help you forecast utilization, spot bottlenecks, and manage your pipeline.

🔥 What's New in v0.2.1

• 🚀 Weekly Resource Call: A guided wizard to review your team project-by-project and make rapid adjustments.
• 🔄 Allocation Pivots: Make temporary "Pivots" (e.g., crunch mode or project pauses) without changing your long-term staffing plan.
• 📅 Project Lifecycles: Define optional start/end dates for projects to automatically bound consultant allocations.
• 📊 Heatmaps & Hours: Toggle reports between percentage utilization and raw weekly hours.
• 🔍 Smart Sorting: Use the --alphabetical flag across all list and edit commands for faster navigation.
• Context-Aware Availability: Automatically accounts for PTO, Last Working Days (LWD), and Win Probabilities.

🔥 Additions in v0.2.0

• Interactive Setup Wizard: Run rostr setup to personalize your workspace globally.
• Custom Date Formats: Input and view dates your way—choose between YYYY-MM-DD (ISO), DD/MM/YYYY (EU/India), or MM/DD/YYYY (US).
• Workspace Defaults: Set your region's default weekly capacity and custom forecast horizons.
• Smart Shortcodes: Customize the auto-generated length of your team and project shortcodes to fit your organization's naming conventions.
• Modular Architecture: Under-the-hood rewrite separating people, project, and report modules for faster execution and better scalability.

✨ Key Features

• Terminal-Native Dashboards: Rich, color-coded heatmaps and matrix reports right in your terminal.
• Event-Sourced Ledger: Every addition, allocation, and time-off request is stored as an immutable event.
• Smart Forecasting: View utilization projections across days, weeks, or months.
• Pipeline vs. Active Tracking: Filter utilization by 100% confirmed work vs. probable pipeline work.
• Context-Aware Availability: Automatically accounts for PTO and Last Working Days (LWD).

---

🚀 Installation

Rostr is a globally available CLI tool. The recommended way to install it is using pipx, which keeps the tool and its dependencies safely isolated from your system Python.

Option 1: Install via pipx (Recommended)

pipx install rostr

Option 2: Install via pip

pip install rostr

Option 3: Install from Source (For Development)

Clone the repository and install the dependencies using Poetry:

git clone [https://github.com/chaitanyakunthe/rostr.git](https://github.com/chaitanyakunthe/rostr.git)
cd rostr
poetry install

---

📖 Quick Start Guide

Once installed, you can access the tool from anywhere on your computer simply by typing rostr. Here is the basic workflow to get your first report running.

0. Setup

On your very first run, Rostr will automatically launch a setup wizard. You can also trigger this manually at any time to change your date formats, default hours, and reporting targets.

rostr setup

If you ever get stuck, rostr --help will help you. For command specific help - rostr <command> --help and so on.

1. Build your team

Add people to your roster and define their weekly capacity (default is 40 hours).

rostr people add

List people in your team

rostr people list
rostr people list -A # List in alphabetical Order

Edit people

rostr people edit
rostr people edit -A # List in alphabetical Order

2. Log timeoffs and exits

Ensure your forecasts are accurate by changes and plotting timeoffs.

rostr people edit
rostr people timeoff

Remove people from your roster.

rostr people offboard
rostr people delete

3. Create Projects

Add projects to your pipeline. You can mark them as Active, Proposed, etc., and assign a win probability.

rostr project add
rostr project list
rostr project list -A # List in alphabetical Order
rostr project edit
rostr project edit -A # List in alphabetical Order

4. Allocate People to Projects and remove them

Assign your team to projects with start and end dates.

rostr project allocate
rostr project unallocate

3. The Weekly Resource Call Wizard

The most efficient way to manage a large team. Run this during your weekly staffing meeting to skip the manual commands and fly through updates.

rostr review call

• Select Projects: Choose only the projects that need attention.
• Bulk Pause: Pause an entire project team for $X$ weeks in one keystroke.
• Pivot: Temporarily change a consultant's hours for a specific duration.
• Skip: Quickly jump to the next project if no changes are needed.

📊 Reporting & Dashboards

Rostr's true power lies in its reporting engine.

Current Utilization

See exactly what your team is working on today, broken down by project.

rostr report current

Timeline Heatmap

View a color-coded matrix of when people are freeing up across days, weeks, or months.

rostr report timeline --interval week --periods 4

Pipeline Forecast

Look months into the future. See utilization percentages weighted by project probability.

# View the next 3 months (Default)
rostr report forecast --months 3
# Filter to see ONLY confirmed/active work
rostr report forecast --view active
# Filter to see ONLY proposed/pipeline work
rostr report forecast --view probable

Know how is not available

Generate a timeoff report to know unavailable dates

rostr report timeoff

Know your gaps in skill

rostr report skills

🗄️ Where is my data stored?

Rostr uses a local, privacy-first storage model. No databases to spin up, and no cloud servers. All your data is saved locally on your machine in your home directory:

• Path: ~/.rostr/
• Files: You will find rostr_journal.jsonl (your event ledger) and several derived state files (rostr_people.json, etc.)

If you ever want to back up your roster or share it with a colleague, simply copy the ~/.rostr/rostr_journal.jsonl file!

⚠️ CRITICAL WARNING: THE EVENT JOURNAL

Rostr relies on an Event-Sourced Architecture. This means the rostr_journal.jsonl file is the absolute brain and single source of truth for your entire application.

Backups: Because of this architecture, rostr_journal.jsonl is the only file you need to back up. If you move to a new computer, just install Rostr, drop your old journal file into the ~/.rostr/ folder, and the app will instantly rebuild your entire workspace.

🤝 Contributing

Contributions are welcome! If you have ideas for new reports, commands, or features:

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request.

License: MIT