Orgflow

A modern Rust ecosystem for managing notes and tasks with a smooth, efficient workflow.

Orgflow consists of two main components:

orgflow - Core library for document management with support for tasks and notes
orgflow-tui - Terminal user interface for intuitive note and task management

🚀 Quick Start

Install the TUI Application

# Install from crates.io
cargo install orgflow-tui

# Run the application
orgflow-tui

Use the Library

Add to your Cargo.toml:

[dependencies]
orgflow = "0.1.0"

📋 Features

Orgflow Library (`orgflow`)

Document Management: Read, write, and manipulate structured documents
Task Handling: Create, manage, and track tasks with metadata
Note Support: Rich note creation with titles, content, and tags
Flexible Storage: Configurable file locations and formats
Rust API: Type-safe, memory-efficient document operations

Orgflow TUI (`orgflow-tui`)

Three-Tab Interface: Editor, Viewer, and Tasks views
Session Management: Automatic state persistence and recovery
Real-time Editing: Create and edit notes with immediate saving
Task Management: Visual task list with status tracking
Note Browser: Navigate through saved notes with metadata display
Keyboard-driven: Efficient navigation without mouse dependency
Cross-platform: Works on Linux, macOS, and Windows

🎯 Use Cases

Personal Knowledge Management: Organize notes, ideas, and research
Task Tracking: Manage todos, projects, and deadlines
Documentation: Create and maintain structured documentation
Note-taking: Capture thoughts with rich formatting and metadata
Productivity: Streamline workflow with keyboard-driven interface

📦 Components

Core Library: `orgflow`

The foundational library that provides:

use orgflow::{OrgDocument, Task, Note, Configuration};

// Load a document
let doc = OrgDocument::from("path/to/file.org")?;

// Create a task
let task = Task::with_today("Complete project documentation");

// Create a note
let note = Note::with("Meeting Notes".to_string(), vec![
    "Discussed project timeline".to_string(),
    "Next steps identified".to_string(),
]);

// Add to document and save
doc.push_task(task);
doc.push_note(note);
doc.to("path/to/file.org")?;

Terminal Interface: `orgflow`

A beautiful, responsive terminal interface featuring:

Editor Tab

Create notes with titles and rich content
Quick task entry with Ctrl+T
Auto-save functionality with Ctrl+S
Smart field navigation
Draft content automatically preserved between sessions

Viewer Tab

Browse all saved notes
Split-panel layout (content + metadata)
Arrow key navigation
Rich metadata display

Tasks Tab

Visual task list with status indicators
Detailed task information panel
Highlighted selection with underlines
Priority and date tracking

Navigation

Streamlined Tab Switching: Single Ctrl+R key cycles through all tabs (Editor → Viewer → Tasks)
Session Recovery: All navigation state preserved between sessions
Keyboard-driven: Efficient workflow without mouse dependency

📖 Documentation

Installation

From Crates.io

# Install the TUI application
cargo install orgflow-tui

# Use the library in your project
cargo add orgflow

From Source

git clone https://github.com/ucyo/orgflow
cd orgflow

# Build everything
cargo build --release

# Build just the library
cargo build -p orgflow --release

# Build just the TUI
cargo build -p orgflow-tui --release

Configuration

Set your preferred storage location:

export ORGFLOW_BASEFOLDER=/path/to/your/notes

Default location: /home/sweet/home

Session Management

Orgflow TUI automatically manages your session state:

Automatic Saving: Session state is saved every 500ms after changes or every 50 keystrokes
Draft Recovery: Unsaved notes, tasks, and scratchpad content are preserved between sessions
UI State Persistence: Current tab, focus, and selection positions are restored on startup
Session File: State is stored in session.json in your base folder
No Data Loss: Even if the application crashes, your work is automatically recovered

Session includes:

Current tab and focus position
Unsaved draft content (title, note content, scratchpad)
Navigation state (selected note/task indices)
UI preferences (scratchpad visibility)

The session file is automatically created and managed - no manual intervention required.

File Format

Orgflow uses a structured text format:

## Tasks
[ ] Implement new feature
[x] 2024-01-15 Write documentation
(A) 2024-01-10 High priority task @work +project

## Notes

### Meeting Notes
> cre:2024-01-15 mod:2024-01-15 guid:abc123... @meeting +work
Discussed quarterly objectives and timeline.

Next steps:
- Review current progress
- Set new milestones
- Schedule follow-up meeting

### Project Ideas
> cre:2024-01-10 mod:2024-01-12 guid:def456... @ideas +innovation
Ideas for improving the user experience:
1. Better navigation
2. Faster search
3. Mobile support

🎮 Usage Examples

TUI Application

# Start the application
orgflow

# Keyboard shortcuts:
# Ctrl+R - Cycle through tabs (Editor → Viewer → Tasks → Editor)
# Ctrl+T - Quick task entry    Ctrl+S - Save note
# Esc - Exit (session auto-saved)    Tab - Navigate fields
# Session state automatically preserved on every keystroke

Library Usage

use orgflow::{Configuration, OrgDocument, Task, Note};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Get base folder from environment or use default
    let base_folder = Configuration::basefolder();
    let file_path = format!("{}/refile.org", base_folder);

    // Load existing document or create new
    let mut doc = OrgDocument::from(&file_path)
        .unwrap_or_else(|_| OrgDocument::default());

    // Add a new task
    let task = Task::with_today("Review pull requests");
    doc.push_task(task);

    // Add a new note
    let note = Note::with(
        "Daily Standup".to_string(),
        vec![
            "Team discussed current sprint progress".to_string(),
            "Identified blockers and solutions".to_string(),
            "Planned next steps for the week".to_string(),
        ]
    );
    doc.push_note(note);

    // Save the document
    doc.to(&file_path)?;

    println!("Document saved with {} tasks and {} notes",
             doc.len().0, doc.len().1);

    Ok(())
}

🛠️ Development

Prerequisites

Rust 1.70+ (edition 2024)
Git

Setup

# Clone the repository
git clone https://github.com/ucyo/orgflow
cd orgflow

# Build the workspace
cargo build

# Run tests
cargo test

# Run the TUI in development
cargo run -p orgflow-tui

# Run the CLI tool
cargo run -p orgflow

Project Structure

orgflow/
├── orgflow/           # Core library
│   ├── src/
│   │   ├── lib/       # Library modules
│   │   └── main.rs    # CLI binary
│   └── tests/         # Integration tests
├── orgflow-tui/       # Terminal interface
│   └── src/
│       ├── main.rs    # TUI application
│       └── session.rs # Session management
├── Cargo.toml         # Workspace configuration
└── README.md          # This file

Testing

# Run all tests
cargo test

# Test specific package
cargo test -p orgflow
cargo test -p orgflow-tui

# Run with output
cargo test -- --nocapture

Linting and Formatting

# Format code
cargo fmt

# Run clippy lints
cargo clippy

# Check for issues
cargo check

🎨 Interface Preview

Editor Tab

┌─────────────────────────────────────────────────────────────┐
│        Orgflow - Editor | Viewer | Tasks (Ctrl+R to switch) │
├─────────────────────────────────────────────────────────────┤
│ Title                                                       │
│ Weekly Planning Session                                     │
├─────────────────────────────────────────────────────────────┤
│ Content                                                     │
│ ## Agenda                                                   │
│ 1. Review last week's accomplishments                      │
│ 2. Set priorities for upcoming week                        │
│ 3. Identify potential blockers                             │
│                                                             │
│ ## Action Items                                             │
│ - Schedule team review meeting                              │
│ - Update project documentation                              │
│                                                             │
│ Quit <ESC> Switch <SHIFT>+<TAB> Save <CTRL>+<S> Cycle <CTRL>+<R> │
└─────────────────────────────────────────────────────────────┘

Tasks Tab

┌─────────────────────────────────────────────────────────────┐
│        Orgflow - Editor | Viewer | Tasks (Ctrl+R to switch) │
├──────────────────────────────────────┬──────────────────────┤
│ Tasks (5 total)                      │ Task Details         │
│ ► [ ] Review pull request #123       │ Status: Pending      │
│   [x] Update documentation           │ Priority: High       │
│   [ ] Fix login bug                  │ Created: 2024-01-15  │
│   [ ] Plan next sprint               │ Completed: N/A       │
│   [x] Team standup meeting           │ Tags: @dev +urgent   │
│                                      │                      │
│                                      │ Description:         │
│                                      │ Review pull request  │
│                                      │ #123 for the new     │
│                                      │ authentication...    │
│ Navigate <↑↓> Quit <ESC> Switch <CTRL>+<R>                  │
└──────────────────────────────────────┴──────────────────────┘

Session Management: All UI state and draft content is automatically preserved in session.json. Exit anytime with ESC and resume exactly where you left off!

🤝 Contributing

We welcome contributions! Here's how to get started:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes: Follow the existing code style
Add tests: Ensure your changes are well-tested
Run tests: cargo test
Submit a PR: Create a pull request with a clear description

Contribution Guidelines

Follow Rust conventions and idioms
Add tests for new functionality
Update documentation as needed
Keep commits focused and atomic
Write clear commit messages

Areas for Contribution

Features: New functionality for the library or TUI
Performance: Optimization opportunities
Documentation: Improve examples and guides
Testing: Increase test coverage
UI/UX: Enhance the terminal interface
Bug fixes: Address reported issues

📄 License

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

🙏 Acknowledgments

ratatui - Excellent TUI framework
org-mode - Inspiration for the document format
The Rust community for amazing tools and libraries

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: docs.rs/orgflow

Start organizing your workflow with Orgflow today! 🚀

Made with ❤️ in Rust

orgflow 0.2.0

Orgflow

🚀 Quick Start

Install the TUI Application

Use the Library

📋 Features

Orgflow Library (orgflow)

Orgflow TUI (orgflow-tui)

🎯 Use Cases

📦 Components

Core Library: orgflow

Terminal Interface: orgflow

Editor Tab

Viewer Tab

Tasks Tab

Navigation

📖 Documentation

Installation

From Crates.io

From Source

Configuration

Session Management

File Format

🎮 Usage Examples

TUI Application

Library Usage

🛠️ Development

Prerequisites

Setup

Project Structure

Testing

Linting and Formatting

🎨 Interface Preview

Editor Tab

Tasks Tab

🤝 Contributing

Contribution Guidelines

Areas for Contribution

📄 License

🙏 Acknowledgments

📞 Support

Orgflow Library (`orgflow`)

Orgflow TUI (`orgflow-tui`)

Core Library: `orgflow`

Terminal Interface: `orgflow`