{"id":33185680,"url":"https://github.com/aguiarsc/numen","last_synced_at":"2025-11-22T04:01:32.817Z","repository":{"id":289335957,"uuid":"970906701","full_name":"aguiarsc/numen","owner":"aguiarsc","description":"Markdown-compatible terminal notepad that allows users to take notes, write snippets of code, and send selected text to AI models","archived":false,"fork":false,"pushed_at":"2025-04-22T18:53:59.000Z","size":4108,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-22T19:37:28.641Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aguiarsc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-22T18:03:06.000Z","updated_at":"2025-04-22T18:54:03.000Z","dependencies_parsed_at":"2025-04-22T19:38:26.930Z","dependency_job_id":"8bd03b70-7703-413b-b53b-6d42cc512ad2","html_url":"https://github.com/aguiarsc/numen","commit_stats":null,"previous_names":["aguiarsc/numen"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/aguiarsc/numen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aguiarsc%2Fnumen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aguiarsc%2Fnumen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aguiarsc%2Fnumen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aguiarsc%2Fnumen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aguiarsc","download_url":"https://codeload.github.com/aguiarsc/numen/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aguiarsc%2Fnumen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":285731803,"owners_count":27222214,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-22T02:00:05.934Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-11-16T05:00:20.098Z","updated_at":"2025-11-22T04:01:32.808Z","avatar_url":"https://github.com/aguiarsc.png","language":"Python","funding_links":[],"categories":["\u003ca name=\"note-taking\"\u003e\u003c/a\u003eNote taking"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/aguiarsc/numen/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/aguiarsc/numen?style=flat-square\" alt=\"Latest Release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/aguiarsc/numen/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/aguiarsc/numen?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# ✨ Numen — AI-Augmented Terminal Notepad\n\n**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.\n\n---\n\nhttps://github.com/user-attachments/assets/029ed3b6-e5f1-4087-9b9e-44406e2ad660\n\n---\n\n## 🚀 Features\n\n- 📝 **Markdown-first editing** experience\n- 🤖 **Multi-AI integration**: Claude 3, GPT-4, Gemini, Ollama\n- 🏷️ **Tag-based** note organization\n- 📋 **Template system** for different note types\n- 📜 **Version history** with diff comparisons\n- ⚡ **Powerful CLI** interface\n- 💾 **Local-first** storage (no cloud, full control)\n- 🖼️ **Rich-text terminal display**\n- 🔐 **Backup \u0026 import** functionality\n- 📊 **Stats \u0026 insights** on your note-taking habits\n\n---\n\n## 📦 Installation\n\n### 🛠 From Source\n\n```bash\n# Clone the repo\ngit clone https://github.com/aguiarsc/numen.git\ncd numen\n\n# Install core (no AI)\npip install -e .\n\n# Add AI provider support:\npip install -e \".[gemini]\"     # Google Gemini (Rust-free)\npip install -e \".[anthropic]\"  # Claude 3 (needs Rust)\npip install -e \".[openai]\"     # OpenAI GPT (needs Rust)\n\n# All providers\npip install -e \".[all-ai]\"\n\n# For development (includes tests, linters, etc.)\npip install -e \".[dev]\"\n```\n\n### 🐧 Arch Linux (and friends)\n\nArch Linux uses an externally managed environment for Python packages. The recommended installation method is using the install script which automatically detects and uses pipx:\n\n```bash\n# Clone the repo\ngit clone https://github.com/aguiarsc/numen.git\ncd numen\n\n# Run the install script (includes all AI providers by default)\n./install.sh --all-ai\n\n# Or for minimal installation without AI features\n./install.sh\n```\n\nThis installation method:\n- Uses pipx to create an isolated environment\n- Avoids conflicts with system packages\n- Makes uninstallation cleaner (`./uninstall.sh` will use pipx too)\n- Works with Arch's PEP 668 externally managed environment\n\n### 🧰 Rust Requirements\n\nClaude and GPT integrations depend on Rust. You can:\n\n1. Skip AI and use it as a standard notepad  \n2. Use **Gemini** or **Ollama** (no Rust required)  \n3. Install all AI tools if Rust is available\n\nNumen smartly detects what’s available and falls back gracefully.\n\n---\n\n## ⚙️ Configuration\n\nNumen stores config and notes in `~/.numen/`.\n\nFirst run:\n\n```bash\nnumen config\n```\n\nThis creates `~/.numen/config.toml`. Add your API keys:\n\n```toml\n[ai]\ndefault_provider = \"gemini\"\nanthropic_api_key = \"your-api-key\"\nopenai_api_key = \"your-api-key\"\ngemini_api_key = \"your-api-key\"\nollama_base_url = \"http://localhost:11434\"\ndefault_model = \"gemini-1.5-flash\"\ntemperature = 0.7\n\n[editor]\ndefault = \"nvim\"\n\n[paths]\nnotes_dir = \"~/.numen/notes\"\n```\n\n---\n\n## 💡 Usage\n\n### ✍️ Core CLI Commands\n\n```bash\nnumen new \"Note title\"                    # Create a note\nnumen new \"Meeting Notes\" -t meeting      # Create from template\nnumen list                                # List all notes\nnumen list --tag idea                     # Filter by tag\nnumen edit my-note                        # Edit in $EDITOR\nnumen view my-note                        # Read-only display\nnumen search \"regex\"                      # Fuzzy search\nnumen tag my-note +inspo                  # Add or remove tags\nnumen remove my-note                      # Delete note\n```\n\n### 📋 Templates\n\n```bash\nnumen templates list                      # List all templates\nnumen templates create book-review        # Create new template\nnumen templates edit meeting              # Edit a template\nnumen templates show journal              # View template content\nnumen templates delete my-template        # Delete a template\nnumen templates reset meeting             # Reset default template\n```\n\n### 📜 Version History\n\n```bash\nnumen history save my-note -m \"Comment\"   # Create a version\nnumen history list my-note                # List all versions\nnumen history view my-note 0              # View oldest version\nnumen history restore my-note 1           # Revert to second oldest version\nnumen history diff my-note 0 1            # Compare oldest vs second version\nnumen history remove my-note              # Delete all version history\n```\n\n### 📈 Stats \u0026 Insights\n\n```bash\nnumen stats\n```\n\n- Total notes\n- Monthly breakdown\n- Top tags\n- Word count stats\n\n### 📦 Backup \u0026 Restore\n\n```bash\nnumen backup ./backup.zip             # Create zip\nnumen import ./backup.zip             # Restore\nnumen import ./backup.zip --overwrite # Overwrite existing\n```\n\n### 🧠 AI Commands\n\n```bash\nnumen ai expand my-note --section 2                 # Expand section\nnumen ai summarize my-note                          # Summarize\nnumen ai summarize my-note --preview                # Dry run\nnumen ai summarize my-note --replace                # Inline replace\nnumen ai poetic my-note --section 3                 # Make it lyrical\nnumen ai custom my-note \"Make it a love letter\"     # Freeform AI prompt\n```\n\n---\n\n## 🗃 Note Structure\n\nNotes are stored in `~/.numen/notes/` as Markdown with frontmatter:\n\n```markdown\n---\ntitle: A Bright Idea\ndate: 2023-04-21T15:30:45\ntags: [inspiration, python, cli]\n---\n\n# A Bright Idea\n\nEverything begins here.\n\n## Details\n\nMarkdown. Syntax. Bliss.\n```\n\n---\n\n## 🧾 Command Reference\n\n### Core\n\n| Command                  | Description                             |\n|--------------------------|-----------------------------------------|\n| `new \u003ctitle\u003e`            | Create a new note                       |\n| `new \u003ctitle\u003e -t \u003ctemplate\u003e` | Create note from template            |\n| `list [--tag \u003ctag\u003e]`     | List all notes (filtered if needed)     |\n| `edit \u003cnote\u003e`            | Edit in your default terminal editor    |\n| `view \u003cnote\u003e [--raw]`    | View content (raw optional)             |\n| `search \u003cquery\u003e`         | Fuzzy search your notes                 |\n| `tag \u003cnote\u003e [+tag] [-tag]`| Manage tags on notes                   |\n| `remove \u003cnote\u003e [--force]`| Delete note (with optional force)       |\n| `stats`                  | Show statistics                         |\n\n### Templates\n\n| Command                      | Description                          |\n|------------------------------|--------------------------------------|\n| `templates list`             | List all available templates         |\n| `templates create \u003cname\u003e`    | Create a new template                |\n| `templates edit \u003cname\u003e`      | Edit an existing template            |\n| `templates show \u003cname\u003e`      | Display a template's content         |\n| `templates delete \u003cname\u003e`    | Delete a template                    |\n| `templates reset \u003cname\u003e`     | Reset a default template             |\n\n### Version History\n\n| Command                       | Description                         |\n|-------------------------------|-------------------------------------|\n| `history save \u003cnote\u003e [-m]`    | Create a version with message       |\n| `history list \u003cnote\u003e`         | List all versions of a note         |\n| `history view \u003cnote\u003e \u003cidx\u003e`   | View a specific version (by index or ID) |\n| `history restore \u003cnote\u003e \u003cidx\u003e`| Revert to a previous version        |\n| `history diff \u003cnote\u003e \u003cv1\u003e \u003cv2\u003e` | Compare two versions              |\n| `history remove \u003cnote\u003e`       | Delete all version history          |\n\n### Backup \u0026 Restore\n\n| Command                | Description                            |\n|------------------------|----------------------------------------|\n| `backup [path]`        | Backup all notes into a zip archive    |\n| `import \u003cpath\u003e`        | Restore from a backup zip              |\n| `import \u003cpath\u003e --overwrite`| Overwrite notes on restore         |\n\n### AI Tools\n\n| Command                                              | Description                               |\n|------------------------------------------------------|-------------------------------------------|\n| `ai expand \u003cnote\u003e`                                   | Expand content using AI                   |\n| `ai summarize \u003cnote\u003e`                                | Generate summaries                        |\n| `ai poetic \u003cnote\u003e`                                   | Make it poetic                            |\n| `ai custom \u003cnote\u003e \"\u003cinstruction\u003e\"`                   | Custom AI task                            |\n| `--section N`, `--preview`, `--replace` (any command) | Modify how AI interacts with note content |\n\n---\n\n## 🛠 Development\n\n```bash\nmake dev-install  # Install dev deps\nmake test         # Run test suite\nmake lint         # Lint code\nmake format       # Format code\nmake clean        # Clean up\n```\n\n---\n\n## 🧠 Philosophy\n\n\u003e *“A good note is a thought that refused to be forgotten.”*\n\nNumen 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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faguiarsc%2Fnumen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faguiarsc%2Fnumen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faguiarsc%2Fnumen/lists"}