cotext

cotext is a Rust CLI and TUI for keeping project context in one structured, git-friendly place instead of scattering design notes, progress logs, TODOs, and caveats across unrelated markdown files.

This project is built jointly by humans and OpenAI Codex. Treat AI-generated changes like any other contribution: review them, test them, and keep durable project context in sync.

cotext manages five entry categories:

• design
• note
• progress
• todo
• deferred

Install

cargo install cotext

For local development from a checkout:

cargo install --path .

Quick Start

cotext init . --name my-project --with-agents
cotext new design "Context packet format" --section render
cotext new todo "Add export command" --section cli --tag roadmap
cotext list
cotext render --audience codex
cotext tui

Storage Modes

cotext can keep entry files in one of two places:

• global (default): store the project under the system-local data directory. On Linux this is ~/.local/share/<project-name>/.
• local: keep the project inside the repository under .cotext/.

All commands accept --storage local|global. By default, commands prefer global storage and fall back to repo-local storage when no matching global project exists.

Default global layout:

~/.local/share/<project-name>/
  cotext.toml
  entries/
    design/
    note/
    progress/
    todo/
    deferred/

Opt-in local layout:

.cotext/
  cotext.toml
  entries/
    design/
    note/
    progress/
    todo/
    deferred/

Core Commands

cotext init [--storage local|global] [path]
cotext new <category> <title> [--storage local|global]
cotext update <id> [--storage local|global]
cotext list [--storage local|global]
cotext show <id> [--storage local|global]
cotext render [--storage local|global] [--audience human|agent|codex|claude]
cotext agent install <codex|claude|all> [--storage local|global]
cotext tui [--storage local|global]

High-signal patterns:

• cotext render --audience codex
• cotext render --storage local --audience codex
• cotext render --category progress --category todo --audience codex
• cotext list --category todo --status active --status planned
• cotext update <id> --append "Validation: cargo test"
• cotext agent install all --overwrite

Agent Integration

cotext agent install codex writes:

• AGENTS.md
• .codex/skills/cotext-context/SKILL.md
• .codex/skills/cotext-context/agents/openai.yaml

cotext agent install claude writes:

• CLAUDE.md
• .claude/skills/cotext-context/SKILL.md
• .claude/commands/cotext.md
• .claude/commands/cotext-sync.md

Use --codex-skill-dir <path> only when you intentionally want a second Codex skill copy outside the tracked .codex/skills/cotext-context/ tree.

For the full agent workflow and maintenance notes, see docs/agent-workflow.md.

TUI

cotext tui provides a single-screen terminal board for browsing, editing metadata, previewing, and copying entries and packets. Press Enter to open the selected entry in $VISUAL or $EDITOR for real markdown editing.

Key bindings:

• Tab / Shift-Tab: switch category
• j / k: move selection
• Enter / e: open the selected entry in your editor
• n / +: add entry
• d / Delete: delete entry with confirmation
• t / s / g: edit title, section, and tags
• p / a: change preview mode and audience
• ? in browse mode, or F1 anywhere: toggle help
• PageUp / PageDown: scroll preview
• Ctrl-s: save
• Esc: cancel
• c / C: copy selected or category packet
• q: quit