tabmind 0.2.1
TabMind - Smart Tab Manager with AI assistance and productivity features
License: MIT
Requires Python: >=3.8
Keywords: cli, tab-manager, productivity, ai, due-dates

# TabMind - Smart Tab Manager with AI Assistance

A powerful Python CLI tool to manage your browser tabs, track why you opened them, set deadlines, and get AI-powered productivity reminders using GitHub Copilot.

## Features

- **Save Tabs**: Quickly save URLs with context about why you opened them
- **Auto-Fetch Titles**: Automatically retrieve page titles from URLs
- **Due Dates**: Set deadlines for your tabs to stay on track
- **Mark as Done**: Track which tabs you've completed
- **Statistics**: View analytics about your saved tabs
- **Review Tabs**: View all saved tabs with their reasons, titles, due dates, and status
- **AI Prompts**: Generate smart motivation prompts for your pending tasks using GitHub Copilot
- **Simple CLI**: Easy-to-use command-line interface
- **Persistent Storage**: Tabs are saved locally in JSON format
- **Python Library**: Use TabMind as a library in your own Python projects

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage](#usage)
  - [CLI Commands](#cli-commands)
  - [Using as a Python Library](#using-as-a-python-library)
- [Requirements](#requirements)
- [Project Structure](#project-structure)
- [Contributing](#contributing)
- [License](#license)

## Installation

### From Source (Development)

```bash
git clone https://github.com/IshikaBanga26/TabMind.git
cd TabMind
pip install -e .
```

### From PyPI (Once Published)

```bash
pip install tabmind
```

## Quick Start

### Add a Tab

```bash
tabmind add https://example.com
# When prompted, enter why you opened this link
# The page title will be fetched automatically
```

### Add a Tab with Due Date

```bash
tabmind add https://example.com --due-date 2024-12-31
# or
tabmind add https://example.com -d 2024-12-31
```


### Review Your Tabs

```bash
tabmind review
```

### Mark a Tab as Done

```bash
tabmind mark-done 1
# Marks tab #1 as completed
```

### Set a Due Date

```bash
tabmind due-date 2 2024-12-25
# Sets a due date for tab #2 (format: YYYY-MM-DD)
```

### View Statistics

```bash
tabmind stats
```
Shows total tabs, completed count, pending count, and tabs with due dates.

### Generate AI Prompts

```bash
tabmind ai-prompt
```

This will output GitHub Copilot prompts for pending tabs that you can run manually:

```bash
gh copilot -p "Your generated prompt here"
```

## Usage

### CLI Commands

#### `tabmind add <URL> [OPTIONS]`

Save a new tab with a reason for opening it. Optionally set a due date.

```bash
$ tabmind add https://github.com
Why did you open this link? Learn Git workflows
✓ Tab saved successfully!

$ tabmind add https://python.org --due-date 2024-12-31
Why did you open this link? Check Python documentation
✓ Tab saved successfully!
```

#### `tabmind review`

Display all saved tabs with their details including titles, due dates, and status.

```bash
$ tabmind review

[1] ⏳ Pending | Due: 2024-12-31
    Title: GitHub: Where the world builds software
    URL: https://github.com
    Reason: Learn Git workflows
    Added: 2026-02-14 19:18:23

[2] ✓ Done
    Title: Welcome to Python.org
    URL: https://python.org
    Reason: Check Python documentation
    Added: 2026-02-14 19:20:15
```

#### `tabmind mark-done <TAB_NUMBER>`

Mark a specific tab as completed.

```bash
$ tabmind mark-done 1
✓ Tab 1 marked as done!
```

#### `tabmind due-date <TAB_NUMBER> <DATE>`

Set or update a due date for a tab (format: YYYY-MM-DD).

```bash
$ tabmind due-date 3 2024-12-25
✓ Due date for Tab 3 set to 2024-12-25
```

#### `tabmind stats`

Display statistics about your saved tabs.

```bash
$ tabmind stats

TabMind Statistics
========================================
Total Tabs:      10
Completed:       4 
Pending:         6 
With Due Date:   5 
========================================
```

#### `tabmind ai-prompt`

Generate AI-powered productivity reminders for pending tabs.

```bash
$ tabmind ai-prompt

-----------------------------------
Run this command in your terminal:

gh copilot -p "You are a productivity assistant.

The user saved this link:
URL: https://github.com
Reason: Learn Git workflows
Date Added: 2026-02-14 19:18:23

Write a short motivational reminder asking if they want to continue this task.
Keep it under 3 lines."

-----------------------------------
```

### Using as a Python Library

Import TabMind functions in your own Python projects:

```python
from storage import add_tab, get_tabs, mark_tab_done, set_due_date, get_stats, fetch_page_title

# Add a tab with auto-fetched title
add_tab("https://example.com", "Research machine learning")

# Add a tab with due date
add_tab("https://github.com", "Learn Git workflows", due_date="2024-12-31")

# Get all saved tabs
tabs = get_tabs()
for tab in tabs:
    print(f"Title: {tab['title']}")
    print(f"URL: {tab['url']}")
    print(f"Reason: {tab['reason']}")
    print(f"Status: {'Done' if tab['completed'] else 'Pending'}")
    print(f"Due: {tab.get('due_date', 'N/A')}")

# Mark a tab as done
mark_tab_done(0)

# Set a due date
set_due_date(1, "2024-12-25")

# Get statistics
stats = get_stats()
print(f"Total: {stats['total']}, Completed: {stats['completed']}")

# Fetch page title
title = fetch_page_title("https://example.com")
print(f"Page title: {title}")
```

## Requirements

- Python 3.8+
- `click` >= 8.0.0 (for CLI functionality)
- `requests` >= 2.28.0 (for fetching page titles)
- `beautifulsoup4` >= 4.11.0 (for parsing HTML)
- (Optional) GitHub CLI with Copilot access (for AI features)

### Install Requirements

```bash
pip install -r requirements.txt
```

## Project Structure

```
TabMind/
├── main.py                 # CLI entry point and commands
├── storage.py              # Tab storage, retrieval, and title fetching
├── ai_helper.py            # GitHub Copilot integration
├── tabs.json               # Local storage for tabs (auto-generated)
├── setup.py                # Package setup configuration
├── pyproject.toml          # Modern Python packaging config
├── requirements.txt        # Project dependencies
├── MANIFEST.in             # Additional files to include in distribution
├── LICENSE                 # MIT License
└── README.md               # This file
```

## Data Storage

Tabs are stored locally in a `tabs.json` file in your current directory. Each tab entry contains:

```json
{
  "url": "https://example.com",
  "title": "Example Domain",
  "reason": "Why you opened this link",
  "date_added": "2026-02-14 19:18:23",
  "due_date": "2024-12-31",
  "completed": false
}
```

**Note**: The storage location can be customized by modifying the `FILE_NAME` variable in `storage.py`.

## Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/IshikaBanga26/TabMind.git
cd TabMind

# Create a virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install in development mode
pip install -e .

# Install development dependencies
pip install -r requirements.txt
```

### Testing Commands

```bash
# Test adding a tab
tabmind add https://test.com

# Test reviewing tabs
tabmind review

# Test AI prompt generation (requires GitHub Copilot)
tabmind ai-prompt
```

## Contributing

Contributions are welcome! Here's how you can help:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Make your changes
4. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
5. Push to the branch (`git push origin feature/AmazingFeature`)
6. Open a Pull Request

### Areas for Contribution

- Add unit tests
- Improve error handling
- Add support for additional data formats (CSV, SQLite)
- Implement cloud synchronization
- Add more AI integration options
- Improve documentation

## Reporting Issues

Found a bug? Please open an issue on the [GitHub Issues](https://github.com/IshikaBanga26/TabMind/issues) page with:

- Description of the bug
- Steps to reproduce
- Expected behavior
- Your environment (OS, Python version)

## Future Features

- [ ] Web-based dashboard for viewing tabs
- [ ] Browser extension for quick tab saving
- [ ] Cloud synchronization
- [ ] Tab categorization and tagging
- [ ] Advanced analytics and insights
- [ ] Integration with more AI services
- [ ] Export to various formats (PDF, CSV, HTML)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Author

Your Name - [Ishika Banga](https://github.com/IshikaBanga26)

## Acknowledgments

- Built with [Click](https://click.palletsprojects.com/) - Python CLI framework
- GitHub Copilot integration for AI assistance
- Inspired by productivity and tab management tools

## Contact & Support

For questions or support:

- Open an issue on [GitHub](https://github.com/IshikaBanga26/TabMind/issues)
- Email: your.email@example.com
- Check the [Discussions](https://github.com/IshikaBanga26/TabMind/discussions) page

---

**Happy tab management!**