FreeTodo

English

简体中文

English

简体中文

Appearance

FreeTodo Installation Guide ​

Want to get started with FreeTodo quickly? Check out Quick Start Guide 🚀 ​

System Requirements ​

Before installing FreeTodo, please ensure your system meets the following requirements:

Operating System ​

  • Windows 10/11
  • macOS 10.14+

Software Dependencies ​

Backend:

  • Python 3.12
  • Git (for cloning repository)

Frontend:

  • Node.js 20+
  • pnpm package manager

Hardware Requirements ​

  • Memory: 4GB or more recommended
  • Hard Disk: At least 10GB available space
  • Processor: Multi-core processor supported
  • Optional: CUDA support (for GPU acceleration)

Installation Steps ​

1. Clone Project Repository ​

First, clone the FreeTodo project from GitHub:

bash
git clone https://github.com/FreeU-group/FreeTodo.git
cd FreeTodo

2. Install Dependencies ​

This project uses uv for fast and reliable dependency management.

Install uv:

bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Note: After installation, uv may not be immediately available in the current terminal. To activate it in the current session:

  • Windows (PowerShell): Run $env:Path = "$env:USERPROFILE\.local\bin;$env:Path" to refresh PATH
  • macOS/Linux: Run exec $SHELL to reinitialize your shell session, or restart your terminal

Alternatively, you can simply open a new terminal window and uv will be available automatically.

Install dependencies and sync environment:

bash
# Sync dependencies from pyproject.toml and uv.lock
uv sync

# Activate the virtual environment
# macOS/Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

3. Start the Backend Service ​

Note: On first run, the system will automatically create config.yaml from default_config.yaml if it doesn't exist. You can customize your settings by editing lifetrace/config/config.yaml.

Start the server:

bash
python -m lifetrace.server

Customize Prompts: If you want to modify AI prompts for different features, you can edit lifetrace/config/prompt.yaml.

The backend service will automatically find an available port starting from 8001 (or 8100 for build version). If the default port is occupied, it will automatically use the next available port and display the actual port in the console.

  • Default Backend Port: http://localhost:8001
  • API Documentation: The actual API docs URL will be displayed in the console (typically http://localhost:8001/docs)

4. Start the Frontend Service ​

The frontend is required to use FreeTodo. Start the frontend development server:

bash
cd free-todo-frontend

pnpm install
pnpm dev

The frontend development server will:

  • Automatically find an available port starting from 3001 (default port for development)
  • Automatically detect the running FreeTodo backend port by checking the /health endpoint
  • Set up API proxy to the detected backend port

The actual frontend URL and backend connection status will be displayed in the console. Once both services are running, open your browser and navigate to the displayed frontend URL (typically http://localhost:3001) to enjoy FreeTodo! 🎉

Note: If ports are occupied, both frontend and backend will automatically find the next available ports. The console will show the actual ports being used.

Next Steps ​

After installation, please see Usage Guide to learn how to use FreeTodo.