# Notulist - Record notes from your terminal

Notulist is a CLI-based note taking application for terminal power-users. You
can now easily record quick notes via the terminal or your favorite editor.
After collecting notes, you can let AI organize them for you into projects, and
your journal automatically.

The application features a journal section that records daily and monthly
summaries for you based on the notes collected so you always have a clear
overview of what happened in the past days or weeks. In addition to the journal,
you can organize notes into projects or archive them by date so you can refer to
them at any point.

I made notulist in such a way that you can link it to Claude Code and let your
agent do the note taking for you. Claude Code is also used to organize the notes
based on customizable instructions stored in the application's configuration
directory.

## Requirements

- Python 3.14+
- Claude Code

## Installation

```sh
pip install notulist
```

## Usage

### Initialize a notes repository

Before you can take notes, you should initialize a directory as the notes repository for the application.
First, create a new directory for your notes, and then use the following command to initialize the new directory
as a notes repository:

```sh
notulist init
```

This creates the following directory structure:

```
today/           # inbox for today's notes
journal/daily/   # daily journal entries
journal/monthly/ # monthly journal entries
projects/        # project-specific notes
archive/         # archived notes organized by date
```

You can synchronize the directory using Git. Use `git init` in the notes repository
to initialize it as a Git repository, and then commit and push as normal.

Make sure to review the `config.toml` file and configure your editor of choice.
You can find the configuration file in `~/.config/notulist/config.toml` on
Mac/Linux and in `%USERPROFILE%/.notulist/config.toml` on Windows. Refer to [the
configuration section](#configuration) for more details on the configuration
format for the application.

### Create a note

The application offers two ways to create notes. You can write a note inline:

```sh
notulist note -m "Remember to review the API design doc"
```

Claude Code will automatically generate a title for your note so you can find it
again. Add the `-t <title>` option to provide a title yourself. You can also
create a new note using a text editor of your choice.

```sh
uv run notulist note
```

### Manage projects

The application can organize notes into projects for you automatically.
You can create a new project with this command:

```sh
notulist projects create -n "API Redesign" -d "Notes on the v2 API migration"
```

Or omit `-d` to open the configured editor for a longer description.

You can list all commands with the following command:

```sh
notulist projects ls
```

You can remove a project when you no longer need it. We'll ask for confirmation if it contains notes.

```sh
notulist projects remove -n api-redesign
```

### Organize notes

After collecting notes, you can use the following command to organize the notes into projects and your journal:

```sh
notulist organize
```

This command:

1. Generates **daily summaries** in `journal/daily/` for each date found in `today/`.
2. Generates **monthly summaries** in `journal/monthly/`.
3. **Classifies** each note into a matching project (moved to `projects/<slug>/`) or archives it (moved to `archive/<date>/`).

Summaries and classification are powered by Claude Code.

### Configuration

The application reads settings from `~/.config/notulist/config.toml` (Linux/macOS) or `~/.notulist/config.toml` (Windows), and from environment variables. Make sure to review the settings after running `notulist init` to make sure the application uses the editor
you'd like to use.

Available settings:

| Key          | Default                                 | Description                        |
| ------------ | --------------------------------------- | ---------------------------------- |
| `editor`     | `vi` (Linux/macOS), `notepad` (Windows) | Editor command for composing notes |
| `repository` | `~/notes`                               | Path to the notes repository       |

Example `config.toml`:

```toml
editor = "nvim"
repository = "/home/user/my-notes"
```

### Prompt customization

You can customize the prompts we use for organizing your notes by editing the
files in `~/.config/notulist/prompts` on Mac/Linux or
`%USERPROFILE%/.notulist/prompts` on Windows.
