terminal-second-brain 0.0.1

Terminal User Interface for Second Brain Todo Application

Terminal Second Brain - TUI

🧠 A modern Terminal User Interface for managing your todos with style and efficiency.

Features

✨ Modern TUI Interface

• Clean, responsive terminal interface built with Textual
• Keyboard and mouse navigation support
• Real-time status updates and notifications

📋 Todo Management

• View all todos with visual status indicators
• Add new todos with input validation
• Mark todos as completed with a single click
• Automatic refresh and real-time updates

🔗 API Integration

• Seamless integration with Spring Boot backend
• Connection health monitoring
• Error handling and user feedback
• Configurable API endpoint

Prerequisites

• Python 3.10 or higher
• Spring Boot Todo API running on http://localhost:8080

Installation

1. Install dependencies using uv:

uv sync

2. Or install manually with pip:

pip install textual httpx rich pydantic

Running the Application

1. Ensure your Spring Boot backend is running:

# In the main project directory
gradle bootRun

2. Start the TUI application:

# Using uv (recommended)
uv run main.py

# Or directly with Python
python main.py

Usage

Keyboard Shortcuts

Key	Action
q	Quit application
a	Add new todo
r	Refresh todo list
?	Show help
Esc	Cancel/Go back
Ctrl+S	Save (in forms)
Tab	Navigate controls
Enter	Activate selected item

Mouse Controls

• Click on a todo to select it
• Double-click to mark as complete (future feature)
• Use scroll wheel to navigate long lists

Visual Indicators

• ✅ Completed todos - Green checkmark
• ⭕ Pending todos - Yellow circle
• 🔄 Loading - Spinning indicator
• ❌ Errors - Red X with message

Configuration

The application can be configured through environment variables:

# API endpoint (default: http://localhost:8080)
export TODO_API_URL=http://your-api-server:8080

# Run the application
uv run main.py

Troubleshooting

Connection Issues

If you see a connection error:

1. Check Backend Status: Ensure Spring Boot app is running

curl http://localhost:8080/actuator/health

2. Verify API Endpoints: Test the API manually

curl http://localhost:8080/api/v1/todos

3. Check Port Conflicts: Ensure port 8080 is available

Common Issues

• Import Errors: Run uv sync to install dependencies
• API Timeout: Check network connectivity and backend performance
• Display Issues: Ensure terminal supports Unicode and colors

Development

Project Structure

tui/
├── main.py              # Main application entry point
├── api_client.py        # HTTP client for backend API
├── todo_list.py         # Todo list widget
├── add_todo_screen.py   # Add todo form screen
├── config.py            # Configuration and constants
├── pyproject.toml       # Project dependencies
└── README.md           # This file

Adding Features

The application is built with Textual widgets and follows a modular architecture:

1. New Screens: Add in separate files, register in SCREENS dict
2. New Widgets: Extend textual.widgets base classes
3. API Methods: Add to SyncTodoAPIClient class
4. Styling: Update CSS in main.py or create separate CSS file

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with the backend API
5. Submit a pull request

License

This project is part of the Terminal Second Brain application. See the main project LICENSE for details.