cotext 0.1.2

Structured project context for humans and coding agents, with a CLI and ratatui TUI.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

# 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

```bash
cargo install cotext
```

For local development from a checkout:

```bash
cargo install --path .
```

## Quick Start

```bash
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
```

Each project gets a plain-text `.cotext/` directory:

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

## Core Commands

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

High-signal patterns:

- `cotext render --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](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