|
3 | 3 | This document is the authoritative reference for the public Lua API exposed by |
4 | 4 | `codex.nvim`. |
5 | 5 |
|
| 6 | +> [!NOTE] |
| 7 | +> In this document, `codex` refers to `require("codex")`. |
| 8 | +
|
6 | 9 | For `:Codex*` command flow and internal command-to-component behavior, see |
7 | 10 | [`docs/command-interactions.md`](./command-interactions.md). |
8 | 11 |
|
9 | | -## Return Conventions |
| 12 | +## Table of Contents |
10 | 13 |
|
11 | | -Send-like, wrapper-command, resume, and mention APIs return: |
| 14 | +- [Return Conventions](#return-conventions) |
| 15 | +- [Setup and Runtime](#setup-and-runtime) |
| 16 | +- [Session Control](#session-control) |
| 17 | +- [Sending and Input](#sending-and-input) |
| 18 | +- [Slash and Wrapper Commands](#slash-and-wrapper-commands) |
| 19 | +- [Mention Helpers](#mention-helpers) |
| 20 | +- [Terminal Keymap Builtins](#terminal-keymap-builtins) |
12 | 21 |
|
13 | | -- `ok` (`boolean`) whether the request was sent immediately or queued |
14 | | - successfully. |
15 | | -- `err` (`string|nil`) error details when the request could not be dispatched. |
| 22 | +## Return Conventions |
16 | 23 |
|
17 | | -Query-style APIs such as `is_running()`, `get_config()`, and `get_logs()` use |
18 | | -their own return shapes documented in their sections below. |
| 24 | +| API Scope | Return Shape | Notes | |
| 25 | +| ------------------------------------------------------------------------- | ------------- | ------------------------------------------ | |
| 26 | +| Send-like, wrapper-command, resume, and mention APIs | `ok, err` | `ok` is `boolean`; `err` is `string\|nil`. | |
| 27 | +| Query-style APIs such as `is_running()`, `get_config()`, and `get_logs()` | Varies by API | See the per-API return details below. | |
19 | 28 |
|
20 | 29 | ## Setup and Runtime |
21 | 30 |
|
22 | | -### `require("codex").setup(opts)` |
23 | | - |
24 | | -Initialize plugin config and runtime state, register `:Codex*` commands, and |
25 | | -wire the send queue and lifecycle collaborators. |
26 | | - |
27 | | -Call this before using the other public APIs. |
28 | | - |
29 | | -### `require("codex").is_running()` |
30 | | - |
31 | | -Return whether the active Codex session is currently alive. |
32 | | - |
33 | | -### `require("codex").get_config()` |
34 | | - |
35 | | -Return a deep-copied snapshot of the resolved config, or `nil` before setup. |
36 | | - |
37 | | -### `require("codex").get_logs()` |
38 | | - |
39 | | -Return captured in-memory log entries. |
40 | | - |
41 | | -### `require("codex").clear_logs()` |
42 | | - |
43 | | -Clear captured in-memory log entries. |
| 31 | +| API | Description | Options / Inputs | Returns | |
| 32 | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------ | |
| 33 | +| `codex.setup(opts)` | Initialize plugin config and runtime state, register `:Codex*` commands, and wire the send queue and lifecycle collaborators. | `opts` (`table\|nil`): setup options. Call before using the other public APIs. | `nil` | |
| 34 | +| `codex.is_running()` | Return whether the active Codex session is currently alive. | None | `boolean` | |
| 35 | +| `codex.get_config()` | Return a deep-copied snapshot of the resolved config. | None | `table\|nil` | |
| 36 | +| `codex.get_logs()` | Return captured in-memory log entries. | None | `codex.LogEntry[]` | |
| 37 | +| `codex.clear_logs()` | Clear captured in-memory log entries. | None | `nil` | |
44 | 38 |
|
45 | 39 | ## Session Control |
46 | 40 |
|
47 | | -### `require("codex").open(focus)` |
48 | | - |
49 | | -Open a Codex terminal session. When `focus` is omitted, it defaults to `true`. |
50 | | - |
51 | | -### `require("codex").close()` |
52 | | - |
53 | | -Close the active session and reset the send queue. |
54 | | - |
55 | | -### `require("codex").toggle()` |
56 | | - |
57 | | -Toggle the active terminal if one is running, otherwise open a focused session. |
58 | | - |
59 | | -### `require("codex").focus()` |
60 | | - |
61 | | -Focus the active session, or open one when no session is running. |
| 41 | +| API | Description | Options / Inputs | Returns | |
| 42 | +| ------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------- | |
| 43 | +| `codex.open(focus)` | Open a Codex terminal session. | `focus` (`boolean\|nil`): defaults to `true` when omitted. | `nil` | |
| 44 | +| `codex.close()` | Close the active session and reset the send queue. | None | `nil` | |
| 45 | +| `codex.toggle()` | Toggle the active terminal if one is running, otherwise open a focused session. | None | `nil` | |
| 46 | +| `codex.focus()` | Focus the active session, or open one when no session is running. | None | `nil` | |
62 | 47 |
|
63 | 48 | ## Sending and Input |
64 | 49 |
|
65 | | -### `require("codex").send(text)` |
66 | | - |
67 | | -Send raw text through the standard send pipeline. |
68 | | - |
69 | | -- `text` (`string`): payload to send. |
70 | | - |
71 | | -### `require("codex").clear_input()` |
72 | | - |
73 | | -Send `<C-c>` to the active Codex terminal to clear the current prompt input. |
74 | | - |
75 | | -### `require("codex").send_command(slash_cmd)` |
76 | | - |
77 | | -Normalize and send a slash command, then auto-submit it with Enter. |
78 | | - |
79 | | -- `slash_cmd` (`string`): command name with or without a leading `/`. |
80 | | - |
81 | | -### `require("codex").send_buffer(opts)` |
82 | | - |
83 | | -Send a file reference as `@path` with a trailing space. |
84 | | - |
85 | | -Options: |
86 | | - |
87 | | -- `opts.path` (`string|nil`): explicit file path to send; takes precedence over |
88 | | - `opts.bufnr`. |
89 | | -- `opts.bufnr` (`integer|nil`): buffer to resolve when `opts.path` is omitted. |
90 | | -- `opts.focus` (`boolean|nil`): set to `false` to keep editor focus after |
91 | | - sending; defaults to focused send behavior. |
92 | | - |
93 | | -Returns an error when the target buffer or path cannot be resolved to a regular |
94 | | -file. |
95 | | - |
96 | | -### `require("codex").send_selection(opts)` |
97 | | - |
98 | | -Send a formatted selection reference plus fenced code block, with a trailing |
99 | | -newline after the block. |
100 | | - |
101 | | -Options: |
102 | | - |
103 | | -- `opts.line1` (`integer|nil`): start line for an explicit range. |
104 | | -- `opts.line2` (`integer|nil`): end line for an explicit range. |
105 | | -- `opts.visual_mode` (`string|nil`): visual mode override when needed by custom |
106 | | - callers. |
107 | | - |
108 | | -When `opts` is omitted, the function falls back to the current visual |
109 | | -selection/range. |
| 50 | +| API | Description | Options / Inputs | Returns | |
| 51 | +| ------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | |
| 52 | +| `codex.send(text)` | Send raw text through the standard send pipeline. | `text` (`string`): payload to send. | `ok, err` | |
| 53 | +| `codex.clear_input()` | Send `<C-c>` to the active Codex terminal to clear the current prompt input. | None | `ok, err` | |
| 54 | +| `codex.send_command(slash_cmd)` | Normalize and send a slash command, then auto-submit it with Enter. | `slash_cmd` (`string`): command name with or without a leading `/`. | `ok, err` | |
| 55 | +| `codex.send_buffer(opts)` | Send a file reference as `@path` with a trailing space. | `opts.path` (`string\|nil`): explicit file path, takes precedence over `opts.bufnr`.<br>`opts.bufnr` (`integer\|nil`): buffer to resolve when `opts.path` is omitted.<br>`opts.focus` (`boolean\|nil`): set to `false` to keep editor focus after sending. | `ok, err` | |
| 56 | +| `codex.send_selection(opts)` | Send a formatted selection reference plus fenced code block, with a trailing newline after the block. | `opts.line1` (`integer\|nil`): explicit start line.<br>`opts.line2` (`integer\|nil`): explicit end line.<br>`opts.visual_mode` (`string\|nil`): visual mode override for custom callers.<br>When omitted, `opts` falls back to the current visual selection/range. | `ok, err` | |
110 | 57 |
|
111 | 58 | ## Slash and Wrapper Commands |
112 | 59 |
|
113 | | -### `require("codex").set_model()` |
114 | | - |
115 | | -Send `/model` using the wrapper-command autosubmit flow. |
116 | | - |
117 | | -### `require("codex").show_status()` |
118 | | - |
119 | | -Send `/status` using the wrapper-command autosubmit flow. |
120 | | - |
121 | | -### `require("codex").show_permissions()` |
122 | | - |
123 | | -Send `/permissions` using the wrapper-command autosubmit flow. |
124 | | - |
125 | | -### `require("codex").compact()` |
126 | | - |
127 | | -Send `/compact` using the wrapper-command autosubmit flow. |
128 | | - |
129 | | -### `require("codex").review(instructions)` |
130 | | - |
131 | | -Send `/review`, optionally with inline instructions. |
132 | | - |
133 | | -- `instructions` (`string|nil`): appended after `review ` when present and |
134 | | - non-empty. |
135 | | - |
136 | | -### `require("codex").show_diff()` |
137 | | - |
138 | | -Send `/diff` using the wrapper-command autosubmit flow. |
139 | | - |
140 | | -### `require("codex").resume(opts)` |
141 | | - |
142 | | -Resume in-process when an active session exists; otherwise open `codex resume`. |
143 | | - |
144 | | -Options: |
145 | | - |
146 | | -- `opts.last` (`boolean|nil`): when launching a new process, use |
147 | | - `codex resume --last`. |
148 | | - |
149 | | -Returns `true` after opening a new resume process, or the standard `ok, err` |
150 | | -result when dispatching in-process `/resume`. |
| 60 | +| API | Description | Options / Inputs | Returns | |
| 61 | +| ---------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | |
| 62 | +| `codex.set_model()` | Send `/model` using the wrapper-command autosubmit flow. | None | `ok, err` | |
| 63 | +| `codex.show_status()` | Send `/status` using the wrapper-command autosubmit flow. | None | `ok, err` | |
| 64 | +| `codex.show_permissions()` | Send `/permissions` using the wrapper-command autosubmit flow. | None | `ok, err` | |
| 65 | +| `codex.compact()` | Send `/compact` using the wrapper-command autosubmit flow. | None | `ok, err` | |
| 66 | +| `codex.review(instructions)` | Send `/review`, optionally with inline instructions. | `instructions` (`string\|nil`): appended after `review` when present and non-empty. | `ok, err` | |
| 67 | +| `codex.show_diff()` | Send `/diff` using the wrapper-command autosubmit flow. | None | `ok, err` | |
| 68 | +| `codex.resume(opts)` | Resume in-process when an active session exists; otherwise open `codex resume`. | `opts.last` (`boolean\|nil`): when launching a new process, use `codex resume --last`. | `ok, err` for in-process `/resume`; `true` after opening a new resume process. | |
151 | 69 |
|
152 | 70 | ## Mention Helpers |
153 | 71 |
|
154 | | -### `require("codex").mention_file(path, opts)` |
155 | | - |
156 | | -Send `/mention` for a file path, auto-submit it, then restore previously |
157 | | -captured prompt input. |
158 | | - |
159 | | -- `path` (`string|nil`): explicit file path; when omitted, uses the current |
160 | | - buffer path. |
161 | | -- `opts.post_execute` (`fun(ok, err)|nil`): callback invoked after mention |
162 | | - execution completes. |
163 | | - |
164 | | -### `require("codex").mention_directory(path, opts)` |
165 | | - |
166 | | -Send `/mention` for a directory path, auto-submit it, then restore previously |
167 | | -captured prompt input. |
168 | | - |
169 | | -- `path` (`string|nil`): explicit directory path; when omitted, uses the |
170 | | - current buffer directory. |
171 | | -- `opts.post_execute` (`fun(ok, err)|nil`): callback invoked after mention |
172 | | - execution completes. |
| 72 | +| API | Description | Options / Inputs | Returns | |
| 73 | +| ------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | |
| 74 | +| `codex.mention_file(path, opts)` | Send `/mention` for a file path, auto-submit it, then restore previously captured prompt input. | `path` (`string\|nil`): explicit file path; when omitted, uses the current buffer path.<br>`opts.post_execute` (`fun(ok, err)\|nil`): callback invoked after mention execution completes. | `ok, err` | |
| 75 | +| `codex.mention_directory(path, opts)` | Send `/mention` for a directory path, auto-submit it, then restore previously captured prompt input. | `path` (`string\|nil`): explicit directory path; when omitted, uses the current buffer directory.<br>`opts.post_execute` (`fun(ok, err)\|nil`): callback invoked after mention execution completes. | `ok, err` | |
173 | 76 |
|
174 | 77 | ## Terminal Keymap Builtins |
175 | 78 |
|
176 | | -### `require("codex.keymaps").builtins` |
177 | | - |
178 | | -Builtin terminal keymap actions for use in `terminal.keymaps` config: |
179 | | - |
180 | | -- `toggle` |
181 | | -- `clear_input` |
182 | | -- `close` |
183 | | -- `nav_left` |
184 | | -- `nav_down` |
185 | | -- `nav_up` |
186 | | -- `nav_right` |
187 | | - |
188 | | -These are action functions intended for terminal-buffer mappings and carry |
189 | | -builtin descriptions automatically when used through the keymap helper module. |
| 79 | +| API | Description | Available Actions | Returns | |
| 80 | +| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------- | |
| 81 | +| `require("codex.keymaps").builtins` | Builtin terminal keymap actions for use in `terminal.keymaps` config. These are action functions intended for terminal-buffer mappings and carry builtin descriptions automatically when used through the keymap helper module. | `toggle`, `clear_input`, `close`, `nav_left`, `nav_down`, `nav_up`, `nav_right` | `table<string, function>` | |
0 commit comments