Skip to content

Commit 1ccb2d1

Browse files
sugarpoosugarpoo
committed
Prepare public launch materials
1 parent 79b25f2 commit 1ccb2d1

5 files changed

Lines changed: 212 additions & 13 deletions

File tree

‎README.md‎

Lines changed: 41 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,37 @@
33
[![Lint](https://github.com/sugarpoo/codex-learning-loop/actions/workflows/lint.yml/badge.svg)](https://github.com/sugarpoo/codex-learning-loop/actions/workflows/lint.yml)
44
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
55

6-
A safe global learning loop for Codex on macOS.
6+
A local learning loop for Codex on macOS.
77

8-
Codex Learning Loop is a local macOS automation system that gives Codex a file-based global learning workflow. It captures reusable lessons, processes them on a daily/catch-up schedule, and maintains global guidance files so future Codex sessions behave more consistently.
8+
Codex Learning Loop helps Codex remember reusable lessons across sessions by maintaining global guidance files such as `AGENTS.md`, `GLOBAL_MEMORY.md`, and `ERROR_PATTERNS.md`. It captures learning candidates, processes them on a daily/catch-up schedule, and keeps future Codex sessions more consistent.
99

10-
It does **not** train, fine-tune, or modify the model. It maintains local Markdown and TSV files that future Codex sessions can read.
10+
It does **not** train, fine-tune, or modify the model. It maintains local Markdown and TSV files that future Codex sessions can read before future work.
11+
12+
## Why This Exists
13+
14+
- Codex is powerful, but repeated mistakes can happen across sessions.
15+
- This project creates a local file-based feedback loop.
16+
- It does not train the model.
17+
- It maintains guidance files Codex can read before future work.
18+
- It is scoped to `~/.codex` for safety.
19+
20+
## 30-Second Explanation
21+
22+
Codex Learning Loop gives your local Codex setup a durable place to put lessons that should survive beyond one chat. During normal work, you or Codex can add short learning candidates to `~/.codex/learning-inbox/`. A daily macOS LaunchAgent, with catch-up handling for missed runs, reviews those candidates and updates guidance files like `GLOBAL_MEMORY.md` and `ERROR_PATTERNS.md` when the lesson is clear enough to keep.
23+
24+
## Who This Is For
25+
26+
- Codex power users.
27+
- Developers who use `AGENTS.md`.
28+
- People who automate local workflows.
29+
- People who want safer scheduled Codex maintenance.
30+
31+
## Not Magic
32+
33+
- It does not train the model.
34+
- It does not read all chats.
35+
- It does not scan your whole computer.
36+
- It does not replace human review.
1137

1238
## Quick Install
1339

@@ -88,16 +114,15 @@ open "$HOME/.codex/reports/global-learning-maintenance"
88114
## How The Learning Loop Works
89115

90116
```mermaid
91-
flowchart TD
92-
A["Codex session notices a reusable lesson"] --> B["Learning candidate in ~/.codex/learning-inbox"]
93-
B --> C["Daily or catch-up maintenance run"]
94-
C --> D["Classification rubric"]
95-
D --> E["AGENTS.md"]
96-
D --> F["GLOBAL_MEMORY.md"]
97-
D --> G["ERROR_PATTERNS.md"]
98-
D --> H["ACTIVE_GLOBAL.md"]
99-
D --> I["Keep in inbox or archive"]
100-
C --> J["Timestamped report and log"]
117+
flowchart LR
118+
A[Codex session] --> B[Learning candidate]
119+
B --> C[~/.codex/learning-inbox]
120+
D[LaunchAgent daily / catch-up] --> E[Maintenance script]
121+
C --> E
122+
E --> F[GLOBAL_MEMORY.md]
123+
E --> G[ERROR_PATTERNS.md]
124+
E --> H[AGENTS.md]
125+
E --> I[Maintenance report]
101126
```
102127

103128
The maintenance script runs Codex with `~/.codex` as the workspace and uses `~/.codex/templates/global-learning-maintenance-prompt.md` as its editable rubric prompt.
@@ -174,6 +199,9 @@ Public repositories should include only templates, scripts, documentation, and g
174199
- [Learning Rubric](docs/learning-rubric.md)
175200
- [Troubleshooting](docs/troubleshooting.md)
176201
- [Safety Model](docs/safety-model.md)
202+
- [Demo Plan](docs/demo.md)
203+
- [Launch Materials](docs/launch.md)
204+
- [Public Launch Checklist](docs/public-launch-checklist.md)
177205

178206
## Repository Structure
179207

‎assets/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Demo Assets
2+
3+
This folder is reserved for public-safe screenshots and GIFs.
4+
5+
Recommended assets:
6+
7+
- `terminal-install.png`: terminal screenshot showing `./scripts/install.sh`.
8+
- `learning-candidate.png`: screenshot of a fake learning candidate being added.
9+
- `maintenance-report.png`: screenshot of a generic maintenance report.
10+
- `architecture-diagram.png`: screenshot or export of the README architecture diagram.
11+
- `demo.gif`: short end-to-end demo following `docs/demo.md`.
12+
13+
Before adding assets, check that they do not include private logs, real reports, backups, state files, personal notes, credentials, account details, or personal paths.
14+

‎docs/demo.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Demo Plan
2+
3+
Use this as the script for a short demo GIF or screen recording. Keep the demo data fake, generic, and safe to publish.
4+
5+
## Short Demo GIF Script
6+
7+
1. Show the repo install command:
8+
9+
```sh
10+
./scripts/install.sh
11+
```
12+
13+
2. Add a fake learning candidate:
14+
15+
```sh
16+
~/.local/bin/codex-add-global-learning-note "When a command fails because a repo path is wrong, verify pwd and git status before retrying."
17+
```
18+
19+
3. Run maintenance manually:
20+
21+
```sh
22+
~/.local/bin/codex-global-learning-maintenance
23+
```
24+
25+
4. Show the candidate classified in the maintenance report.
26+
27+
5. Show `ERROR_PATTERNS.md` or `GLOBAL_MEMORY.md` updated with the fake lesson.
28+
29+
6. Show the status command:
30+
31+
```sh
32+
~/.local/bin/codex-global-learning-maintenance --status
33+
```
34+
35+
7. Explain catch-up mode:
36+
37+
```sh
38+
~/.local/bin/codex-global-learning-maintenance --dry-run-catchup
39+
```
40+
41+
## Recording Notes
42+
43+
- Use a clean demo account or temporary `HOME` when possible.
44+
- Do not show real `~/.codex` files, private project paths, API keys, tokens, logs, or personal notes.
45+
- Keep terminal font large enough to read on mobile.
46+
- End on the updated guidance file and the status command.
47+

‎docs/launch.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Launch Materials
2+
3+
Repo: https://github.com/sugarpoo/codex-learning-loop
4+
5+
## 1-Sentence Pitch
6+
7+
Codex Learning Loop is a safe local learning loop for Codex on macOS that maintains guidance files future Codex sessions can read.
8+
9+
## 3-Sentence Pitch
10+
11+
Codex Learning Loop gives Codex a file-based memory workflow without pretending to train the model. It captures reusable learning candidates, reviews them on a daily/catch-up schedule, and updates global guidance files under `~/.codex`. It is designed for people who use `AGENTS.md`, automate local workflows, and want a conservative way to reduce repeated mistakes across sessions.
12+
13+
## 1-Paragraph Pitch
14+
15+
Codex Learning Loop is a small macOS project for Codex users who want reusable lessons to survive beyond one session. It writes learning candidates to a local inbox, runs a LaunchAgent-backed maintenance pass with catch-up handling, and promotes clear lessons into files such as `GLOBAL_MEMORY.md`, `ERROR_PATTERNS.md`, and `AGENTS.md`. It does not train or fine-tune Codex, scan the whole computer, or replace human review. It simply maintains local guidance files under `~/.codex` that future Codex sessions can read.
16+
17+
## X/Twitter Post
18+
19+
I made Codex Learning Loop: a local macOS workflow that helps Codex keep reusable lessons across sessions.
20+
21+
It captures learning candidates, runs daily/catch-up maintenance, and updates guidance files like `AGENTS.md`, `GLOBAL_MEMORY.md`, and `ERROR_PATTERNS.md`.
22+
23+
It does not train the model. It keeps local files future Codex sessions can read.
24+
25+
https://github.com/sugarpoo/codex-learning-loop
26+
27+
## LinkedIn Post
28+
29+
I published Codex Learning Loop, a small macOS project for people using Codex in repeated development workflows.
30+
31+
The idea is simple: when Codex or a user notices a reusable lesson, it can be written as a learning candidate under `~/.codex`. A daily LaunchAgent maintenance pass reviews candidates, handles catch-up after missed runs, and updates local guidance files such as `AGENTS.md`, `GLOBAL_MEMORY.md`, and `ERROR_PATTERNS.md`.
32+
33+
This is not model training or fine-tuning. It is a file-based memory workflow that keeps future Codex sessions more consistent while staying scoped to local Codex files.
34+
35+
Repo: https://github.com/sugarpoo/codex-learning-loop
36+
37+
## Reddit Post
38+
39+
Title: I built a local learning loop for Codex on macOS
40+
41+
I use Codex across sessions and wanted a safer way to keep reusable lessons around without pretending the model is self-training.
42+
43+
Codex Learning Loop is a local, file-based workflow under `~/.codex`. It lets you capture learning candidates, then a daily/catch-up LaunchAgent maintenance pass can classify them into guidance files such as `AGENTS.md`, `GLOBAL_MEMORY.md`, and `ERROR_PATTERNS.md`.
44+
45+
It does not read all chats, scan the whole computer, or train the model. It maintains plain-text guidance files that future Codex sessions can read.
46+
47+
Repo: https://github.com/sugarpoo/codex-learning-loop
48+
49+
## Hacker News Show HN Post
50+
51+
Title: Show HN: Codex Learning Loop, a local file-based memory workflow for Codex
52+
53+
I built Codex Learning Loop for macOS users who want Codex to carry reusable lessons across sessions through local guidance files.
54+
55+
The project captures learning candidates into `~/.codex/learning-inbox`, runs a daily LaunchAgent maintenance job with catch-up handling, and updates files such as `GLOBAL_MEMORY.md`, `ERROR_PATTERNS.md`, and `AGENTS.md`.
56+
57+
It does not train or fine-tune the model. It keeps a conservative, local, reviewable file workflow that future Codex sessions can read.
58+
59+
Repo: https://github.com/sugarpoo/codex-learning-loop
60+
61+
## Discord/Slack Short Post
62+
63+
I published Codex Learning Loop: a local macOS workflow that keeps reusable Codex lessons in files like `AGENTS.md`, `GLOBAL_MEMORY.md`, and `ERROR_PATTERNS.md`. It uses a daily/catch-up LaunchAgent and stays scoped to `~/.codex`. It does not train the model. https://github.com/sugarpoo/codex-learning-loop
64+
65+
## Product Hunt Style Tagline
66+
67+
A safe local learning loop for Codex on macOS.
68+
69+
## FAQ
70+
71+
### Does this train Codex?
72+
73+
No. It does not train, fine-tune, or modify the model. It maintains local guidance files future Codex sessions can read.
74+
75+
### Does it read all my chats?
76+
77+
No. The workflow is file-based. It processes learning candidates and Codex-owned guidance files under `~/.codex`.
78+
79+
### Does it scan my whole computer?
80+
81+
No. The maintenance workflow is scoped to `~/.codex` and is designed to avoid unrelated files.
82+
83+
### Why use this instead of manually editing AGENTS.md?
84+
85+
Manual editing works. This project adds a repeatable inbox, classification rubric, reports, archive, and daily/catch-up maintenance so useful lessons are easier to review and keep.
86+
87+
### What should I put in a learning candidate?
88+
89+
Short, factual, reusable lessons. Good candidates describe a repeated mistake, a safer workflow, or a durable preference. Do not include secrets, private logs, personal notes, or sensitive information.
90+
91+
### Is this only for macOS?
92+
93+
The current automation is macOS-focused because it uses LaunchAgents. The file layout and scripts may still be useful as references for other systems.
94+

‎docs/public-launch-checklist.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Public Launch Checklist
2+
3+
- [x] README polished.
4+
- [ ] Release created.
5+
- [ ] Topics added.
6+
- [ ] Actions passing.
7+
- [ ] Safety scan complete.
8+
- [ ] Demo GIF added.
9+
- [ ] Post on X/Twitter.
10+
- [ ] Post on LinkedIn.
11+
- [ ] Post on Reddit.
12+
- [ ] Post on Hacker News.
13+
- [ ] Share in relevant developer communities.
14+
- [ ] Respond to issues quickly.
15+
- [ ] Add first good-first-issues.
16+
- [ ] Create v0.1.1 after feedback.

0 commit comments

Comments
 (0)