Numen is a sleek, Markdown-first terminal notepad that brings your notes to life with the power of AI. Write code snippets, brainstorm ideas, and transform text seamlessly with models like Claude 3, GPT-4, Gemini, or local engines like Ollama — all from the comfort of your terminal.
showcase.mp4
- 📝 Markdown-first editing experience
- 🤖 Multi-AI integration: Claude 3, GPT-4, Gemini, Ollama
- 🏷️ Tag-based note organization
- 📋 Template system for different note types
- 📜 Version history with diff comparisons
- ⚡ Powerful CLI interface
- 💾 Local-first storage (no cloud, full control)
- 🖼️ Rich-text terminal display
- 🔐 Backup & import functionality
- 📊 Stats & insights on your note-taking habits
# Clone the repo
git clone https://github.com/aguiarsc/numen.git
cd numen
# Install core (no AI)
pip install -e .
# Add AI provider support:
pip install -e ".[gemini]" # Google Gemini (Rust-free)
pip install -e ".[anthropic]" # Claude 3 (needs Rust)
pip install -e ".[openai]" # OpenAI GPT (needs Rust)
# All providers
pip install -e ".[all-ai]"
# For development (includes tests, linters, etc.)
pip install -e ".[dev]"Arch Linux uses an externally managed environment for Python packages. The recommended installation method is using the install script which automatically detects and uses pipx:
# Clone the repo
git clone https://github.com/aguiarsc/numen.git
cd numen
# Run the install script (includes all AI providers by default)
./install.sh --all-ai
# Or for minimal installation without AI features
./install.shThis installation method:
- Uses pipx to create an isolated environment
- Avoids conflicts with system packages
- Makes uninstallation cleaner (
./uninstall.shwill use pipx too) - Works with Arch's PEP 668 externally managed environment
Claude and GPT integrations depend on Rust. You can:
- Skip AI and use it as a standard notepad
- Use Gemini or Ollama (no Rust required)
- Install all AI tools if Rust is available
Numen smartly detects what’s available and falls back gracefully.
Numen stores config and notes in ~/.numen/.
First run:
numen configThis creates ~/.numen/config.toml. Add your API keys:
[ai]
default_provider = "gemini"
anthropic_api_key = "your-api-key"
openai_api_key = "your-api-key"
gemini_api_key = "your-api-key"
ollama_base_url = "http://localhost:11434"
default_model = "gemini-1.5-flash"
temperature = 0.7
[editor]
default = "nvim"
[paths]
notes_dir = "~/.numen/notes"numen new "Note title" # Create a note
numen new "Meeting Notes" -t meeting # Create from template
numen list # List all notes
numen list --tag idea # Filter by tag
numen edit my-note # Edit in $EDITOR
numen view my-note # Read-only display
numen search "regex" # Fuzzy search
numen tag my-note +inspo # Add or remove tags
numen remove my-note # Delete notenumen templates list # List all templates
numen templates create book-review # Create new template
numen templates edit meeting # Edit a template
numen templates show journal # View template content
numen templates delete my-template # Delete a template
numen templates reset meeting # Reset default templatenumen history save my-note -m "Comment" # Create a version
numen history list my-note # List all versions
numen history view my-note 0 # View oldest version
numen history restore my-note 1 # Revert to second oldest version
numen history diff my-note 0 1 # Compare oldest vs second version
numen history remove my-note # Delete all version historynumen stats- Total notes
- Monthly breakdown
- Top tags
- Word count stats
numen backup ./backup.zip # Create zip
numen import ./backup.zip # Restore
numen import ./backup.zip --overwrite # Overwrite existingnumen ai expand my-note --section 2 # Expand section
numen ai summarize my-note # Summarize
numen ai summarize my-note --preview # Dry run
numen ai summarize my-note --replace # Inline replace
numen ai poetic my-note --section 3 # Make it lyrical
numen ai custom my-note "Make it a love letter" # Freeform AI promptNotes are stored in ~/.numen/notes/ as Markdown with frontmatter:
---
title: A Bright Idea
date: 2023-04-21T15:30:45
tags: [inspiration, python, cli]
---
# A Bright Idea
Everything begins here.
## Details
Markdown. Syntax. Bliss.| Command | Description |
|---|---|
new <title> |
Create a new note |
new <title> -t <template> |
Create note from template |
list [--tag <tag>] |
List all notes (filtered if needed) |
edit <note> |
Edit in your default terminal editor |
view <note> [--raw] |
View content (raw optional) |
search <query> |
Fuzzy search your notes |
tag <note> [+tag] [-tag] |
Manage tags on notes |
remove <note> [--force] |
Delete note (with optional force) |
stats |
Show statistics |
| Command | Description |
|---|---|
templates list |
List all available templates |
templates create <name> |
Create a new template |
templates edit <name> |
Edit an existing template |
templates show <name> |
Display a template's content |
templates delete <name> |
Delete a template |
templates reset <name> |
Reset a default template |
| Command | Description |
|---|---|
history save <note> [-m] |
Create a version with message |
history list <note> |
List all versions of a note |
history view <note> <idx> |
View a specific version (by index or ID) |
history restore <note> <idx> |
Revert to a previous version |
history diff <note> <v1> <v2> |
Compare two versions |
history remove <note> |
Delete all version history |
| Command | Description |
|---|---|
backup [path] |
Backup all notes into a zip archive |
import <path> |
Restore from a backup zip |
import <path> --overwrite |
Overwrite notes on restore |
| Command | Description |
|---|---|
ai expand <note> |
Expand content using AI |
ai summarize <note> |
Generate summaries |
ai poetic <note> |
Make it poetic |
ai custom <note> "<instruction>" |
Custom AI task |
--section N, --preview, --replace (any command) |
Modify how AI interacts with note content |
make dev-install # Install dev deps
make test # Run test suite
make lint # Lint code
make format # Format code
make clean # Clean up“A good note is a thought that refused to be forgotten.”
Numen is for tinkerers, thinkers, and terminal romantics. It’s a place to write raw ideas and refine them with the help of machines — all while staying offline, markdown-pure, and in full control.