xnoted 0.1.5

A powerful terminal-based task and note management application built with Python and Textual. Organize your tasks and notes into projects with a modern, keyboard-driven interface.

 █████ █████ ██████   █████           █████                 █████
░░███ ░░███ ░░██████ ░░███           ░░███                 ░░███ 
 ░░███ ███   ░███░███ ░███   ██████  ███████    ██████   ███████ 
  ░░█████    ░███░░███░███  ███░░███░░░███░    ███░░███ ███░░███ 
   ███░███   ░███ ░░██████ ░███ ░███  ░███    ░███████ ░███ ░███ 
  ███ ░░███  ░███  ░░█████ ░███ ░███  ░███ ███░███░░░  ░███ ░███ 
 █████ █████ █████  ░░█████░░██████   ░░█████ ░░██████ ░░████████
░░░░░ ░░░░░ ░░░░░    ░░░░░  ░░░░░░     ░░░░░   ░░░░░░   ░░░░░░░░ 

A powerful terminal-based task and note management application built with Python and Textual. Organize your tasks and notes into projects with a modern, keyboard-driven interface.

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 6 different states: Not started, Completed, 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

Requirements

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

Installation

1. Using pip

pip install xnoted

2. Using pipx

pipx install xnoted

Development

1. Clone the repository:

git clone [e-mail]:babucarr32/xnoted.git
cd xnoted

2. Install dependencies using uv:

uv sync

Or using pip:

pip install -e .

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

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

Shortcut	Action	Description
Ctrl+N	Create new task	Opens modal to create a new task in current project
Ctrl+B	Create new project	Opens modal to create a new project
Ctrl+L	Select project	Opens project selector to switch between projects
Ctrl+O	Import/Export	Opens modal to import or export projects
Ctrl+R	Show readme	Displays the README in the content panel
Ctrl+D	Scroll down	Scrolls the content panel down
Ctrl+U	Scroll up	Scrolls the content panel up

Task List Navigation

Shortcut	Action	Description
j	Move down	Move cursor down in task list (Vim-style)
k	Move up	Move cursor up in task list (Vim-style)
Enter	Select task	View the selected task's content
e	Edit task	Edit the highlighted task
d	Delete task	Delete the highlighted task (with confirmation)
←	Previous status	Cycle task status backward
→	Next status	Cycle task status forward
/	Search	Search the tasks

Task/Project Editor Shortcuts

Shortcut	Action	Description
Ctrl+S	Save	Save the current task or project
Esc	Cancel	Close modal without saving

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",
      "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 (app.py): Main application class that handles:

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

• Database (src/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/screens/): Modal overlays for user interactions:

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

• Components (src/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", "note", "general")
• 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\

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.

License

MIT