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

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
u	Unlock tasks	Unlock all locked tasks
ctrl+p	Command pallette	Display command pallette
s	Command pallette	Display command pallette
L	Create password / Edit password	Create or edit password

Task List Navigation

Shortcut	Action	Description
j	Move down	Move cursor down in task list
k	Move up	Move cursor up in task list
enter	Select task	View the selected task's content
e	Edit task	Edit the highlighted task
m	Move task	Move the highlighted task
c	Copy task	Copy the highlighted task
l	Lock task / Permanently unlock task	Lock or permanently unlock 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

Project List Navigation

Shortcut	Action	Description
j	Move down	Move cursor down in task list
k	Move up	Move cursor up in task list
e	Edit project	Edit the highlighted project
d	Delete project	Delete the highlighted project (with confirmation)

Copy Task List Navigation

Shortcut	Action	Description
j	Move down	Move cursor down in copy task list
k	Move up	Move cursor up in copy task list

Form(s) Shortcuts

Shortcut	Action	Description
enter	Save	Save the current changes
escape	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",
      "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