v3.1.0 · Zero dependencies · Pure Python

Notes that live
in your terminal

Vim keybindings. Full-screen. An AI who reads your notes and remembers you. No pip installs. Just Python.

Install now View source

shellnote — python3

⬡ 8 notes [Work] sort:modified ✦ Sage

/ search [Work]

TITLECATEGORYWCDATE

★ Q3 Planning 2025 Work 312w 2h ago

API redesign notes Work 88w 4h ago

Sprint retro Work 44w yesterday

Weekly review General 201w 3d ago

PREVIEW

API redesign notes

Work 4h ago 88w

#api #rest #v2

Breaking changes for v2:

- Auth via header only

- Pagination mandatory

- Deprecate /v1/users

…

API redesign notes INSERT

1 # API redesign notes

3 ## Breaking changes for v2

5 - Auth via header only (Bearer token)

6 - Pagination mandatory on all list endpoints

7 - Deprecate /v1/users by Q4

9 TODO verify migration guide with devrel

10 TODO add versioning note to README

12 ~

13 ~

✦ Sage [llama-3.1-8b-instant] API redesign notes

Note loaded: API redesign notes

You: what's the riskiest change here?

Sage: The mandatory pagination is the highest risk.

Any client that fetches all records in one

call will break silently if you just add

a default limit. You'll need a deprecation

warning on the old behaviour first.

You: add that to the TODO list

…thinking

Enter:Ask Esc:Close Ctrl+A:Clear PgUp/Dn:Scroll

SettingsEsc:close

Theme Sage AI Categories Display Memory About

Color Theme

◆ Monokai ← active

○ Purple Haze

○ Pink Neon

○ Cream Paper

j/k move Enter select

Get started in 30 seconds

git clone https://github.com/LoneMagma/shellnote.git && cd shellnote

python3 shellnote.py

chmod +x setup_shellnote.sh && ./setup_shellnote.sh

Requires Python 3.6+ · Linux or macOS · 256-color terminal · Full guide →

Built different

Everything you need.
Nothing you don't.

ShellNote is a single Python file. Open it, read it, trust it.

⌨

Real vim bindings

Not vim-inspired. Vim. hjkl, dd, yy, p, gg/G, w/b, u undo, :wq. Normal and Insert modes. If your fingers know vim, they know ShellNote.

✦

Sage AI — built in

Press i on any note. Sage reads it, understands it, and thinks with you. Powered by Groq's free tier. She also remembers facts about you across sessions.

◎

Zero dependencies

Pure Python stdlib. No pip install. No virtual environments. No breaking updates. If Python 3.6 is on your machine, ShellNote runs.

◈

4 themes, live switching

Monokai, Purple Haze, Pink Neon, Cream Paper. Switch in Settings and see it take effect immediately. All themes are contrast-audited for legibility.

◆

Dynamic categories

Not hardcoded. Add your own categories in Settings. Remove ones you don't use. Notes keep their category even if you rename or remove it later.

⬡

Full-screen takeover

The terminal becomes ShellNote. Launch with launch_shellnote.py for a dedicated fullscreen window with no tabs, no title bar, no terminal chrome.

✦ Sage llama-3.1-8b-instant

Note loaded: Q3 Planning 2025

You:

what's missing from this plan?

Sage:

Three things stand out. First, no owner
is assigned to any goal — accountability
is implicit. Second, the timeline is just
"Q3", which has no teeth. Third, success
looks undefined. How do you measure a
20% infra cost reduction? Against what?

You: add those gaps as TODOs

AI that actually helps

Meet Sage

Sage is your thinking partner. She lives inside ShellNote, reads whatever note you're on, and has a running memory of who you are and what you're working on.

Reads your note as context automatically
Persistent memory — learns your preferences across sessions
Model fallback — if one is unavailable, tries the next
Works from the editor mid-thought with Ctrl+A
Free — powered by Groq's free API tier

Get free API key → Sage docs

Aesthetics

Four themes.
One command.

Switch live inside Settings. All themes pass contrast checks — no invisible text, no eye strain.

⬡ SHELLNOTE
▶ All Notes  8
  Work      3
  Personal  2
  Ideas     1
★ Q3 Planning 2025
  Sprint retro

Monokaidefault

⬡ SHELLNOTE
▶ All Notes  8
  Work      3
  Personal  2
  Ideas     1
★ Q3 Planning 2025
  Sprint retro

Purple Hazedeep

⬡ SHELLNOTE
▶ All Notes  8
  Work      3
  Personal  2
  Ideas     1
★ Q3 Planning 2025
  Sprint retro

Pink Neonneon

⬡ SHELLNOTE
▶ All Notes  8
  Work      3
  Personal  2
  Ideas     1
★ Q3 Planning 2025
  Sprint retro

Cream Paperwarm

Muscle memory

If you know vim,
you already know this.

List View

j / k navigate notes

gg / G first / last

n new note

e edit selected

dd delete (confirm)

p pin / unpin

yy copy title

i open Sage AI

/ search

:s settings

q quit

Editor — Normal

h j k l move cursor

0 / $ line start / end

gg / G file start / end

w / b word forward / back

i a A o O enter Insert

dd delete line

yy / p yank / paste

u undo (10 levels)

:w save

:wq save + close

:q discard

Editor — Insert

Esc back to Normal

Ctrl+A open Sage AI

Ctrl+G word / char count

Tab 4 spaces

Syntax hints

# Heading cyan bold

## Sub yellow bold

> Quote magenta

- List yellow

TODO green

Your data, your machine

Local. Private. Yours.

Notes live on your filesystem as plain JSON. No accounts. No sync. No cloud unless you choose.

Data files

Everything ShellNote needs is in one directory:

~/.shellnote/

├── notes.json your notes

├── config.json theme, key, cats

└── sage_memory.json Sage memory

Sage & privacy

Your notes are never sent anywhere unless you open Sage. When you do, the current note is sent to Groq's API to generate a response. Groq's free tier privacy policy applies.

Sage's memory is stored locally. Clear it anytime: Settings → Memory → C

Notes that livein your terminal

Everything you need.Nothing you don't.