Clutter

• GitHub repo: https://github.com/sharimot/clutter
• Use cases:
  • Notebook
  • Task manager
  • Calendar
  • File manager
  • Diary
  • Bookmark
• Disrupting:
  • Notion
  • Evernote
  • Obsidian
  • Roam Research
  • Todoist
  • etc.

Installation

1. Requirements:
   • Mac or PC. (Phones and tablets are not supported.)
   • python3
   • pip
2. Create clutter.txt somewhere.
   • This is a plain text file used to store app data.
3. Clone the repository from GitHub:

   git clone https://github.com/sharimot/clutter

4. Change into the directory:

   cd clutter

5. Install dependencies:

   python3 -m pip install -r requirements.txt

6. Run Clutter:

   python3 clutter.py /path/to/clutter.txt

7. Open the browser and access Clutter at http://localhost:12224/.

   12224 == int(hashlib.sha256('clutter'.encode('utf-8')).hexdigest()[:4], 16)

   It is possible to specify a different port number (e.g., 9999):

   python3 clutter.py /path/to/clutter.txt 9999

Manual

• Add:
  1. Click on the invisible input field located in the second row.
     • The input field is indicated by the + sign.
  2. Type a text to add. Line breaks are not allowed.
  3. Press the Enter key.
     • The timestamp is automatically included in the format yyyymmddHHMMSS.
• Edit:
  1. Click on the - button preceding the item to edit.
  2. Make necessary changes to it.
  3. Press the Enter key to save the edits.
• Find:
  • To search for items, use the invisible input field in the top row.
    • The input field is indicated by the = sign.
  • Only items that contain the search string are shown.
    • The search is case-insensitive (i.e., the search results for hello and hElLo are identical).
  • To search for items that contain multiple strings (e.g., hello and world), type both strings separated by a space (e.g., hello world).
  • To search for items that contain a specific phrase (e.g., hello world), replace the space with [space].
    • When the query is hello[space]world, items that contain hello world (with a space between hello and world) are shown.
  • To search for items that do not contain a specific string, use the N operator.
    • When the query is hello Nworld, items that contain hello but do not contain world are shown.
  • The number of items that match the query is shown in the top left corner.
    • Clutter displays a maximum of 1000 items.
    • To view old items, include the year (in the format yyyy) in the query.
• Sort:
  • Use the A or D prefixes before the keywords.
    • A stands for ascending order.
    • D stands for descending order.
  • The sorting is based on the string after the keyword prefixed by A or D.
  • Suppose that the search result for http is:

    20200103000000 https://example.com/c.html
    20210102000000 https://example.com/a.html
    20220101000000 https://example.com/b.html

  • The search result for Ahttp is:

    20210102000000 https://example.com/a.html
    20220101000000 https://example.com/b.html
    20200103000000 https://example.com/c.html

  • When the query is Nquick brown Dfox Njumps:
    • Clutter shows items that:
      • do not contain quick,
      • contain brown,
      • contain fox,
      • and do not contain jumps,
    • and it sorts them by the string after fox in descending order.
• Replace (substitute):
  • To replace old with new:
    1. Set the query to S|old|new|.
    2. Click on the % button in the top left.
  • Unlike find, the old and new in a substitute query are case-sensitive.
  • The delimiter (|) may be any letter.
    • To replace :| with :), set the query to S/:|/:)/.
  • The substitute query may contain additional conditions.
    • To replace old with new only in items that contain yes but do not contain no, set the query to S|old|new| yes Nno.
  • When old or new contains a space character, use [space].
    • To replace hello world with good morning world, set the query to S|hello[space]world|good[space]morning[space]world|.
  • The warning "new" already exists! indicates that the new string is already present in Clutter.
    • In such a situation, redoing the substitute operation may be difficult.
  • When doing a substitute operation, a backup file is automatically saved in the snapshots folder as yyyymmddHHMMSS.clutter.txt.
    • The snapshots folder is located in the same directory as clutter.txt.
• Log:
  • The log file is automatically created as clutter.txt.log in the same folder as clutter.txt.
  • The log file is updated on add, edit (including delete), or replace.
  • The log file is made up of blocks that are separated by blank lines.
  • A block is made up of single/double/triple row(s).
    • Single row blocks (add): just the new line.
    • Double row blocks (physical delete): the timestamp and the old line.
    • Triple row blocks (non-delete edit or replace): timestamp, new, and old.
  • A, D, N, and S are not supported in the log search.

Best practices

• Command line:
  • Avoid typing out the command python3 clutter.py /path/to/clutter.txt.
  • Add the following line to the ~/.bashrc file:

    alias clutter-run="python3 /path/to/clutter/clutter.py /path/to/clutter.txt"

  • Run clutter-run to start Clutter.
• Vimium C:
  • A highly recommended Chrome extension.
  • Control the browser using only the keyboard.
• Shortcuts:
  • Use site search shortcuts.
  • Find: http://localhost:12224/?q=%s
  • Add: http://localhost:12224/?add=%s
  • Log: http://localhost:12224/log?q=%s
• Formatted find:
  • Remove unnecessary parts from the URL in the PDF Viewer for Vimium C (chrome-extension://nacjakoppgmdcpemlfnfegmlhipddanj/...).
  • Decapitalize the query to avoid conflict with A, D, and N.
  • Use /path/to/clutter/utils/redirector.html?q=%sx as a site search shortcut.
  • Do not use this when dealing with regular URLs.
• Tagging:
  • Hashtags (#tagname) and cashtags ($tagname) are colorized.
  • Include a hashtag in every item that is added to Clutter.
  • When creating a new tag, add an item like #tag #newtagname to list tags.
  • To spot misspelled or undeclared tags, run:

    python3 /path/to/clutter/utils/spot.py /path/to/clutter.txt

• Tag nesting:
  • Use hierarchy to list related tags.
  • #tag #parent #child
  • #tag #grandparent #parent #child
  • #tag #tagname $root (for root tags)
• Tag counter:
  • Visit http://localhost:12224/tag?q=%s to view the number of tags.
• Timestamping:
  • Copy and paste the current date and time (in the format yyyymmddHHMMSS).
  • Mac users can use Karabiner-Elements.
  • Add the following object into profiles.complex_modifications.rules of ~/.config/karabiner/karabiner.json.

    {
        "description": "datetime",
        "manipulators": [
            {
                "from": {
                    "key_code": "<favorite-letter>",
                    "modifiers": {
                        "mandatory": [
                            "command"
                        ]
                    }
                },
                "to": [
                    {
                        "shell_command": "date +'%Y%m%d%H%M%S' | tr -d '\n' | pbcopy"
                    }
                ],
                "type": "basic"
            }
        ]
    }

  • Press the command key and <favorite-letter> to copy the current date and time to the clipboard and then paste it as a timestamp.
• Task management:
  • Denote the completion time using $done:yyyymmddHHMMSS.
  • To sort items by completion time, include D$done in the query.
• Deleting an item:
  • Physical deletion: replace the item with a blank.
    • Select all, delete, and enter.
  • Logical deletion: add a $trash tag.
• Sorting by importance:
  • Use $star:<n> or whatever to signify the importance of an item.
  • To sort items by importance, include D$star in the query.
  • Site search shortcut: http://localhost:12224/?q=D%24star+%s
• Daily review:
  • The date part of the timestamp is clickable.
  • Click on the date to see what happened on that day.
• File management:
  • Prepend yyyymmddHHMMSS. to the filename.
  • Place all files in a single folder.
  • Add to Clutter an item with a file path, a description, and a tag.
  • Strings that start with / can be copied with Vimium C's LinkHints.activateCopyLinkUrl.
• Using Clutter across multiple devices:
  • Sync clutter.txt and clutter.txt.log.
  • Use cloud storage services like Dropbox or Google Drive.
• Bookmarking:
  • Check whether the current page's URL has been included in Clutter.
  • Using Tampermonkey:

    // ==UserScript==
    // @name         clutter
    // @version      1.0.0
    // @description  Easily search URLs.
    // @author       sharimot
    // @match        *://*/*
    // @icon         https://raw.githubusercontent.com/sharimot/clutter/main/static/favicon.svg
    // @grant        none
    // ==/UserScript==
    
    (function() {
        window.addEventListener('keydown', event => {
            if (event.target.matches('input')) { return; }
            if (event.target.matches('textarea')) { return; }
            if (event.target.closest('[contenteditable]')) { return; }
            const q = encodeURIComponent(location.href.split('#')[0]);
            const url = `http://localhost:12224/?q=${q}`;
            if (event.key === '<favorite-letter-1>') {
                window.location.href = url;
            }
            if (event.key === '<favorite-letter-2>') {
                window.open(url, '_blank').focus();
            }
        });
    })();

  • Press <favorite-letter-1> to open Clutter in the same tab.
  • Press <favorite-letter-2> to open Clutter in a new tab.
  • Click on the + button to copy the query to the input field.
• Planning:
  • Make an hourly timetable for tomorrow.
  • It also serves as a lifelog.
  • Programmatically create a reverse chronological sequence of lines in the format

    yyyymmddHH0000 #plan 

    and append it to the bottom of clutter.txt.
  • When planning, edit it like this:

    yyyymmddHH0000 #plan #tagname

  • When done, edit it like this with |:

    yyyymmddHH0000 #plan #tagname | description

• Screen recording:
  • Mac users can add the following snippet to the .bashrc.

    record() {
        local timestamp=$(date +"%Y%m%d%H%M%S")
        ffmpeg -f avfoundation -i "1:0" -r 15 -s 1280x800 "/path/to/videos/${timestamp}.mp4"
    }

  • This makes it easier to see what happened at a particular moment.
• Important pages:
  • #tag D$star for choosing the plan.
  • #plan yyyymm N| for viewing and editing plans.
  • #plan | for viewing the past.