Skip to content

Commit 5973f9b

Browse files
phernandezphernandez
authored
feat(plugins): add codex plugin package (#894)
Signed-off-by: phernandez <paul@basicmachines.co>
1 parent 8887267 commit 5973f9b

41 files changed

Lines changed: 1558 additions & 2 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/plugins/marketplace.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"name": "basic-memory-local",
3+
"interface": {
4+
"displayName": "Basic Memory Local"
5+
},
6+
"plugins": [
7+
{
8+
"name": "codex",
9+
"source": {
10+
"source": "local",
11+
"path": "./plugins/codex"
12+
},
13+
"policy": {
14+
"installation": "AVAILABLE",
15+
"authentication": "ON_INSTALL"
16+
},
17+
"category": "Developer Tools"
18+
}
19+
]
20+
}

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ ENV/
5555
claude-output
5656
**/.claude/settings.local.json
5757
.mcp.json
58+
!/plugins/codex/.mcp.json
5859
.mcpregistry_*
5960
/.testmondata
6061
.benchmarks/

‎justfile‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -265,8 +265,8 @@ check: lint format typecheck test
265265
# Run all code quality checks and all test suites, including semantic benchmarks
266266
check-all: lint format typecheck test test-semantic
267267

268-
# Validate every consolidated agent package (Claude Code, skills, Hermes, OpenClaw)
269-
package-check: package-check-claude-code package-check-skills package-check-hermes package-check-openclaw
268+
# Validate every consolidated agent package (Claude Code, Codex, skills, Hermes, OpenClaw)
269+
package-check: package-check-claude-code package-check-codex package-check-skills package-check-hermes package-check-openclaw
270270

271271
# Alias for plugin/package validation during consolidation work
272272
plugins-check: package-check
@@ -278,6 +278,10 @@ agent-harness-check: package-check-claude-code package-check-hermes package-chec
278278
package-check-claude-code:
279279
just --justfile plugins/claude-code/justfile --working-directory plugins/claude-code check
280280

281+
# Codex plugin: manifest, bundled skills, hooks, MCP config, and schemas
282+
package-check-codex:
283+
just --justfile plugins/codex/justfile --working-directory plugins/codex check
284+
281285
# Shared top-level SKILL.md source
282286
package-check-skills:
283287
just --justfile skills/justfile --working-directory skills check

‎plugins/codex/.codex-plugin/plugin.json‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
{
2+
"name": "codex",
3+
"version": "0.1.0+codex.20260604201213",
4+
"description": "A Codex-native bridge to Basic Memory for durable engineering context, decisions, and resumable checkpoints.",
5+
"author": {
6+
"name": "Basic Machines",
7+
"email": "hello@basicmachines.co",
8+
"url": "https://basicmemory.com"
9+
},
10+
"homepage": "https://docs.basicmemory.com",
11+
"repository": "https://github.com/basicmachines-co/basic-memory/tree/main/plugins/codex",
12+
"license": "MIT",
13+
"keywords": [
14+
"basic-memory",
15+
"codex",
16+
"memory",
17+
"knowledge-graph",
18+
"mcp",
19+
"checkpoints"
20+
],
21+
"skills": "./skills/",
22+
"mcpServers": "./.mcp.json",
23+
"interface": {
24+
"displayName": "Basic Memory for Codex",
25+
"shortDescription": "Carry decisions, active work, and handoffs across Codex threads",
26+
"longDescription": "Use Basic Memory for Codex to orient from your durable knowledge graph, capture engineering decisions, checkpoint long-running work, and resume with repo-backed context across Codex sessions.",
27+
"developerName": "Basic Machines",
28+
"category": "Developer Tools",
29+
"capabilities": [
30+
"Interactive",
31+
"Read",
32+
"Write"
33+
],
34+
"websiteURL": "https://basicmemory.com",
35+
"privacyPolicyURL": "https://basicmemory.com/privacy",
36+
"termsOfServiceURL": "https://basicmemory.com/terms",
37+
"defaultPrompt": [
38+
"Use Basic Memory to orient before changing this repo.",
39+
"Checkpoint this Codex thread into Basic Memory.",
40+
"Capture the decision we just made."
41+
],
42+
"brandColor": "#2563EB",
43+
"composerIcon": "./assets/app-icon.png",
44+
"logo": "./assets/logo.png"
45+
}
46+
}

‎plugins/codex/.mcp.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"mcpServers": {
3+
"basic-memory": {
4+
"command": "uvx",
5+
"args": [
6+
"basic-memory",
7+
"mcp"
8+
]
9+
}
10+
}
11+
}

‎plugins/codex/DEVELOPMENT.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Basic Memory Codex Plugin Development
2+
3+
This plugin is developed in-place from the Basic Memory repository. Codex installs local plugins
4+
through marketplaces, so local testing uses a repo-local marketplace wrapper rather than publishing
5+
anything external.
6+
7+
## Local Marketplace
8+
9+
The repo marketplace lives at:
10+
11+
```text
12+
.agents/plugins/marketplace.json
13+
```
14+
15+
It exposes this plugin as:
16+
17+
```text
18+
codex@basic-memory-local
19+
```
20+
21+
The marketplace entry points at `./plugins/codex`, resolved relative to the repository root.
22+
23+
## First-Time Setup
24+
25+
From the repository root:
26+
27+
```bash
28+
codex plugin marketplace add "$(git rev-parse --show-toplevel)"
29+
codex plugin add codex@basic-memory-local
30+
```
31+
32+
Start a new Codex thread after installing. New threads are the reliable boundary for picking up
33+
plugin skills, hooks, and MCP configuration.
34+
35+
Plugin installation is user-level in Codex, so one install makes the plugin available across
36+
projects on the same machine. Repo-specific memory routing still comes from each checkout's
37+
`.codex/basic-memory.json`.
38+
39+
## Iteration Loop
40+
41+
After changing files in `plugins/codex`, run the local checks:
42+
43+
```bash
44+
just package-check-codex
45+
```
46+
47+
Then update the manifest cachebuster and reinstall from the local marketplace:
48+
49+
```bash
50+
python3 "$CODEX_PLUGIN_CREATOR_SCRIPTS/update_plugin_cachebuster.py" \
51+
"$(git rev-parse --show-toplevel)/plugins/codex"
52+
codex plugin add codex@basic-memory-local
53+
```
54+
55+
Start a fresh Codex thread to test the updated plugin.
56+
57+
## Useful Checks
58+
59+
List configured marketplaces:
60+
61+
```bash
62+
codex plugin marketplace list
63+
```
64+
65+
List plugins Codex can see:
66+
67+
```bash
68+
codex plugin list
69+
```
70+
71+
Run the full package validation gate when touching plugin packaging, shared skills, or integration
72+
metadata:
73+
74+
```bash
75+
just package-check
76+
```
77+
78+
To also run Codex's scaffold validator during `just package-check-codex`, set
79+
`CODEX_PLUGIN_VALIDATOR` to the local `plugin-creator` validator script before
80+
running the check.

‎plugins/codex/README.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Basic Memory for Codex
2+
3+
Basic Memory for Codex is the Codex-native bridge between a working coding thread
4+
and Basic Memory's durable knowledge graph.
5+
6+
It is not a 1:1 copy of the Claude Code plugin. This version leans into Codex
7+
workflows: repo orientation, long-running goals, changed-file evidence, explicit
8+
verification, decision capture, and resumable checkpoints.
9+
10+
## What It Does
11+
12+
- **Orient from memory.** The `bm-orient` skill reads active tasks, open
13+
decisions, and recent Codex checkpoints before substantial work.
14+
- **Checkpoint work.** The `bm-checkpoint` skill and `PreCompact` hook write
15+
`type: codex_session` notes with the current work cursor.
16+
- **Capture decisions.** The `bm-decide` skill records durable engineering
17+
decisions with rationale, alternatives, and consequences.
18+
- **Remember lightly.** The `bm-remember` skill saves small facts without turning
19+
them into a full decision or session note.
20+
- **Share deliberately.** The `bm-share` skill copies personal notes to configured
21+
team projects only after confirmation.
22+
- **Report status.** The `bm-status` skill shows configuration, reachability, and
23+
recent memory state.
24+
25+
## Package Contents
26+
27+
| Path | Role |
28+
| --- | --- |
29+
| `.codex-plugin/plugin.json` | Codex plugin manifest |
30+
| `.mcp.json` | Basic Memory MCP server configuration |
31+
| `hooks/hooks.json` | SessionStart and PreCompact hook registration |
32+
| `hooks/session-start.sh` | Launches the SessionStart uv script |
33+
| `hooks/session-start.py` | Injects a compact memory brief at thread start |
34+
| `hooks/pre-compact.sh` | Launches the PreCompact uv script |
35+
| `hooks/pre-compact.py` | Writes an automatic Codex checkpoint before compaction |
36+
| `skills/` | Codex-native Basic Memory workflows |
37+
| `schemas/` | Seed schemas for Codex sessions, decisions, and tasks |
38+
39+
## Install
40+
41+
Install the plugin once from the Basic Memory repository root:
42+
43+
```bash
44+
codex plugin marketplace add "$(git rev-parse --show-toplevel)"
45+
codex plugin add codex@basic-memory-local
46+
```
47+
48+
Plugin installation is user-level in Codex, so one install makes the plugin
49+
available across projects on the same machine. Start a new Codex thread after
50+
installing so Codex can load the plugin skills, MCP configuration, and hooks.
51+
52+
Each repository still needs its own `.codex/basic-memory.json` so the plugin
53+
knows which Basic Memory project and folders to use for that checkout. Run the
54+
setup skill in each repo, or create the config file shown below.
55+
56+
## Configuration
57+
58+
Run the setup skill, or create `.codex/basic-memory.json` in a repo:
59+
60+
```json
61+
{
62+
"basicMemory": {
63+
"primaryProject": "my-project",
64+
"secondaryProjects": [],
65+
"teamProjects": {},
66+
"focus": "code/dev",
67+
"captureFolder": "codex-sessions",
68+
"rememberFolder": "codex-remember",
69+
"recallTimeframe": "7d",
70+
"placementConventions": "Put decisions in decisions/ and work checkpoints in codex-sessions/."
71+
}
72+
}
73+
```
74+
75+
Codex plugin hooks must be reviewed and trusted before they run. Open `/hooks` in
76+
Codex after enabling the plugin and trust the Basic Memory hook definitions.
77+
78+
## Development
79+
80+
From this directory:
81+
82+
```bash
83+
just check
84+
```
85+
86+
From the repo root:
87+
88+
```bash
89+
just package-check-codex
90+
```
91+
92+
The package intentionally keeps Codex-specific configuration separate from
93+
Claude's `.claude/settings.json`.

‎plugins/codex/assets/app-icon.png‎

10.1 KB
Loading

‎plugins/codex/assets/logo.png‎

10.1 KB
Loading

‎plugins/codex/hooks/hooks.json‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"description": "Basic Memory for Codex hooks - orient from the graph on session start and checkpoint before compaction.",
3+
"hooks": {
4+
"SessionStart": [
5+
{
6+
"matcher": "startup|resume|compact",
7+
"hooks": [
8+
{
9+
"type": "command",
10+
"command": "${PLUGIN_ROOT}/hooks/session-start.sh",
11+
"statusMessage": "Loading Basic Memory context",
12+
"timeout": 30
13+
}
14+
]
15+
}
16+
],
17+
"PreCompact": [
18+
{
19+
"matcher": "manual|auto",
20+
"hooks": [
21+
{
22+
"type": "command",
23+
"command": "${PLUGIN_ROOT}/hooks/pre-compact.sh",
24+
"statusMessage": "Checkpointing Codex work to Basic Memory",
25+
"timeout": 60
26+
}
27+
]
28+
}
29+
]
30+
}
31+
}

0 commit comments

Comments
 (0)