@kodus/cli 0.1.12 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (102) hide show
  1. package/README.md +293 -208
  2. package/dist/cli.d.ts.map +1 -1
  3. package/dist/cli.js +2 -0
  4. package/dist/cli.js.map +1 -1
  5. package/dist/commands/__tests__/auth.team-key.test.js +16 -0
  6. package/dist/commands/__tests__/auth.team-key.test.js.map +1 -1
  7. package/dist/commands/__tests__/capture-api.test.d.ts +2 -0
  8. package/dist/commands/__tests__/capture-api.test.d.ts.map +1 -0
  9. package/dist/commands/__tests__/capture-api.test.js +88 -0
  10. package/dist/commands/__tests__/capture-api.test.js.map +1 -0
  11. package/dist/commands/__tests__/disable.test.d.ts +2 -0
  12. package/dist/commands/__tests__/disable.test.d.ts.map +1 -0
  13. package/dist/commands/__tests__/disable.test.js +103 -0
  14. package/dist/commands/__tests__/disable.test.js.map +1 -0
  15. package/dist/commands/__tests__/enable.test.d.ts +2 -0
  16. package/dist/commands/__tests__/enable.test.d.ts.map +1 -0
  17. package/dist/commands/__tests__/enable.test.js +103 -0
  18. package/dist/commands/__tests__/enable.test.js.map +1 -0
  19. package/dist/commands/__tests__/install-merge-hook.test.d.ts +2 -0
  20. package/dist/commands/__tests__/install-merge-hook.test.d.ts.map +1 -0
  21. package/dist/commands/__tests__/install-merge-hook.test.js +54 -0
  22. package/dist/commands/__tests__/install-merge-hook.test.js.map +1 -0
  23. package/dist/commands/auth/team-key.d.ts.map +1 -1
  24. package/dist/commands/auth/team-key.js +1 -1
  25. package/dist/commands/auth/team-key.js.map +1 -1
  26. package/dist/commands/memory/capture.d.ts +8 -0
  27. package/dist/commands/memory/capture.d.ts.map +1 -0
  28. package/dist/commands/memory/capture.js +173 -0
  29. package/dist/commands/memory/capture.js.map +1 -0
  30. package/dist/commands/memory/disable.d.ts +2 -0
  31. package/dist/commands/memory/disable.d.ts.map +1 -0
  32. package/dist/commands/memory/disable.js +20 -0
  33. package/dist/commands/memory/disable.js.map +1 -0
  34. package/dist/commands/memory/enable.d.ts +8 -0
  35. package/dist/commands/memory/enable.d.ts.map +1 -0
  36. package/dist/commands/memory/enable.js +81 -0
  37. package/dist/commands/memory/enable.js.map +1 -0
  38. package/dist/commands/memory/hooks.d.ts +45 -0
  39. package/dist/commands/memory/hooks.d.ts.map +1 -0
  40. package/dist/commands/memory/hooks.js +347 -0
  41. package/dist/commands/memory/hooks.js.map +1 -0
  42. package/dist/commands/memory/index.d.ts +3 -0
  43. package/dist/commands/memory/index.d.ts.map +1 -0
  44. package/dist/commands/memory/index.js +44 -0
  45. package/dist/commands/memory/index.js.map +1 -0
  46. package/dist/commands/memory/promote.d.ts +7 -0
  47. package/dist/commands/memory/promote.d.ts.map +1 -0
  48. package/dist/commands/memory/promote.js +38 -0
  49. package/dist/commands/memory/promote.js.map +1 -0
  50. package/dist/commands/memory/show.d.ts +2 -0
  51. package/dist/commands/memory/show.d.ts.map +1 -0
  52. package/dist/commands/memory/show.js +44 -0
  53. package/dist/commands/memory/show.js.map +1 -0
  54. package/dist/commands/memory/status.d.ts +2 -0
  55. package/dist/commands/memory/status.d.ts.map +1 -0
  56. package/dist/commands/memory/status.js +54 -0
  57. package/dist/commands/memory/status.js.map +1 -0
  58. package/dist/services/__tests__/memory.service.test.d.ts +2 -0
  59. package/dist/services/__tests__/memory.service.test.d.ts.map +1 -0
  60. package/dist/services/__tests__/memory.service.test.js +279 -0
  61. package/dist/services/__tests__/memory.service.test.js.map +1 -0
  62. package/dist/services/__tests__/transcript-parser.service.test.d.ts +2 -0
  63. package/dist/services/__tests__/transcript-parser.service.test.d.ts.map +1 -0
  64. package/dist/services/__tests__/transcript-parser.service.test.js +134 -0
  65. package/dist/services/__tests__/transcript-parser.service.test.js.map +1 -0
  66. package/dist/services/api/__tests__/api.real.test.js +11 -0
  67. package/dist/services/api/__tests__/api.real.test.js.map +1 -1
  68. package/dist/services/api/api.interface.d.ts +5 -1
  69. package/dist/services/api/api.interface.d.ts.map +1 -1
  70. package/dist/services/api/api.real.d.ts +2 -1
  71. package/dist/services/api/api.real.d.ts.map +1 -1
  72. package/dist/services/api/api.real.js +15 -1
  73. package/dist/services/api/api.real.js.map +1 -1
  74. package/dist/services/api/index.d.ts +1 -1
  75. package/dist/services/api/index.d.ts.map +1 -1
  76. package/dist/services/git.service.d.ts +1 -0
  77. package/dist/services/git.service.d.ts.map +1 -1
  78. package/dist/services/git.service.js +9 -0
  79. package/dist/services/git.service.js.map +1 -1
  80. package/dist/services/memory.service.d.ts +49 -0
  81. package/dist/services/memory.service.d.ts.map +1 -0
  82. package/dist/services/memory.service.js +450 -0
  83. package/dist/services/memory.service.js.map +1 -0
  84. package/dist/services/transcript-parser.service.d.ts +10 -0
  85. package/dist/services/transcript-parser.service.d.ts.map +1 -0
  86. package/dist/services/transcript-parser.service.js +96 -0
  87. package/dist/services/transcript-parser.service.js.map +1 -0
  88. package/dist/types/index.d.ts +1 -0
  89. package/dist/types/index.d.ts.map +1 -1
  90. package/dist/types/memory.d.ts +85 -0
  91. package/dist/types/memory.d.ts.map +1 -0
  92. package/dist/types/memory.js +2 -0
  93. package/dist/types/memory.js.map +1 -0
  94. package/dist/utils/__tests__/module-matcher.test.d.ts +2 -0
  95. package/dist/utils/__tests__/module-matcher.test.d.ts.map +1 -0
  96. package/dist/utils/__tests__/module-matcher.test.js +164 -0
  97. package/dist/utils/__tests__/module-matcher.test.js.map +1 -0
  98. package/dist/utils/module-matcher.d.ts +6 -0
  99. package/dist/utils/module-matcher.d.ts.map +1 -0
  100. package/dist/utils/module-matcher.js +94 -0
  101. package/dist/utils/module-matcher.js.map +1 -0
  102. package/package.json +3 -2
package/README.md CHANGED
@@ -1,335 +1,420 @@
1
- # Kodus CLI
1
+ <!-- TODO: Add banner image/logo here -->
2
2
 
3
- AI-powered code review from your terminal.
3
+ <h1 align="center">Kodus CLI</h1>
4
4
 
5
- ## Installation
5
+ <p align="center">
6
+ <strong>Catch bugs before they reach your pull request — AI code review from the terminal.</strong>
7
+ </p>
8
+
9
+ <p align="center">
10
+ <a href="https://www.npmjs.com/package/@kodus/cli"><img src="https://img.shields.io/npm/v/@kodus/cli.svg" alt="npm version"></a>
11
+ <a href="https://www.npmjs.com/package/@kodus/cli"><img src="https://img.shields.io/npm/dm/@kodus/cli.svg" alt="npm downloads"></a>
12
+ <a href="https://github.com/kodustech/cli/blob/main/LICENSE"><img src="https://img.shields.io/github/license/kodustech/cli" alt="license"></a>
13
+ <a href="https://github.com/kodustech/cli"><img src="https://img.shields.io/github/stars/kodustech/cli" alt="stars"></a>
14
+ <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node version"></a>
15
+ </p>
6
16
 
7
- ### npm (Recommended)
17
+ <p align="center">
18
+ <a href="https://kodus.io">Website</a> &middot;
19
+ <a href="https://app.kodus.io">Sign Up</a> &middot;
20
+ <a href="https://github.com/kodustech/cli/issues">Issues</a>
21
+ </p>
22
+
23
+ ---
8
24
 
9
25
  ```bash
10
26
  npm install -g @kodus/cli
11
27
  ```
12
28
 
13
- ### Via curl
29
+ ---
30
+
31
+ ## Quick Start
14
32
 
15
33
  ```bash
16
- curl -fsSL https://raw.githubusercontent.com/kodustech/cli/main/install.sh | bash
34
+ # 1. Install
35
+ npm install -g @kodus/cli
36
+
37
+ # 2. Authenticate (or skip for trial mode — no account needed)
38
+ kodus auth login
39
+
40
+ # 3. Review your code
41
+ kodus review
17
42
  ```
18
43
 
19
- ### Homebrew (Coming soon)
44
+ That's it. Kodus analyzes your changes, finds issues, and lets you fix them interactively — or auto-fix everything at once with `kodus review --fix`.
45
+
46
+ <!-- TODO: Add demo GIF showing interactive review in action -->
47
+
48
+ ## What It Does
49
+
50
+ ### Code Review
51
+
52
+ Analyze local changes, staged files, commits, or branch diffs. Kodus finds bugs, security issues, performance problems, and style violations — then suggests fixes with real code.
20
53
 
21
54
  ```bash
22
- brew install kodus/tap/kodus
55
+ kodus review # Review working tree changes (interactive)
56
+ kodus review --staged # Only staged files
57
+ kodus review --branch main # Compare against a branch
58
+ kodus review --fix # Auto-apply all fixable issues
59
+ kodus review --prompt-only # Structured output for AI agents
23
60
  ```
24
61
 
25
- ### Using npx (No installation)
62
+ Reviews are **context-aware** — Kodus reads your `.cursorrules`, `claude.md`, and `.kodus.md` so suggestions follow your team's standards. [More on review modes](#review-modes)
63
+
64
+ ### PR Suggestions
65
+
66
+ Fetch AI-powered suggestions for open pull requests directly from your terminal.
26
67
 
27
68
  ```bash
28
- npx @kodus/cli review
69
+ kodus pr suggestions --pr-url https://github.com/org/repo/pull/42
70
+ kodus pr suggestions --pr-number 42 --repo-id <id>
29
71
  ```
30
72
 
31
- ## Quick Start
73
+ Filter by severity, export as JSON or Markdown, or pipe into an AI agent with `--prompt-only` for automated fixes.
32
74
 
33
- ```bash
34
- # Run an interactive review (default mode)
35
- kodus review
75
+ ### Decision Memory
36
76
 
37
- # Run a review on staged files (interactive)
38
- kodus review --staged
77
+ AI agents make dozens of decisions per session — architecture choices, trade-offs, why approach X was picked over Y. Without a record, that reasoning vanishes when the session ends.
39
78
 
40
- # Run a review on a specific commit (interactive)
41
- kodus review --commit HEAD~1
79
+ Kodus captures agent decisions into your repo as structured markdown. When you or another agent return to the code, the full context is there.
42
80
 
43
- # Run a review comparing against another branch (interactive)
44
- kodus review --branch main
81
+ ```bash
82
+ kodus decisions enable # Install hooks + initialize config
83
+ kodus decisions status # See what's been captured
84
+ kodus decisions show [name] # View PR or module memory
85
+ kodus decisions promote # Promote decisions to long-term memory
86
+ ```
45
87
 
46
- # Run a review on specific files (interactive)
47
- kodus review src/index.ts src/utils.ts
88
+ Stored in `.kody/pr/by-sha/<head-sha>.md` versioned with your code, readable by humans and agents. [More on decision memory](#decision-memory-1)
48
89
 
49
- # Review using only configured rules (no general suggestions)
50
- kodus review --rules-only
90
+ ---
51
91
 
52
- # Fast mode: quicker analysis (good for large diffs)
53
- kodus review --fast
92
+ ## Best With AI Agents
54
93
 
55
- # Auto-fix: apply all fixable issues automatically
56
- kodus review --fix
94
+ Kodus is designed to work **inside AI coding agents**. While you can use it standalone, the real power comes when your agent runs reviews automatically and fixes issues in a loop — no manual intervention needed.
57
95
 
58
- # Non-interactive modes:
59
- # - JSON output
60
- kodus review --format json
96
+ **Works with:** Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, and [20+ more environments](https://review-skill.com/).
61
97
 
62
- # - Markdown report
63
- kodus review --format markdown
98
+ ### Install the Skill (recommended)
64
99
 
65
- # - AI Agent mode (optimized for Claude Code, Cursor, etc)
66
- kodus review --prompt-only
100
+ The fastest way to get started. Auto-detects your installed IDEs and sets everything up:
101
+
102
+ ```bash
103
+ curl -fsSL https://review-skill.com/install | bash
67
104
  ```
68
105
 
69
- ## Authentication
106
+ This installs the Kodus CLI globally and deploys the review skill into every supported agent on your machine — Claude Code, Cursor, Windsurf, and others. One command, all environments.
70
107
 
71
- Sign up at **https://app.kodus.io** to create your account.
108
+ ### How It Works With Agents
72
109
 
73
- ```bash
74
- # Login with your account
75
- kodus auth login
110
+ Once installed, your AI agent can autonomously:
111
+
112
+ 1. **Write code** as usual
113
+ 2. **Run `kodus review --prompt-only`** to analyze changes
114
+ 3. **Read the structured output** and understand each issue
115
+ 4. **Fix the issues** automatically
116
+ 5. **Repeat** until the review is clean
117
+
118
+ This creates a tight feedback loop: the agent writes, reviews, and fixes — all without leaving your IDE.
119
+
120
+ Beyond reviews, Kodus also captures **what your agent decided and why** via [Decision Memory](#decision-memory). Every reasoning step is saved into your repo — so when you (or another agent) pick up the work later, the full context is already there. No more re-explaining what was done or losing decisions between sessions.
76
121
 
77
- # Check authentication status
78
- kodus auth status
122
+ ### Setup: Claude Code
79
123
 
80
- # Logout
81
- kodus auth logout
124
+ Add to your project's `CLAUDE.md`:
82
125
 
83
- # Generate CI/CD token
84
- kodus auth token
126
+ ```markdown
127
+ ## Code Review
128
+ After implementing changes, run `kodus review --prompt-only` to check for issues.
129
+ If issues are found, fix them and re-run until clean.
85
130
  ```
86
131
 
87
- ## Review Modes
132
+ Or use the skill directly — after installing via the command above, just ask Claude Code to review your code and it will use Kodus automatically.
88
133
 
89
- ### Interactive Mode (Default)
90
- Navigate through issues and apply fixes interactively:
134
+ ### Setup: Cursor / Windsurf
91
135
 
92
- ```bash
93
- # Interactive mode is now the default
94
- kodus review
136
+ Add to your `.cursorrules` or equivalent:
95
137
 
96
- # You can also explicitly enable it
97
- kodus review --interactive
98
- kodus review -i
138
+ ```
139
+ When writing code:
140
+ 1. Implement the feature
141
+ 2. Run: kodus review --prompt-only
142
+ 3. If issues are found, fix them automatically
143
+ 4. Repeat until review is clean
144
+ 5. Show final result
99
145
  ```
100
146
 
101
- Features:
102
- - **File-first navigation**: Browse files with issue counts
103
- - **Copy fix prompt**: Generate AI-friendly prompts for Claude Code, Cursor, etc.
104
- - **One-by-one review**: See issues with detailed information
105
- - **Preview fixes**: View changes before applying
106
- - **Apply fixes**: Choose which fixes to apply
107
- - **Live progress**: Track fixed vs remaining issues
147
+ ### Setup: Headless / Shared Environments
108
148
 
109
- ### Auto-fix Mode
110
- Automatically apply all fixable issues:
149
+ Set a team key so agents and shared machines are authenticated without individual logins:
111
150
 
112
151
  ```bash
113
- kodus review --fix
152
+ export KODUS_TEAM_KEY=kodus_xxxxx
153
+ kodus review --prompt-only
114
154
  ```
115
155
 
116
- Features:
117
- - Applies all auto-fixable issues at once
118
- - Shows confirmation prompt before applying
119
- - Reports success/failure for each fix
156
+ Works with Codex, CI runners, remote dev environments, and any context where personal login isn't practical. Get your key at [app.kodus.io/settings/cli](https://app.kodus.io/settings/cli).
157
+
158
+ ### Copy & Paste Workflow (interactive)
159
+
160
+ If you prefer manual control:
161
+
162
+ 1. Run `kodus review`
163
+ 2. Navigate to a file with issues
164
+ 3. Select **"Copy fix prompt for AI agent"**
165
+ 4. Paste into Claude Code or Cursor — the AI fixes it
166
+
167
+ The copied prompt includes file path, line numbers, severity, and detailed suggestions — optimized for AI agents.
168
+
169
+ ## Installation
120
170
 
121
- ### AI Agent Mode
122
- Optimized for AI coding agents (Claude Code, Cursor, Windsurf):
171
+ ### Skill installer (recommended — CLI + all your agents)
123
172
 
124
173
  ```bash
125
- kodus review --prompt-only
174
+ curl -fsSL https://review-skill.com/install | bash
126
175
  ```
127
176
 
128
- Features:
129
- - Minimal, structured output
130
- - Easy to parse programmatically
131
- - Includes fix code for auto-fixable issues
132
- - Perfect for autonomous generate-review-fix loops
177
+ Installs the CLI and deploys the review skill to all detected agents in one step.
133
178
 
134
- ## Output Formats
179
+ ### CLI only
135
180
 
136
- ```bash
137
- # Interactive mode (default)
138
- kodus review
181
+ <details>
182
+ <summary><strong>npm</strong></summary>
139
183
 
140
- # JSON output (non-interactive)
141
- kodus review --format json
184
+ ```bash
185
+ npm install -g @kodus/cli
186
+ ```
187
+ </details>
142
188
 
143
- # Markdown report (non-interactive)
144
- kodus review --format markdown
189
+ <details>
190
+ <summary><strong>npx (no install)</strong></summary>
145
191
 
146
- # AI Agent output (non-interactive)
147
- kodus review --prompt-only
192
+ ```bash
193
+ npx @kodus/cli review
194
+ ```
195
+ </details>
148
196
 
149
- # Save to file (non-interactive)
150
- kodus review --format markdown --output report.md
197
+ <details>
198
+ <summary><strong>curl</strong></summary>
151
199
 
152
- # Terminal output without interactivity
153
- kodus review --format terminal --output report.txt
200
+ ```bash
201
+ curl -fsSL https://raw.githubusercontent.com/kodustech/cli/main/install.sh | bash
154
202
  ```
203
+ </details>
155
204
 
156
- ## Context-Aware Reviews
205
+ <details>
206
+ <summary><strong>Homebrew (coming soon)</strong></summary>
157
207
 
158
- Kodus CLI automatically reads your project's context files to provide better, more relevant reviews:
208
+ ```bash
209
+ brew install kodus/tap/kodus
210
+ ```
211
+ </details>
159
212
 
160
- **Auto-detected files:**
161
- - `.cursorrules` - Cursor IDE rules
162
- - `claude.md` / `.claude.md` - Claude Code guidelines
163
- - `.kodus.md` / `.kodus/rules.md` - Kodus-specific rules
213
+ ## Review Modes
214
+
215
+ ### Interactive (default)
164
216
 
165
- **Custom context:**
166
217
  ```bash
167
- # Include custom context file
168
- kodus review --context path/to/custom-guidelines.md
218
+ kodus review
169
219
  ```
170
220
 
171
- This ensures reviews follow your team's standards, coding patterns, and architectural preferences.
221
+ Navigate files with issue counts, preview fixes before applying, and copy AI-friendly prompts to paste into Claude Code or Cursor.
222
+
223
+ ### Auto-fix
172
224
 
173
- ### Flags
225
+ ```bash
226
+ kodus review --fix
227
+ ```
174
228
 
175
- | Flag | Description | Use Case |
176
- |------|-------------|----------|
177
- | (none) | Interactive mode (default) | Local development, manual review |
178
- | `--rules-only` | Only check configured rules | Team standards, CI/CD |
179
- | `--fast` | Faster analysis with lighter checks | Large diffs, quick feedback |
180
- | `--staged` | Analyze only staged files | Pre-commit |
181
- | `--interactive` / `-i` | Explicitly enable interactive mode | When combined with other flags |
182
- | `--fix` | Auto-apply all fixable issues | Quick fixes, automation |
183
- | `--prompt-only` | AI agent optimized output | Claude Code, Cursor integration |
184
- | `--context <file>` | Include custom context file | Project-specific guidelines |
185
- | `--format json` | Output as JSON (non-interactive) | Automation, integrations |
186
- | `--output <file>` | Save to file (non-interactive) | Reports, CI/CD artifacts |
229
+ Applies all fixable issues at once. Shows a confirmation prompt before making changes.
187
230
 
188
- **Examples:**
231
+ ### AI Agent
189
232
 
190
233
  ```bash
191
- # Pre-commit: interactive check on staged files (default)
192
- kodus review --staged
234
+ kodus review --prompt-only
235
+ ```
193
236
 
194
- # CI/CD: strict rules only, JSON output
195
- kodus review --rules-only --format json
237
+ Minimal, structured output designed for Claude Code, Cursor, and Windsurf. Perfect for autonomous generate-review-fix loops.
196
238
 
197
- # Quick feedback on large changes (still interactive)
198
- kodus review --fast
239
+ <details>
240
+ <summary><strong>More: output formats &amp; flags</strong></summary>
199
241
 
200
- # Auto-fix all issues in staged files
201
- kodus review --staged --fix
242
+ #### Output Formats
202
243
 
203
- # AI agent workflow (non-interactive)
204
- kodus review --prompt-only
244
+ ```bash
245
+ kodus review # Interactive (default)
246
+ kodus review --format json # JSON output
247
+ kodus review --format markdown # Markdown report
248
+ kodus review --prompt-only # AI agent output
249
+ kodus review --format markdown -o report.md # Save to file
250
+ ```
205
251
 
206
- # Custom context with interactive mode (default)
207
- kodus review --context .github/GUIDELINES.md
252
+ #### Diff Targets
208
253
 
209
- # Copy fix prompts and paste into Claude Code
210
- kodus review # Select file → "Copy fix prompt for AI agent"
254
+ ```bash
255
+ kodus review # Working tree changes
256
+ kodus review --staged # Staged files only
257
+ kodus review --commit HEAD~1 # Specific commit
258
+ kodus review --branch main # Compare against branch
259
+ kodus review src/index.ts src/utils.ts # Specific files
211
260
  ```
212
261
 
213
- ## AI Agent Integration
262
+ #### All Flags
214
263
 
215
- Kodus CLI works seamlessly with AI coding agents like **Claude Code**, **Cursor**, and **Windsurf**.
264
+ | Flag | Description |
265
+ |------|-------------|
266
+ | `--staged` | Analyze only staged files |
267
+ | `--commit <sha>` | Analyze a specific commit |
268
+ | `--branch <name>` | Compare against a branch |
269
+ | `--rules-only` | Only check configured rules |
270
+ | `--fast` | Faster analysis for large diffs |
271
+ | `--fix` | Auto-apply all fixable issues |
272
+ | `--prompt-only` | AI agent optimized output |
273
+ | `--context <file>` | Include custom context file |
274
+ | `--format <fmt>` | Output format: `terminal`, `json`, `markdown` |
275
+ | `--output <file>` | Save output to file |
276
+ | `--fail-on <severity>` | Exit code 1 if issues meet or exceed severity |
277
+ | `-i, --interactive` | Explicitly enable interactive mode |
216
278
 
217
- ### Interactive Mode with Copy Prompt (Recommended)
279
+ </details>
218
280
 
219
- The easiest way to use with AI agents:
281
+ ## Decision Memory
282
+
283
+ Full reference for the decision capture system ([intro above](#decision-memory)).
220
284
 
221
285
  ```bash
222
- # 1. Run interactive review
223
- kodus review
286
+ # Enable with specific agents
287
+ kodus decisions enable --agents claude,cursor,codex
224
288
 
225
- # 2. Navigate to a file with issues
226
- # 3. Select "Copy fix prompt for AI agent"
227
- # 4. Paste into Claude Code/Cursor
228
- # 5. AI automatically fixes the issues
289
+ # Custom Codex config path
290
+ kodus decisions enable --agents codex --codex-config ~/.codex/config.toml
291
+
292
+ # Overwrite existing config
293
+ kodus decisions enable --force
294
+
295
+ # Check what's been captured on current branch
296
+ kodus decisions status
297
+
298
+ # View decisions for a PR or specific module
299
+ kodus decisions show [name]
300
+
301
+ # Promote PR-level decisions to long-term module memory
302
+ kodus decisions promote --branch feat/auth --modules auth,users
303
+
304
+ # Disable hooks (preserves all captured data in .kody/)
305
+ kodus decisions disable
229
306
  ```
230
307
 
231
- The copied prompt includes:
232
- - File path
233
- - All issues with line numbers and severity
234
- - Detailed suggestions and recommendations
235
- - AI-optimized formatting
308
+ **How it works:** Hooks fire on agent turn-complete events and persist decisions to `.kody/pr/by-sha/<head-sha>.md`. Files are committed to your repo, versioned with your code, readable by humans and agents.
236
309
 
237
- ### Automated Mode with --prompt-only
310
+ **Supported agents:** Claude Code, Cursor, Codex.
238
311
 
239
- For fully automated workflows:
312
+ ## CI/CD & Git Hooks
240
313
 
241
- Set your team key as an environment variable:
314
+ ### Pre-push Hook
242
315
 
243
316
  ```bash
244
- export KODUS_TEAM_KEY=kodus_xxxxx
317
+ kodus hook install --fail-on error # Block pushes with errors
318
+ kodus hook status # Check hook status
319
+ kodus hook uninstall # Remove hook
245
320
  ```
246
321
 
247
- Add this to your `.cursorrules` or prompt:
322
+ ### Pipeline Usage
248
323
 
249
- ```
250
- When writing code:
251
- 1. Implement the feature
252
- 2. Run: kodus review --prompt-only
253
- 3. If issues are found, fix them automatically
254
- 4. Repeat until review is clean
255
- 5. Show final result
324
+ ```bash
325
+ # Strict rules check with JSON output
326
+ kodus review --rules-only --format json --fail-on error
327
+
328
+ # Generate markdown report artifact
329
+ kodus review --format markdown --output review-report.md
256
330
  ```
257
331
 
258
- Claude Code will automatically run reviews and fix issues in a loop.
332
+ ## Authentication
259
333
 
260
- ### Using with Cursor
334
+ Kodus supports multiple auth methods depending on your setup:
261
335
 
262
- Similar workflow - the AI agent can autonomously:
263
- - Generate code
264
- - Review with `kodus review --prompt-only`
265
- - Parse the structured output
266
- - Apply fixes
267
- - Iterate until clean
336
+ ### Trial Mode (no account)
268
337
 
269
- ### Benefits
270
- - ✅ Catch issues during development, not after
271
- - ✅ Autonomous fix loops (no manual intervention)
272
- - ✅ Consistent with team standards
273
- - ✅ Faster development cycles
338
+ Just run `kodus review`. No signup needed. You get 5 reviews/day with up to 10 files and 500 lines per file — enough to try it out. [Sign up free](https://app.kodus.io) to remove limits.
274
339
 
275
- ## Trial Mode
340
+ ### Personal Login
276
341
 
277
- Without an account, you can use the CLI with rate limits:
342
+ For individual developers. Creates a session with automatic token refresh.
278
343
 
279
- - 5 reviews per day
280
- - 10 files per review
281
- - 500 lines per file
344
+ ```bash
345
+ kodus auth login # Sign in with email/password
346
+ kodus auth status # Check auth status and usage
347
+ kodus auth logout # Sign out
348
+ ```
282
349
 
283
- Sign up for free to remove these limits.
350
+ Credentials are stored locally in `~/.kodus/credentials.json`.
284
351
 
285
- ## Development
352
+ ### Team Key
286
353
 
287
- ```bash
288
- # Install dependencies
289
- npm install
354
+ For teams where not everyone needs their own account. A single shared key gives the whole team access — developers just set the key and start reviewing, no individual signup required.
290
355
 
291
- # Build
292
- npm run build
356
+ ```bash
357
+ kodus auth team-key --key kodus_xxxxx
358
+ ```
293
359
 
294
- # Run in development
295
- npm run dev
360
+ Or set it as an environment variable:
296
361
 
297
- # Test locally
298
- node dist/index.js review
362
+ ```bash
363
+ export KODUS_TEAM_KEY=kodus_xxxxx
299
364
  ```
300
365
 
301
- ## Environment Variables
366
+ Get your team key at [app.kodus.io/settings/cli](https://app.kodus.io/settings/cli). Team keys have configurable device limits managed from the dashboard.
302
367
 
303
- | Variable | Description | Security Notes |
304
- |----------|-------------|----------------|
305
- | `KODUS_API_URL` | API endpoint (default: https://api.kodus.io) | ⚠️ Only HTTPS URLs accepted (except localhost). Custom URLs validated for security. |
306
- | `KODUS_VERBOSE` | Set to `true` to enable verbose logging | ⚠️ **DO NOT use in production/CI** - may expose sensitive data in logs |
307
- | `KODUS_TOKEN` | CI/CD token for non-interactive environments | - |
308
- | `KODUS_TEAM_KEY` | Team authentication key for AI coding agents (Codex, Claude Code, Cursor) | - |
368
+ This is also the recommended auth method for AI coding agents (Claude Code, Cursor, Codex) — set the env var once and every agent session is authenticated automatically.
309
369
 
310
- ### Verbose Mode
370
+ ### CI/CD Token
311
371
 
312
- Enable detailed logging for debugging purposes:
372
+ For pipelines and automated environments. Generated from your personal login:
313
373
 
314
374
  ```bash
315
- # Enable verbose logging
316
- export KODUS_VERBOSE=true
317
- kodus review
375
+ kodus auth token # Generate a CI/CD token
376
+ ```
377
+
378
+ Then use it in your pipeline:
379
+
380
+ ```bash
381
+ export KODUS_TOKEN=<your-token>
382
+ kodus review --format json --fail-on error
318
383
  ```
319
384
 
320
- **⚠️ Security Warning:** Verbose mode may log sensitive information including:
321
- - API responses and errors
322
- - Authentication token details
323
- - Full request/response payloads
385
+ > **Note:** For PR-level reviews in CI/CD, we recommend using the [Kodus platform](https://app.kodus.io) GitHub/GitLab integration instead of the CLI. It's purpose-built for PR workflows with inline comments, status checks, and team dashboards.
386
+
387
+ <details>
388
+ <summary><strong>Environment variables</strong></summary>
389
+
390
+ | Variable | Description |
391
+ |----------|-------------|
392
+ | `KODUS_API_URL` | API endpoint (default: `https://api.kodus.io`). HTTPS only (except localhost). |
393
+ | `KODUS_TOKEN` | CI/CD token for automated pipelines (generated via `kodus auth token`) |
394
+ | `KODUS_TEAM_KEY` | Team key for shared team access and AI coding agents |
324
395
 
325
- **Never use verbose mode in:**
326
- - Production environments
327
- - CI/CD pipelines
328
- - Shared or public logs
329
- - Automated workflows
396
+ </details>
330
397
 
331
- Verbose mode is intended **only for local development and debugging**.
398
+ ## Privacy & Security
399
+
400
+ Kodus sends your code diffs to the Kodus API for analysis. We take this seriously:
401
+
402
+ - **HTTPS only** — All API communication is encrypted. Custom API URLs are validated.
403
+ - **No training on your code** — Your code is not used to train models.
404
+ - **Minimal data** — Only diffs and context files are sent, not your entire codebase.
405
+ - **Credentials stored locally** — Auth tokens are kept in `~/.kodus/credentials.json` on your machine.
406
+
407
+ ## Contributing
408
+
409
+ We welcome contributions! Please see our [issues page](https://github.com/kodustech/cli/issues) to get started.
410
+
411
+ ```bash
412
+ npm install # Install dependencies
413
+ npm run build # Build
414
+ npm run dev # Watch mode
415
+ npm test # Run tests
416
+ ```
332
417
 
333
418
  ## License
334
419
 
335
- MIT
420
+ [MIT](LICENSE)
package/dist/cli.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAsB9B,OAAO,EAAE,OAAO,EAAE,CAAC"}
1
+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC,QAAA,MAAM,OAAO,SAAgB,CAAC;AAuB9B,OAAO,EAAE,OAAO,EAAE,CAAC"}
package/dist/cli.js CHANGED
@@ -5,6 +5,7 @@ import { authCommand } from './commands/auth/index.js';
5
5
  import { upgradeCommand } from './commands/upgrade.js';
6
6
  import { prCommand } from './commands/pr.js';
7
7
  import { hookCommand } from './commands/hook/index.js';
8
+ import { decisionsCommand } from './commands/memory/index.js';
8
9
  import { checkForUpdates } from './utils/update-check.js';
9
10
  const require = createRequire(import.meta.url);
10
11
  const pkg = require('../package.json');
@@ -22,6 +23,7 @@ program.addCommand(authCommand);
22
23
  program.addCommand(upgradeCommand);
23
24
  program.addCommand(prCommand);
24
25
  program.addCommand(hookCommand);
26
+ program.addCommand(decisionsCommand);
25
27
  program.hook('postAction', async () => {
26
28
  await checkForUpdates(pkg.version);
27
29
  });
package/dist/cli.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAE9D,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,OAAO,CAAC;KACb,WAAW,CAAC,uDAAuD,CAAC;KACpE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;KACpB,MAAM,CAAC,uBAAuB,EAAE,yCAAyC,EAAE,UAAU,CAAC;KACtF,MAAM,CAAC,qBAAqB,EAAE,iCAAiC,CAAC;KAChE,MAAM,CAAC,eAAe,EAAE,gBAAgB,EAAE,KAAK,CAAC;KAChD,MAAM,CAAC,aAAa,EAAE,0BAA0B,EAAE,KAAK,CAAC,CACxD;AAEH,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AAC9B,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAEhC,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,IAAI,EAAE;IACpC,MAAM,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC,CAAC,CAAC;AAEH,OAAO,EAAE,OAAO,EAAE,CAAC"}
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAE9D,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,OAAO,CAAC;KACb,WAAW,CAAC,uDAAuD,CAAC;KACpE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;KACpB,MAAM,CAAC,uBAAuB,EAAE,yCAAyC,EAAE,UAAU,CAAC;KACtF,MAAM,CAAC,qBAAqB,EAAE,iCAAiC,CAAC;KAChE,MAAM,CAAC,eAAe,EAAE,gBAAgB,EAAE,KAAK,CAAC;KAChD,MAAM,CAAC,aAAa,EAAE,0BAA0B,EAAE,KAAK,CAAC,CACxD;AAEH,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;AAC9B,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,CAAC;AAErC,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,IAAI,EAAE;IACpC,MAAM,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC,CAAC,CAAC;AAEH,OAAO,EAAE,OAAO,EAAE,CAAC"}