xnoted 0.2.4

A powerful terminal-based task and note management application built with Python and Textual.

Features

• Project-Based Organization: Group related tasks and notes into separate projects with custom titles and descriptions
• Task Management:
  • Create, edit, and delete tasks with titles and markdown content
  • Track task status with 5 different states: Not started, In progress, Under review, Done, and Canceled
  • Search tasks in real-time as you type
  • Visual status indicators (○, ◐, ◎, ✓, ✗)
• Rich Text Support: Write task content in Markdown with syntax highlighting
• Project Import/Export: Share and backup projects across systems
• Keyboard-Driven Interface: Navigate and manage tasks efficiently without touching the mouse
• Persistent Storage: SQLite database ensures your data is saved automatically
• Modern Terminal UI: Beautiful interface powered by Textual framework

Installation

1. Using pip

pip install xnoted

2. Using pipx

pipx install xnoted

Requirements

• Python >= 3.11
• Dependencies:
  • textual >= 6.6.0
  • textual-dev >= 1.8.0

Development

1. Clone the repository:

git clone git@github.com:babucarr32/xnoted.git
cd xnoted

2. Install dependencies using uv:

uv sync

Or using pip:

pip install -e .

Or using requirements.txt:

pip install -r requirements.txt

Usage

Starting the Application

1. Activate the virtual environment:

macOS/Linux (Bash/Zsh):

source .venv/bin/activate

Windows (Command Prompt):

.venv\Scripts\activate.bat

2. Run the application:

textual run --dev main.py

Or for production use:

python main.py

Running in Development Mode

Textual provides excellent development tools:

# Run with live reload and dev console
textual run --dev main.py

# Open the development console in another terminal
textual console

The dev console shows real-time logs and application state for debugging.

Build

1. Install hatch
2. To build your project with Hatch, change to the directory containing your pyproject.toml and run the hatch build subcommand:

cd textual-calculator
hatch build

3. The output will be in the dist folder

For more info see Package with Hatch

To install the local build

pipx install --force .

or

pip install --force .

Quick Start Guide

1. First Launch: The app creates a default project automatically
2. Create a Task: Press Ctrl+n to open the task creation modal
3. Navigate Tasks: Use j and k to move up and down the task list
4. View Task Content: Select a task with Enter to view its content in the right panel
5. Edit a Task: Highlight a task and press e to edit it
6. Change Status: Use arrow keys (←/→) to cycle through task statuses
7. Create Projects: Press Ctrl+b to create new projects
8. Switch Projects: Press Ctrl+l to select a different project

Keyboard Shortcuts

Global Application Shortcuts

Task List Navigation

Project List Navigation

Copy Task List Navigation

Form(s) Shortcuts

Task Status Indicators

• ○ Not started - Task hasn't been started yet
• ◐ In progress - Task is actively being worked on
• ◎ Under review - Task is waiting for review
• ✓ Done - Task is verified complete
• ✗ Canceled - Task was canceled or won't be done

Import Project(s)

Project data structure sample

{
  "version": "1.0",
  "exported_at": "2026-01-18T14:30:00.000000",
  "project": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "title": "Website Redesign",
    "description": "Complete redesign of company website with modern UI/UX",
    "type": "tasks",
    "createdAt": "2025-12-15 10:00:00"
  },
  "tasks": [
    {
      "id": "task-001-uuid-1234",
      "title": "Research competitor websites",
      "content": "Analyze top 5 competitor websites and document design patterns, user flows, and features. Focus on:\n- Navigation structure\n- Color schemes\n- Typography choices\n- Mobile responsiveness\n- Accessibility features",
      "is_protected": 1,
      "status": 1,
      "createdAt": "2025-12-15 10:15:00"
    }
  ],
  "task_count": 8
}
  

Development

Architecture Overview

xNoted is built with Textual, a modern Python framework for building terminal user interfaces. The app follows a component-based architecture:

Core Components

• XNotedApp (src/xnoted/app.py): Main application class that handles:

  • Global keyboard bindings
  • Screen navigation and modal management
  • Database initialization

• Database (src/xnoted/utils/database.py): SQLite wrapper providing:

  • Project and task CRUD operations
  • Automatic schema initialization
  • Current project context management
  • Default project creation on first run

• Screens (src/xnoted/screens/): Modal overlays for user interactions:

  • Task creation and editing
  • Project creation and selection
  • Import/export functionality
  • Confirmation dialogs

• Components (src/xnoted/components/): Reusable UI building blocks:

  • Task list with search and navigation
  • Markdown content viewer
  • Form inputs for tasks and projects

Data Model

The SQLite database contains two main tables:

Projects:

• id (TEXT, PRIMARY KEY): Unique project identifier
• title (TEXT): Project name
• description (TEXT): Project description
• type (TEXT): Project type (e.g., "task", "other")
• createdAt (TEXT): Creation timestamp

Tasks:

• id (TEXT, PRIMARY KEY): Unique task identifier
• project_id (TEXT, FOREIGN KEY): Reference to parent project
• title (TEXT): Task title
• content (TEXT): Task content in Markdown
• status (INTEGER): Status index (0-5)
• createdAt (TEXT): Creation timestamp

Database Path

• Linux: ~/.local/share/xnoted/
• macOS: ~/Library/Application Support/xnoted/
• Windows: C:\Users\YourName\AppData\Roaming\xnoted\

Logs Path

• Linux: ~/.local/share/xnoted/log.txt
• macOS: ~/Library/Application Support/xnoted/log.txt
• Windows: C:\Users\YourName\AppData\Roaming\xnoted\log.txt

License

MIT