FinNode

FINNODE - COMPLETE HOW-TO GUIDE

This is the practical day-to-day guide for the current FinNode build. It covers setup, workspaces, node editing, quick launcher, macros, shortcut recording, startup behavior, persistence, tray controls, and troubleshooting.

Go back to the FinNode overview

Guide Contents

1) What FinNode Is 2) First Run Checklist 3) Understanding the UI 4) Core Workflow 5) Workspaces 6) Nodes 7) Board Interaction 8) Multi-Select 9) Search / Quick Launcher 10) Macros 11) Shortcut Recorder 12) Type-Text Tips 13) Open-Application 14) Startup and Persistence 15) System Tray and Hotkeys 16) Window Controls 17) Visual Controls 18) Data Storage 19) Build and Run Commands 20) Troubleshooting 21) Practical Examples 22) Good Practices

1) WHAT FINNODE IS

FinNode is a desktop project launcher and automation board with two windows working together:

Use FinNode to open project folders, run scripts, launch apps, open URLs, type text into active apps, and send keyboard shortcut sequences.

2) FIRST RUN CHECKLIST

  1. Launch FinNode.
  2. Confirm both windows appear: Settings window and Node Board window.
  3. In Settings, verify the "Start app when the PC starts" toggle.
  4. Resize and move the Node Board to your preferred position.
  5. Close and reopen FinNode to verify position and size persistence.

3) UNDERSTANDING THE UI

Settings Window Sections

Node Board Areas

4) CORE WORKFLOW (RECOMMENDED)

  1. Create a workspace per context, for example: Client A, Backend, Personal.
  2. Add nodes for each project or repeated action.
  3. Edit each node and set targets: path, editor command, browser URL, script command.
  4. Assign node colors and icons for quick recognition.
  5. Add macro steps for multi-action flows.
  6. Link related nodes to map dependencies visually.
  7. Set board position, then restart once to confirm geometry persistence.

5) WORKSPACES - HOW TO USE

Create workspace

  1. In Settings -> Workspaces, type a name.
  2. Click +.

Switch workspace

  1. Use the workspace dropdown.
  2. Select your target workspace.

Delete workspace

  1. Select workspace.
  2. Click Delete workspace.
  3. You cannot delete the last remaining workspace.

6) NODES - CREATE, EDIT, ORGANIZE

Add a node

  1. Click + Add in Settings, or + in the Node Board title bar.

Open node editor

Node fields explained

Save changes

  1. Click Save changes.
  2. FinNode persists node data to config.

7) NODE INTERACTION ON THE BOARD

Click behavior

Drag behavior

Context menu actions

8) MULTI-SELECT AND BATCH ACTIONS

Selection

Batch bar options (when selection exists)

9) SEARCH / QUICK LAUNCHER

Open launcher

Use launcher

  1. Type node name.
  2. Use arrow keys.
  3. Press Enter to run node open-path.

10) MACROS - COMPLETE GUIDE

What macros do

How to add macro steps

  1. Open node editor.
  2. Go to Macros section.
  3. Click + Add macro step.
  4. Choose action and set value.
  5. Add more steps as needed.
  6. Save node.

Macro action reference

  1. run-script: runs command string, or script path if value resolves to file.
  2. run-uploaded-script: runs previously uploaded script file for the node.
  3. type-text: types text into the currently active external window.
  4. keyboard-shortcut: sends key chord(s) into currently active external window, supports multi-switch sequences.
  5. open-path: opens path with OS default opener.
  6. open-editor: opens editor target/path.
  7. open-browser: opens URL in browser.
  8. open-application: launches app by command/app name/desktop entry.
  9. delay: waits milliseconds before next step.

11) KEYBOARD SHORTCUT MACRO (RECORDER)

This is the most advanced macro type.

Record a shortcut sequence

  1. Set action to keyboard-shortcut.
  2. Click Record.
  3. Press the first key combo, for example Ctrl+K.
  4. Press a second combo if needed, for example Ctrl+C.
  5. Click Stop or press Esc.
  6. Save node.

How sequence format works

Display behavior

Tips

12) TYPE-TEXT MACRO - BEST RESULTS

Goal

How to get reliable typing

  1. Start macro from Node Board or Settings.
  2. Ensure target app is focused before macro run.
  3. Keep FinNode visibility in mind: FinNode performs focus handoff before input actions.

Linux tools

Install if missing:

sudo apt-get install -y xdotool wtype

13) OPEN-APPLICATION ACTION

What to put in value

Platform notes

If app does not open

  1. Try full command.
  2. Try desktop id on Linux.
  3. Verify app command exists in PATH.

14) STARTUP AND PERSISTENCE

Start on boot

What is persisted

When desktop board geometry is saved

When geometry is restored

15) SYSTEM TRAY AND HOTKEYS

Tray menu items

Global hotkeys

16) WINDOW CONTROLS BEHAVIOR

Settings window minimize button

Settings window close button

Desktop board window

17) VISUAL CONTROLS

Zoom

Opacity

18) WHERE DATA IS STORED

19) BUILD/RUN COMMANDS (FOR POWER USERS)

20) TROUBLESHOOTING

Typing macro does not type in target app

  1. Focus target app right before macro.
  2. Install xdotool and wtype on Linux.
  3. Avoid secure input fields that block synthetic typing.

Keyboard-shortcut macro does not trigger expected behavior

  1. Re-record sequence.
  2. Ensure each chord includes a non-modifier key.
  3. Add short delay steps between complex sequences.

Open-application does nothing

  1. Try command name and full command variants.
  2. On Linux, try app.desktop id.
  3. Check PATH and app install.

Board position/size resets after restart

  1. Move/resize board, then fully exit app once.
  2. Reopen and verify restore.
  3. If autostart path differs by session, verify config-dir permissions.

App says already running

  1. Confirm no FinNode process exists.
  2. Remove stale lock file only when app is definitely closed.

21) PRACTICAL EXAMPLES

Example A: Start coding session macro

1. open-path -> /home/user/work/myrepo
2. open-editor -> code /home/user/work/myrepo
3. open-browser -> http://localhost:5173
4. delay -> 800
5. keyboard-shortcut -> Ctrl+K, Ctrl+C

Example B: Daily notes workflow

1. open-application -> obsidian
2. delay -> 700
3. keyboard-shortcut -> Ctrl+N
4. type-text -> Daily notes

22) GOOD PRACTICES

Back to top