cogitus 0.1.0

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

Cogitus

[!NOTE]

Cogitus is currently in v0.1 MVP/alpha stage. 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
• Timestamps (created/updated)

Future versions may introduce:

• Idea linking (relationships between ideas)
• Graph views
• Scoring or priority signals
• SQLite FTS5-powered full-text search
• AI-assisted idea expansion

---

Architecture

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

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.

---

MVP (v0.1)

• Create new ideas
• Edit existing ideas
• List ideas
• Tag ideas
• Basic search (SQLite LIKE)
• View idea details

Search will initially be simple but structured to evolve into FTS5.

---

Roadmap

v0.2

• SQLite FTS5 search backend
• Better ranking/snippet presentation
• Tag filtering and combined query UX
• Navigation and keybinding polish
• In-place right-pane Markdown edit mode (view/edit toggle in content pane)
• Contextual dynamic toolbar/actions by mode
• Evaluate SQLite write tuning (PRAGMA synchronous=NORMAL) as an optional performance optimization, backed by benchmark and risk assessment.

v0.3

• Idea linking (explicit relationships)
• Relationship browsing primitives
• Richer metadata and prioritization signals

v0.4

• Add non-TUI CLI tasks for idea management:
  • list ideas,
  • dump/export ideas,
  • delete ideas.
• Ensure CLI task layer reuses the same repository/service abstractions as the TUI.

v0.5+

• Graph-oriented idea exploration views
• Scoring heuristics (impact/effort/confidence)
• Optional AI-assisted idea expansion and prompt-to-structure workflows

---

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

uv tool install cogitus

Usage

cogitus

---

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

---

Philosophy

Cogitus is designed to be:

• Local-first
• Minimal
• Fast
• Developer-centric
• Extensible without becoming bloated

It should feel like a serious engineering tool — not a productivity app with a marketing layer