You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add Codex CLI provider and project integration (#348)
* feat: add Codex CLI provider and project integration (#195)
Add a local Codex CLI LLM provider built on authenticated `codex exec`
sessions: argv-based subprocess (no shell), JSONL parsing tolerant of
non-JSON noise, an async semaphore, a 600s exec timeout with kill, reasoning
mapped to `model_reasoning_effort`, and zero-cost subscription usage tracking
(flagged `estimated` when Codex omits usage).
Add project-local Codex setup: `.codex/config.toml` MCP server, `.codex`
lifecycle hooks (SessionStart / UserPromptSubmit / PostToolUse) installed via
the import-isolated `repowise-augment` entry point, `.codex-plugin` metadata,
skills, a plugin marketplace entry, and managed `AGENTS.md` generation reusing
the existing marker-merge generator.
Wire reasoning across all LLM providers (base interface + per-provider model
discovery and supported reasoning modes) and add a richer interactive
provider / model / reasoning selection flow to `repowise init`, with new
`--codex/--no-codex` and `--agents/--no-agents` flags. Codex setup is opt-in:
interactive runs prompt (default no); non-interactive runs require `--codex`.
Squashes the six commits from #195 and rebases them onto current main,
resolving conflicts from the init_cmd/ and ui/ package splits, the
editor-setup integration abstraction, and the provider cost-tracker
inline-await change:
- feat: add Codex editor integration
- docs: document Codex setup
- Reasoning work
- Add provider model discovery to init
- Accept cache hints in Codex provider
- Close Codex subprocess transport
* fix(codex): address review — event-loop blocking, TOML safety, hook gating
Follow-up fixes from a post-merge review of the Codex integration:
- Run the Codex `_build_command` reasoning-catalog load and Gemini's lazy
model discovery via `asyncio.to_thread`, so a cold `codex debug models`
call or a paginated Gemini `/models` fetch can't stall every concurrent
generation coroutine on the event loop.
- Re-validate the merged `.codex/config.toml` with `tomllib` before writing
in `save_codex_mcp_config` / `enable_codex_hooks_feature`. The table-rewrite
regex only matches the bare key spelling; a quoted or inline `repowise`/
`features` entry would otherwise append a duplicate-key block and corrupt
the user's file. Now it aborts cleanly, original file untouched.
- Gate the edit-tool PostToolUse freshness notice on `client == "codex"` so a
future widening of the Claude installer's matcher can't emit Codex banners
to existing Claude Code users. Adds a regression test.
---------
Co-authored-by: Selene29 <funmailfach@web.de>
Copy file name to clipboardExpand all lines: docs/CLI_REFERENCE.md
+19-6Lines changed: 19 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -42,15 +42,15 @@ repowise init .
42
42
1.**Ingestion** — walks every file, parses AST with tree-sitter, builds a two-tier dependency graph (file + symbol nodes), indexes git history (churn, hotspots, ownership, bus factor)
43
43
2.**Analysis** — detects dead code, extracts architectural decisions from inline markers, READMEs, and git history. Runs Leiden community detection and execution flow tracing.
44
44
3.**Generation** — sends structured prompts to the LLM, generates file-level, module-level, and repo-level wiki pages
45
-
4.**Persistence** — stores everything in `.repowise/wiki.db`, builds search indexes, generates `CLAUDE.md`, registers MCP server and Claude Code hooks
45
+
4.**Persistence** — stores everything in `.repowise/wiki.db`, builds search indexes, generates editor instruction files, registers MCP server and hooks
repowise init . --index-only -x "node_modules/"# workspace, no LLM
87
91
```
@@ -99,13 +103,14 @@ Incrementally update wiki pages for files changed since the last sync.
99
103
|`--provider`| Override LLM provider for this run |
100
104
|`--model`| Override model |
101
105
|`--since`| Git ref to diff from (overrides `state.json`) |
102
-
|`--reasoning`| Reasoning mode for supported providers: `auto`, `off`, or `minimal`|
106
+
|`--reasoning`| Reasoning mode for supported providers: `auto`, `off`/`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`|
103
107
|`--cascade-budget`| Max pages to regenerate (default: auto) |
104
108
|`--dry-run`| Show what would be updated without regenerating |
105
109
|`--workspace`| Update all stale repos in the workspace + cross-repo analysis |
106
110
|`--no-workspace`| Force single-repo mode (handy when running from a workspace root) |
107
111
|`--repo`| Update a specific workspace repo by alias |
108
112
|`--full`| Upgrade a fast (`--mode fast`) index to a full one — see below. Single-repo only. |
113
+
|`--agents / --no-agents`| Generate or skip managed `AGENTS.md` after update. Persists the preference. |
109
114
110
115
**First-time indexing:** as of v0.8, `update --workspace` now runs full first-time indexing for workspace entries that have no `.repowise/` dir yet (previously skipped with `"not_indexed"`). The pipeline runs index-only — no LLM cost — and writes a state.json marker so `repowise update --repo <alias> --docs` later picks up doc generation cleanly.
111
116
@@ -452,6 +457,8 @@ See [Auto-Sync](AUTO_SYNC.md) for all sync methods (hooks, file watcher, webhook
452
457
453
458
Start the MCP server for AI editor integration.
454
459
460
+
If `PATH` is omitted, `repowise mcp` first walks upward from the current directory to the nearest initialized `.repowise` repository. This lets project-local Codex config use `args = ["mcp"]` with `cwd` set to the repo root.
461
+
455
462
**Options:**
456
463
457
464
| Flag | Description |
@@ -460,7 +467,7 @@ Start the MCP server for AI editor integration.
460
467
|`--port`| Port for SSE transport (default: 7338) |
461
468
462
469
```bash
463
-
repowise mcp --transport stdio # for Claude Code, Cursor, etc.
470
+
repowise mcp --transport stdio # for Claude Code, Codex, Cursor, etc.
464
471
repowise mcp --transport sse --port 7338 # for web clients
`repowise init --codex` generates managed `AGENTS.md` for Codex. `repowise update` refreshes it when `editor_files.agents_md` is enabled in config, or when `--agents` is passed. User content outside the Repowise managed markers is preserved.
493
+
494
+
---
495
+
483
496
### `repowise export [PATH]`
484
497
485
498
Export wiki pages to files.
@@ -560,4 +573,4 @@ repowise delete <repo-id> --force # delete a specific repo's index, no pr
560
573
561
574
### `repowise augment`
562
575
563
-
Hook-driven context enrichment engine. Not meant to be called manually — invoked by Claude Code hooks installed during `repowise init`.
576
+
Hook-driven context enrichment engine. Not meant to be called manually — invoked by Claude Code and Codex hooks installed during `repowise init`. Claude Code uses it for search-result enrichment and stale-wiki checks; Codex uses it for `SessionStart`, `UserPromptSubmit`, and `PostToolUse` lifecycle guidance.
- Project setup for Codex MCP and lifecycle hooks.
6
+
- The `codex_cli` LLM provider for wiki generation through your authenticated Codex CLI subscription.
7
+
- A local Codex plugin with bundled MCP, hooks, and Repowise skills.
8
+
9
+
These features use project-local files. `repowise init --codex` writes under the repository, not to global `~/.codex/config.toml`.
10
+
11
+
## Prerequisites
12
+
13
+
Install and authenticate the Codex CLI:
14
+
15
+
```bash
16
+
npm install -g @openai/codex
17
+
codex login
18
+
codex login status
19
+
```
20
+
21
+
Repowise checks `codex --version` and `codex login status`. When both succeed, interactive `repowise init` offers to enable Codex project setup. Non-interactive runs require `--codex`; use `--no-codex` to skip the prompt.
22
+
23
+
## Project MCP Setup
24
+
25
+
Run from the repository root:
26
+
27
+
```bash
28
+
repowise init --codex
29
+
```
30
+
31
+
Repowise merges this server into `.codex/config.toml`:
32
+
33
+
```toml
34
+
[mcp_servers.repowise]
35
+
command = "repowise"
36
+
args = ["mcp"]
37
+
cwd = "/absolute/path/to/repo"
38
+
startup_timeout_sec = 20
39
+
40
+
[features]
41
+
hooks = true
42
+
```
43
+
44
+
The MCP server uses `repowise mcp` without a path. In no-path mode, Repowise walks upward from the current directory to the nearest initialized `.repowise` repository.
45
+
46
+
Smoke check:
47
+
48
+
```bash
49
+
codex mcp list
50
+
```
51
+
52
+
## Codex Hooks
53
+
54
+
Repowise writes hooks to `.codex/hooks.json`, not inline `[hooks]` tables. The default hooks call the import-isolated `repowise-augment` entry point for:
55
+
56
+
-`SessionStart` to add Repowise MCP workflow guidance.
57
+
-`UserPromptSubmit` to remind Codex when Repowise context is available.
58
+
-`PostToolUse` for `Bash` to detect git operations that make the wiki stale.
59
+
-`PostToolUse` for `apply_patch`, `Edit`, and `Write` to remind Codex after edits.
60
+
61
+
Claude Code has its own search-result enrichment hook path for `Grep` and `Glob`. Codex setup stays focused on lifecycle guidance and freshness checks instead of trying to reuse that Claude-specific search enrichment.
62
+
63
+
## `codex_cli` Provider
64
+
65
+
Use `codex_cli` when you want Repowise page generation to run through your Codex CLI subscription instead of an API key:
Repowise sends the prompt on stdin, parses Codex JSONL output, records token usage from `turn.completed.usage`, and treats `codex_cli/*` cost as `$0.00` because subscription billing happens outside Repowise API pricing. `--model` is passed to Codex only when you explicitly configure a model. `--reasoning minimal` maps to Codex `model_reasoning_effort="low"`; `low`, `medium`, `high`, and `xhigh` pass through when the selected Codex model advertises those levels. `off`/`none` is not supported by the Codex CLI provider.
From the Repowise repository root, add the local marketplace to Codex, then install the Repowise plugin from the Codex plugin browser:
104
+
105
+
```bash
106
+
codex plugin marketplace add .
107
+
codex
108
+
/plugins
109
+
```
110
+
111
+
The plugin bundles Repowise MCP, lifecycle hooks, and Codex-neutral skills for exploration, pre-modification checks, architectural decisions, and dead-code cleanup. It does not add Claude-style slash commands. Plugin-bundled hooks are opt-in in current Codex releases; enable them with `[features] plugin_hooks = true` if you want hooks loaded from an installed plugin.
112
+
113
+
## AGENTS.md
114
+
115
+
`repowise init --codex` generates a managed `AGENTS.md` by default. `repowise update` refreshes it when `editor_files.agents_md` is enabled, or when `--agents` is passed. The Repowise section is bounded by managed markers and user content outside the markers is preserved.
116
+
117
+
Controls:
118
+
119
+
```bash
120
+
repowise init --no-agents
121
+
repowise init --agents
122
+
repowise update --no-agents
123
+
repowise update --agents
124
+
```
125
+
126
+
The generated section tells Codex when to use Repowise MCP tools for overview, search, context, risk, why/decision history, dependency tracing, diagrams, and dead-code cleanup.
Copy file name to clipboardExpand all lines: docs/MCP_TOOLS.md
+8-7Lines changed: 8 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,15 @@
1
1
# MCP Tools Reference
2
2
3
-
repowise exposes 9 tools via the [Model Context Protocol](https://modelcontextprotocol.io) (MCP). These tools give AI coding assistants (Claude Code, Cursor, Cline, Windsurf) structured access to your codebase intelligence — dependency graph, git history, documentation, and architectural decisions.
3
+
repowise exposes 9 tools via the [Model Context Protocol](https://modelcontextprotocol.io) (MCP). These tools give AI coding assistants (Claude Code, Codex, Cursor, Cline, Windsurf) structured access to your codebase intelligence — dependency graph, git history, documentation, and architectural decisions.
4
4
5
5
**Start the MCP server:**
6
6
7
7
```bash
8
-
repowise mcp --transport stdio # for Claude Code, Cursor, etc.
8
+
repowise mcp --transport stdio # for Claude Code, Codex, Cursor, etc.
9
9
repowise mcp --transport sse --port 7338 # for web clients
10
10
```
11
11
12
-
**Auto-setup for Claude Code:**`repowise init` automatically registers the MCP server and installs proactive hooks. No manual configuration needed.
12
+
**Auto-setup:**`repowise init` automatically registers the MCP server and installs proactive hooks for Claude Code. `repowise init --codex` writes project-local Codex MCP config and hooks.
13
13
14
14
---
15
15
@@ -287,9 +287,10 @@ The MCP server automatically enriches responses with cross-repo intelligence:
287
287
288
288
## Proactive Hooks (Complementary)
289
289
290
-
In addition to the 9 MCP tools, `repowise init` installs Claude Code hooks that provide **passive, automatic** context enrichment:
290
+
In addition to the 9 MCP tools, `repowise init` installs AI-agent hooks (Claude Code and Codex) that provide **passive, automatic** context enrichment:
291
291
292
-
-**PreToolUse** — every `Grep`/`Glob` call is enriched with graph context (symbols, importers, dependencies, git signals) at ~24ms latency
293
-
-**PostToolUse** — after git commits, the agent is notified when the wiki is stale
292
+
-**Claude Code PostToolUse** — broad or zero-result `Grep`/`Glob` calls can be enriched with graph context, and git operations can trigger stale-wiki notices.
293
+
-**Codex SessionStart/UserPromptSubmit** — Codex receives concise Repowise MCP workflow guidance when a session or prompt starts.
294
+
-**Codex PostToolUse** — after edits or git operations, Codex receives a freshness reminder when indexed context may be stale.
294
295
295
-
Hooks fire automatically on every search. MCP tools are for deeper, on-demand investigation. See [Auto-Sync](AUTO_SYNC.md) for details.
296
+
Hooks are lightweight reminders. MCP tools are for deeper, on-demand investigation. See [Auto-Sync](AUTO_SYNC.md) and [Codex Integration](CODEX.md) for details.
Or `OPENAI_API_KEY`, `GEMINI_API_KEY` — whichever provider you installed.
26
34
35
+
If you use Codex as the LLM provider, authenticate the Codex CLI instead:
36
+
37
+
```bash
38
+
codex login status
39
+
```
40
+
27
41
On Windows PowerShell:
28
42
29
43
```powershell
@@ -39,6 +53,12 @@ repowise init
39
53
40
54
Repowise will walk you through an interactive setup — choose a provider, review the cost estimate, and confirm. It parses every file, builds a dependency graph, indexes git history, and generates wiki pages.
41
55
56
+
Codex users can force project-local MCP/hooks setup and use the Codex CLI provider in one command:
57
+
58
+
```bash
59
+
repowise init --codex --provider codex_cli --yes
60
+
```
61
+
42
62
A typical run on a ~500-file codebase takes 5-15 minutes.
43
63
44
64
**Want to skip LLM costs?** Use `--index-only` to just parse and analyze without generating docs:
@@ -67,13 +87,15 @@ repowise serve
67
87
68
88
If Node.js 20+ is installed, the web UI starts automatically. Otherwise, use Docker (see below).
69
89
70
-
**Connect to your AI editor (Claude Code, Cursor, Cline, Windsurf):**
90
+
**Connect to your AI editor (Claude Code, Codex, Cursor, Cline, Windsurf):**
71
91
72
92
```bash
73
93
repowise mcp --transport stdio
74
94
```
75
95
76
-
> **Automatic for Claude Code:**`repowise init` already registers the MCP server and installs PreToolUse/PostToolUse hooks in `~/.claude/settings.json`. Every `Grep`/`Glob` call is automatically enriched with graph context (importers, dependencies, symbols, git signals). After git commits, the agent is notified when the wiki is stale.
96
+
> **Automatic for Claude Code:**`repowise init` already registers the MCP server and installs PostToolUse hooks in `~/.claude/settings.json`. Broad or zero-result `Grep`/`Glob` searches can receive graph context, and git operations can notify the agent when the wiki is stale.
97
+
98
+
> **Automatic for Codex:** run `repowise init --codex` to write project-local `.codex/config.toml`, `.codex/hooks.json`, and managed `AGENTS.md`. See [Codex Integration](CODEX.md).
0 commit comments