cogitus 0.12.0

A fast, searchable terminal workspace for capturing and evolving programming ideas.

Cogitus

[!NOTE]

Cogitus is currently in beta. Core workflows are available, and interfaces may continue to evolve in subsequent releases.

Cogitus — a fast, searchable terminal workspace for capturing and evolving programming ideas.

Cogitus is a Python-based TUI (Terminal User Interface) built with Textual. It is designed specifically for developers who want a structured, keyboard-driven way to capture, explore, and refine programming ideas without leaving the terminal. This is not a generic note-taking app and not a task manager. Cogitus is focused on structured idea capture, iteration, and discovery.

---

Goals

• Fast, local-first idea capture
• Fully keyboard-driven workflow
• Searchable and structured storage
• Minimal, distraction-free UI
• Designed specifically for programming and technical concepts

---

Core Concepts

Cogitus treats ideas as structured entities rather than loose notes. Each idea can include:

• Title
• Body/description (Markdown-friendly text - edit in markdown, display rendered using Textual/Rich native functionality)
• Tags
• Group (ideas are organized under groups in the left tree view)
• Timestamps (created/updated)

Future versions may introduce:

• Idea linking (relationships between ideas)
• Graph views
• Scoring or priority signals
• AI-assisted idea expansion

---

Architecture

• UI: Built with Textual
• Database: SQLite (local file, WAL mode)
• Data Access: sqliter-py
• Package Management: uv

The project intentionally separates:

• Textual UI layer (screens and widgets)
• Repository/service layer for database access
• Schema and migration management

Cogitus is also a real-world validation project for sqliter-py.

---

Current Functionality

Functionality available in the current release:

• Create, edit, rename, and delete ideas
• Organize ideas in groups, including create/rename/delete flows and bulk reassignment on group delete
• Browse ideas in a grouped tree view
• Tag ideas
• Advanced search with SQLite FTS5 text search plus inline operators (tag:, group:, and, or)
• Rendered Markdown detail view with tags and timestamps
• Copy & Paste support
• CLI commands for scripting (list, export, delete)
• Optional FastAPI server for standalone access to ideas, groups, and tags
• Optional MCP server for read-only tool access from MCP clients
• Remote mode so a Cogitus TUI can use a Cogitus API server instead of a local SQLite database

---

Target Users

• Solo developers
• Indie hackers
• Open-source maintainers
• Engineers who think in terminals

If you sketch ideas in README files, TODO lists, or scattered Markdown files across projects, Cogitus aims to centralize that thinking into a structured, searchable workspace.

---

Installation

The recommended way to install this is as a global tool, either using uv (best) or pipx:

uv tool install cogitus

You can always install globally using pip if you don't want to use any of those 2 tools:

pip install cogitus

Usage

cogitus

Key Shortcuts (Main Screen)

• n: New idea
• e: Edit selected idea
• r: Rename selected idea or group
• d: Delete selected idea
• g: New group
• Shift+G: Delete selected group
• /: Focus search
• y: Copy selected idea body
• ?: Show help
• q: Quit

---

Clipboard Support

Cogitus uses two clipboard strategies for maximum compatibility:

• OSC 52 (primary) — works in most modern terminals (Ghostty, iTerm2, Kitty, Alacritty, WezTerm, Windows Terminal) and through tmux/SSH
• pyperclip (fallback) — uses system tools like xclip, xsel, or pbcopy for terminals that don't support OSC 52 (e.g. Gnome Terminal, macOS Terminal)

tmux users: You need set-clipboard enabled in your ~/.tmux.conf for OSC 52 to pass through:

set -g set-clipboard on

Linux users without OSC 52 support: Install xclip or xsel for the pyperclip fallback to work:

sudo apt-get install xclip   # Debian/Ubuntu
sudo pacman -S xclip          # Arch
sudo dnf install xclip        # Fedora

y copy is context-sensitive: In the editor, y copies the current selection. In rendered Markdown view, y copies selected text when detected; otherwise it copies the full idea body. In some terminals/cases, Textual may not detect rendered-view selection and will fall back to full-body copy.

---

Development

This project uses:

• uv for dependency and environment management
• SQLite for local storage
• Textual for UI
• Standard formatting and linting tools defined in the repository

---

License

Cogitus is licensed under the MIT License. See LICENSE.txt.