📖 Overview

tmmpr is a Linux terminal application that lets you create, organize, and connect notes on an infinite canvas. Think of it as a digital whiteboard in your terminal where you can freely place notes anywhere and draw connections between them.

The application is entirely keyboard-driven, offering efficient navigation and control through vim-inspired keybindings. Perfect for brainstorming, project planning, or organizing complex ideas.

Current State: The core functionality works well—you can create maps, add notes, draw connections, and save your work. However, this is an active work in progress with planned improvements to code quality, feature completeness, and test coverage. See Project Status & Roadmap below.

✨ Features

• 🗺️ Infinite Canvas - Place notes anywhere on a positive coordinate system (0,0 to infinity)
• 🔗 Visual Connections - Draw and manage connections between notes with customizable colors and sides
• ⌨️ Vim-Inspired Navigation - Efficient keyboard-driven interface with hjkl movement
• 🎯 Multiple Modes:
  • Normal Mode - viewport navigation and general commands
  • Visual Mode - select and manage notes
  • Visual (Move) Mode - reposition notes on the canvas
  • Visual (Connection) Mode - manage note connections
  • Edit Mode - text editing with optional modal (vim-inspired) editing
• 💾 Auto-Save - Configurable auto-save intervals to prevent data loss
• 🔄 Backup System - Automatic backups with customizable intervals (daily, weekly, etc.)
• 🎨 Customizable - Color-coded notes and connections, adjustable settings

🧪 Testing

This project maintains ~54% test coverage, focusing on business logic, state management, and input handling. The terminal UI layer (/src/ui/) is validated through manual testing and real-world usage rather than automated tests, as UI testing in terminal applications often provides limited value relative to the maintenance cost.

You can find extensive test suites throughout the codebase:

• State management tests: /src/states/*/tests/
• Input handling tests: /src/input/map/tests/
• Utility function tests: /src/utils/tests/

⚠️ Known Testing Issue: Some tests currently modify the actual configuration file (~/.config/tmmpr/settings.json), resetting it to defaults during test execution. This is a known issue that needs to be resolved by properly isolating test environments. Be aware of this if you run the test suite while actively using the application.

📸 Previews

🚀 Installation

From Crates.io (Recommended)

cargo install tmmpr

From Source

git clone https://github.com/tanciaku/tmmpr.git
cd tmmpr
cargo build --release
# Binary will be at ./target/release/tmmpr

System Requirements

• OS: Linux (primary support)
• Rust: 1.85.0 or higher (requires Rust 2024 edition)
• Terminal: Any terminal emulator with Unicode support

💻 Usage

Simply run the application from your terminal:

tmmpr

You'll be greeted with a start screen where you can:

• Create a new mind map
• Open an existing map file
• Access recent files

⌨️ Keybindings

📖 View In-App Help: Press ? or F1 from the Map Screen to open the interactive help pages with all keybindings and detailed explanations.

💡 Zooming: Since tmmpr runs in your terminal, zooming is controlled by adjusting your terminal emulator's font size. Most terminals use Ctrl + + / Ctrl + - (or Cmd + + / Cmd + - on macOS). The specific shortcuts vary by terminal emulator (GNOME Terminal, Konsole, iTerm2, Alacritty, etc.), so consult your terminal's documentation if needed.

📊 Project Status & Roadmap

Current State

The application is fully functional for its core purpose - creating, organizing, and managing mind maps in the terminal. Most features work as intended.

🚧 Known Limitations

Edit Mode (Vim-style):

• Normal mode is very limited compared to vim
• No Visual mode within the text editor
• Block cursor placement issues in Normal mode

Code Quality:

• Code structure and approaches need refactoring throughout the application
• Missing or incomplete inline and documentation comments
• Some logic is not easily testable due to hardcoded paths
• Some test suites modifies actual config files (~/.config/tmmpr/settings.json) during execution

🗺️ Roadmap

Short-term (Before Major Feature Work):

• Refactor code structure and improve modularity
• Fix test suite to avoid modifying real configuration files
• Decouple hardcoded paths to make logic more testable
• Add comprehensive inline and doc comments
• Fix block cursor placement in Edit Normal mode
• Improve Edit Mode functionality:
  • Add Visual Mode for text selection within the editor
  • Expand Normal mode commands (vim motions and operators)
  • Better text editing operations (copy, paste, undo/redo)

Long-term (Future Features):

• Adding images functionality (planned after addressing above issues)

Your feedback on priorities is welcome! Open an issue or discussion to share suggestions.

⚙️ Settings

Access settings by pressing o from the map screen. Configurable options include:

• Map Changes Auto Save Interval - Automatic save frequency (or disable)
• Backups Interval - How often to create backups when opening files
• Runtime Backups Interval - Create backups during long editing sessions
• Default Connection Sides - Default start/end sides for connections
• Modal Edit Mode - Enable vim-inspired modal editing (note: currently limited)

🛠️ Troubleshooting

Issue: Terminal display looks wrong

• Ensure your terminal supports Unicode characters
• Try resizing your terminal window

Issue: Files not saving

• Check file permissions in your working directory
• Verify disk space availability

Issue: Keybindings not working

• Check that your terminal is not intercepting key combinations
• Some terminals may not support all key combinations

🤝 Contributing

Contributions, feedback, and suggestions are highly welcome! This project is actively being improved, and your input can help shape its direction.

Ways to contribute:

• 🐛 Report bugs - Open an issue with details about what you encountered
• 💡 Suggest features - Share ideas for new functionality or improvements
• 🔧 Submit pull requests - Code improvements, bug fixes, or documentation updates
• 📝 Improve documentation - Help clarify usage, add examples, or improve comments
• 🧪 Testing feedback - Report issues with specific terminals, edge cases, or workflows

Areas needing help:

• Code refactoring and structural improvements
• Expanding test coverage with proper isolation
• Documentation and inline comments
• Vim mode improvements in the text editor

No contribution is too small—whether it's fixing a typo or tackling a major refactor!

📝 License

This project is licensed under the MIT License

🙏 Acknowledgements

Concept inspired by: Obsidian Canvas

Built with ❤️ using Rust 🦀 and Ratatui 🐀