Skip to content

Commit 6638819

Browse files
Extend bg-sync to Codex CLI and Gemini CLI
Both agents have SessionStart hook support analogous to Claude Code's; only OpenCode lacks it upstream (anomalyco/opencode#5409). - pkg/agents/session_start_hook.go: generalized the hook helper to take load/save fn parameters and an agent-specific entry map. Replaces the previous Claude-only claude_hook.go. - pkg/agents/{claude,codex,gemini}.go: each Install (when not --no-bg-sync) writes its agent-specific entry shape: * Claude — minimal: just {type, command} * Codex — TOML; adds matcher="startup|resume" + statusMessage; prints a trust-ceremony note since Codex requires `/hooks` to trust new entries before they fire * Gemini — adds matcher="*", name="repocache-bg-sync", timeout=5000 - Each Uninstall removes hooks tracked in sidecar state. README + SPEC §8.6 updated to document the three-agent matrix and each agent's hook schema. Verified end-to-end against all four agents with --agents=all: ✓ Codex TOML serializes correctly as [[hooks.SessionStart.hooks]], ✓ all three hook-supporting agents install + uninstall cleanly, ✓ user content (model/theme keys) preserved across install/uninstall, ✓ idempotent re-install. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
1 parent 6302263 commit 6638819

7 files changed

Lines changed: 225 additions & 125 deletions

File tree

‎README.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -99,9 +99,12 @@ If you've ever watched an agent:
9999
| Agent | Doc file | Allowed-dir setting | SessionStart bg-sync |
100100
|-------|----------|---------------------|----------------------|
101101
| Claude Code | `~/.claude/CLAUDE.md` ← `@REPOCACHE.md` | `~/.claude/settings.json` → `permissions.additionalDirectories` | Yes |
102-
| Codex CLI | `~/.codex/AGENTS.md` ← `@REPOCACHE.md` | `~/.codex/config.toml` → `sandbox_workspace_write.writable_roots` | No |
103-
| Gemini CLI | `~/.gemini/GEMINI.md` ← `@REPOCACHE.md` | `~/.gemini/settings.json` → `includeDirectories` | No |
104-
| OpenCode | `~/.config/opencode/AGENTS.md` ← `@REPOCACHE.md` | `~/.config/opencode/opencode.json` → `external_directory` | No |
102+
| Codex CLI | `~/.codex/AGENTS.md` ← `@REPOCACHE.md` | `~/.codex/config.toml` → `sandbox_workspace_write.writable_roots` | Yes (requires trust)¹ |
103+
| Gemini CLI | `~/.gemini/GEMINI.md` ← `@REPOCACHE.md` | `~/.gemini/settings.json` → `includeDirectories` | Yes |
104+
| OpenCode | `~/.config/opencode/AGENTS.md` ← `@REPOCACHE.md` | `~/.config/opencode/opencode.json` → `external_directory` | No² |
105+
106+
¹ Codex requires you to trust new hooks before they run. After `repocache init`, open Codex CLI once and run `/hooks` to trust the entry.
107+
² OpenCode does not yet support a `SessionStart` hook ([upstream feature request](https://github.com/sst/opencode/issues/5409)).
105108

106109
All edits are idempotent and tagged with a `repocache:managed` marker so `repocache uninstall` removes only what repocache added, preserving any other entries you've set.
107110

@@ -197,6 +200,7 @@ If `git clone <url>` works in your shell, repocache works.
197200
- **Removing a repo doesn't free disk by itself.** `repocache repo rm <name>` removes the config entry but leaves the cache on disk. To free the disk: `chmod -R u+w ~/.local/share/repocache/repos/<name> && rm -rf ~/.local/share/repocache/repos/<name>`. The chmod is necessary because the cache tree is read-only.
198201
- **Large repos.** Repocache does full clones. No sparse-checkout or partial-clone yet. Chromium/llvm-sized repos will feel it.
199202
- **OpenCode project-shadow bug.** When a project-level `AGENTS.md` exists, OpenCode silently ignores the global one — including `@REPOCACHE.md`. Upstream issue; `init` prints a warning.
203+
- **No bg-sync for OpenCode.** OpenCode doesn't have a `SessionStart` hook yet. Other three agents auto-refresh stale repos on session start.
200204
- **No MCP server in v1.** The CLI is the only surface. MCP wrappers can be added later.
201205

202206
---

‎SPEC.md‎

Lines changed: 44 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -351,9 +351,9 @@ Each supported agent's install touches up to three files. All edits are idempote
351351
| Agent | Detection | Files written | Background sync? |
352352
|-------|-----------|---------------|------------------|
353353
| Claude Code | `~/.claude/` exists | `~/.claude/REPOCACHE.md`, `~/.claude/CLAUDE.md`, `~/.claude/settings.json` | Yes |
354-
| Codex CLI | `~/.codex/` exists | `~/.codex/REPOCACHE.md`, `~/.codex/AGENTS.md`, `~/.codex/config.toml` | No |
355-
| Gemini CLI | `~/.gemini/` exists | `~/.gemini/REPOCACHE.md`, `~/.gemini/GEMINI.md`, `~/.gemini/settings.json` | No |
356-
| OpenCode | `~/.config/opencode/` exists | `~/.config/opencode/REPOCACHE.md`, `~/.config/opencode/AGENTS.md`, `~/.config/opencode/opencode.json` | No |
354+
| Codex CLI | `~/.codex/` exists | `~/.codex/REPOCACHE.md`, `~/.codex/AGENTS.md`, `~/.codex/config.toml` | Yes (requires user to run `/hooks` once to trust) |
355+
| Gemini CLI | `~/.gemini/` exists | `~/.gemini/REPOCACHE.md`, `~/.gemini/GEMINI.md`, `~/.gemini/settings.json` | Yes |
356+
| OpenCode | `~/.config/opencode/` exists | `~/.config/opencode/REPOCACHE.md`, `~/.config/opencode/AGENTS.md`, `~/.config/opencode/opencode.json` | No (upstream lacks SessionStart) |
357357

358358
### 8.2 REPOCACHE.md content
359359

@@ -427,20 +427,51 @@ The sidecar state file (`agents.state.json`) records, per agent:
427427

428428
Uninstall reads this file to know exactly what to remove. If the user has hand-edited the agent's config and our entries are gone, uninstall is a no-op for those.
429429

430-
### 8.6 SessionStart hook (Claude Code only)
430+
### 8.6 SessionStart hook (Claude, Codex, Gemini)
431431

432-
Added to `~/.claude/settings.json` under `hooks.SessionStart`:
432+
All three agents with a SessionStart-equivalent get the same wrapper
433+
command (`repocache __bg-sync`) installed. The hook entry shape is
434+
agent-specific.
433435

436+
**Claude Code** — `~/.claude/settings.json`:
434437
```jsonc
438+
{
439+
"hooks": {
440+
"SessionStart": [
441+
{ "hooks": [ { "type": "command", "command": "repocache __bg-sync" } ] }
442+
]
443+
}
444+
}
445+
```
446+
447+
**Codex CLI** — `~/.codex/config.toml`:
448+
```toml
449+
[[hooks.SessionStart]]
450+
matcher = "startup|resume"
451+
452+
[[hooks.SessionStart.hooks]]
453+
type = "command"
454+
command = "repocache __bg-sync"
455+
statusMessage = "repocache bg-sync"
456+
```
457+
458+
Codex requires the user to trust new hooks via the `/hooks` command
459+
before they run. `repocache init` prints a one-line note after
460+
installing the Codex hook.
461+
462+
**Gemini CLI** — `~/.gemini/settings.json`:
463+
```json
435464
{
436465
"hooks": {
437466
"SessionStart": [
438467
{
468+
"matcher": "*",
439469
"hooks": [
440470
{
471+
"name": "repocache-bg-sync",
441472
"type": "command",
442-
"command": "repocache __bg-sync"
443-
// repocache:managed:bg-sync
473+
"command": "repocache __bg-sync",
474+
"timeout": 5000
444475
}
445476
]
446477
}
@@ -449,7 +480,12 @@ Added to `~/.claude/settings.json` under `hooks.SessionStart`:
449480
}
450481
```
451482

452-
Sidecar state records the addition. Uninstall removes by sidecar.
483+
**OpenCode** — no SessionStart hook upstream
484+
([sst/opencode#5409](https://github.com/sst/opencode/issues/5409)).
485+
`init` skips this step for OpenCode and surfaces nothing.
486+
487+
Sidecar state records each successful hook addition; uninstall reverses
488+
exactly those entries.
453489

454490
### 8.7 Failure modes
455491

‎pkg/agents/claude.go‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,15 @@ func (c *Claude) Install(opts InstallOptions) (Installed, error) {
4848
}
4949
var hooks []string
5050
if !opts.NoBgSync {
51-
addedHook, err := ensureSessionStartHook(c.settingsFile(), BgSyncCommand)
51+
entry := map[string]any{
52+
"hooks": []any{
53+
map[string]any{
54+
"type": "command",
55+
"command": BgSyncCommand,
56+
},
57+
},
58+
}
59+
addedHook, err := ensureSessionStartHook(loadJSONC, saveJSON, c.settingsFile(), entry, BgSyncCommand)
5260
if err != nil {
5361
return Installed{}, err
5462
}
@@ -74,7 +82,7 @@ func (c *Claude) Uninstall(prev Installed) error {
7482
}
7583
}
7684
for _, hookCmd := range prev.AddedHooks {
77-
if err := removeSessionStartHook(c.settingsFile(), hookCmd); err != nil {
85+
if err := removeSessionStartHook(loadJSONC, saveJSON, c.settingsFile(), hookCmd); err != nil {
7886
return err
7987
}
8088
}

‎pkg/agents/claude_hook.go‎

Lines changed: 0 additions & 106 deletions
This file was deleted.

‎pkg/agents/codex.go‎

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,14 +28,14 @@ func (c *Codex) docFile() string { return filepath.Join(c.dir, "REPOCACHE.m
2828
func (c *Codex) memoryFile() string { return filepath.Join(c.dir, "AGENTS.md") }
2929
func (c *Codex) settingsFile() string { return filepath.Join(c.dir, "config.toml") }
3030

31-
func (c *Codex) Install(_ InstallOptions) (Installed, error) {
31+
func (c *Codex) Install(opts InstallOptions) (Installed, error) {
3232
if err := os.MkdirAll(c.dir, 0755); err != nil {
3333
return Installed{}, err
3434
}
3535
if err := os.WriteFile(c.docFile(), DocContent, 0644); err != nil {
3636
return Installed{}, fmt.Errorf("write %s: %w", c.docFile(), err)
3737
}
38-
added, err := ensureImportLine(c.memoryFile(), "REPOCACHE.md")
38+
addedImport, err := ensureImportLine(c.memoryFile(), "REPOCACHE.md")
3939
if err != nil {
4040
return Installed{}, err
4141
}
@@ -44,9 +44,32 @@ func (c *Codex) Install(_ InstallOptions) (Installed, error) {
4444
if err != nil {
4545
return Installed{}, err
4646
}
47+
var hooks []string
48+
if !opts.NoBgSync {
49+
entry := map[string]any{
50+
"matcher": "startup|resume",
51+
"hooks": []any{
52+
map[string]any{
53+
"type": "command",
54+
"command": BgSyncCommand,
55+
"statusMessage": "repocache bg-sync",
56+
},
57+
},
58+
}
59+
addedHook, err := ensureSessionStartHook(loadTOML, saveTOML, c.settingsFile(), entry, BgSyncCommand)
60+
if err != nil {
61+
return Installed{}, err
62+
}
63+
if addedHook {
64+
hooks = []string{BgSyncCommand}
65+
fmt.Fprintln(os.Stderr, " note: Codex requires you to trust new hooks before they run.")
66+
fmt.Fprintln(os.Stderr, " Open Codex CLI and run `/hooks` once to trust this hook.")
67+
}
68+
}
4769
return Installed{
4870
AddedPaths: paths,
49-
AddedImports: importLineRecord(added, "REPOCACHE.md"),
71+
AddedImports: importLineRecord(addedImport, "REPOCACHE.md"),
72+
AddedHooks: hooks,
5073
}, nil
5174
}
5275

@@ -60,6 +83,11 @@ func (c *Codex) Uninstall(prev Installed) error {
6083
return err
6184
}
6285
}
86+
for _, hookCmd := range prev.AddedHooks {
87+
if err := removeSessionStartHook(loadTOML, saveTOML, c.settingsFile(), hookCmd); err != nil {
88+
return err
89+
}
90+
}
6391
_ = os.Remove(c.docFile())
6492
return nil
6593
}

‎pkg/agents/gemini.go‎

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,14 +28,14 @@ func (g *Gemini) docFile() string { return filepath.Join(g.dir, "REPOCACHE.
2828
func (g *Gemini) memoryFile() string { return filepath.Join(g.dir, "GEMINI.md") }
2929
func (g *Gemini) settingsFile() string { return filepath.Join(g.dir, "settings.json") }
3030

31-
func (g *Gemini) Install(_ InstallOptions) (Installed, error) {
31+
func (g *Gemini) Install(opts InstallOptions) (Installed, error) {
3232
if err := os.MkdirAll(g.dir, 0755); err != nil {
3333
return Installed{}, err
3434
}
3535
if err := os.WriteFile(g.docFile(), DocContent, 0644); err != nil {
3636
return Installed{}, fmt.Errorf("write %s: %w", g.docFile(), err)
3737
}
38-
added, err := ensureImportLine(g.memoryFile(), "REPOCACHE.md")
38+
addedImport, err := ensureImportLine(g.memoryFile(), "REPOCACHE.md")
3939
if err != nil {
4040
return Installed{}, err
4141
}
@@ -44,9 +44,31 @@ func (g *Gemini) Install(_ InstallOptions) (Installed, error) {
4444
if err != nil {
4545
return Installed{}, err
4646
}
47+
var hooks []string
48+
if !opts.NoBgSync {
49+
entry := map[string]any{
50+
"matcher": "*",
51+
"hooks": []any{
52+
map[string]any{
53+
"name": "repocache-bg-sync",
54+
"type": "command",
55+
"command": BgSyncCommand,
56+
"timeout": 5000,
57+
},
58+
},
59+
}
60+
addedHook, err := ensureSessionStartHook(loadJSONC, saveJSON, g.settingsFile(), entry, BgSyncCommand)
61+
if err != nil {
62+
return Installed{}, err
63+
}
64+
if addedHook {
65+
hooks = []string{BgSyncCommand}
66+
}
67+
}
4768
return Installed{
4869
AddedPaths: paths,
49-
AddedImports: importLineRecord(added, "REPOCACHE.md"),
70+
AddedImports: importLineRecord(addedImport, "REPOCACHE.md"),
71+
AddedHooks: hooks,
5072
}, nil
5173
}
5274

@@ -60,6 +82,11 @@ func (g *Gemini) Uninstall(prev Installed) error {
6082
return err
6183
}
6284
}
85+
for _, hookCmd := range prev.AddedHooks {
86+
if err := removeSessionStartHook(loadJSONC, saveJSON, g.settingsFile(), hookCmd); err != nil {
87+
return err
88+
}
89+
}
6390
_ = os.Remove(g.docFile())
6491
return nil
6592
}

0 commit comments

Comments
 (0)