@kody-ade/kody-engine-lite 0.1.73 → 0.1.75
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.
- package/README.md +87 -123
- package/dist/bin/cli.js +5 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -3,102 +3,53 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/@kody-ade/kody-engine-lite)
|
|
4
4
|
[](LICENSE)
|
|
5
5
|
|
|
6
|
-
**
|
|
6
|
+
**Comment `@kody` on a GitHub issue. Get back a tested, reviewed PR. Free and open source.**
|
|
7
7
|
|
|
8
|
-
Kody
|
|
8
|
+
Kody wraps Claude Code with a 7-stage autonomous pipeline — classify, plan, build, verify, review, fix, ship — with quality gates between every stage. If verify catches a bug, it gets fixed before review ever sees it. No blind retries, no context drift, no babysitting.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
- **Repo-aware prompts** — `bootstrap` analyzes your codebase and generates customized instructions for every stage, not generic "write clean code" prompts
|
|
11
|
+
- **Quality gates** — runs your repo's typecheck, tests, and lint between stages + AI code review in a fresh session
|
|
12
|
+
- **AI failure diagnosis** — classifies errors as fixable/infrastructure/pre-existing before retrying
|
|
13
|
+
- **Self-improving** — learns conventions, remembers architectural decisions, discovers existing patterns
|
|
14
|
+
- **Runs anywhere** — locally from your terminal or via GitHub Actions
|
|
15
|
+
- **Anthropic-compatible models** — Anthropic natively, or other providers (MiniMax, Gemini, etc.) via LiteLLM proxy
|
|
11
16
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
Most AI coding tools are **autocomplete** (Copilot) or **chat-based** (Cursor, Cline). You still drive. Kody is an **autonomous pipeline** — comment `@kody`, walk away, come back to a PR.
|
|
15
|
-
|
|
16
|
-
- **Repo-aware prompts** — auto-generated step files with your repo's patterns, gaps, and acceptance criteria
|
|
17
|
-
- **7 stages with quality gates** — not a single agent conversation
|
|
18
|
-
- **Fire and forget** — runs in GitHub Actions, no IDE required
|
|
19
|
-
- **Any LLM** — route through LiteLLM to use MiniMax, GPT, Gemini, or local models
|
|
20
|
-
- **Free** with free-tier models — no subscriptions, no per-seat pricing
|
|
21
|
-
|
|
22
|
-
[How Kody compares to Copilot, Devin, Cursor, OpenHands, and others →](docs/COMPARISON.md)
|
|
23
|
-
|
|
24
|
-
## Pipeline
|
|
17
|
+
[Why Kody? →](docs/ABOUT.md) · [Full comparison →](docs/COMPARISON.md)
|
|
25
18
|
|
|
26
19
|
```
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
│ 🛑 Pause for approval │──── @kody approve
|
|
50
|
-
└────────────┬────────────┘
|
|
51
|
-
│
|
|
52
|
-
┌──────────────────────────▼──────────────────────────────────┐
|
|
53
|
-
│ ③ BUILD Tier: mid │
|
|
54
|
-
│ Implement code via Claude Code tools → code + git commit│
|
|
55
|
-
└──────────────────────────┬──────────────────────────────────┘
|
|
56
|
-
│
|
|
57
|
-
┌──────────────────────────▼──────────────────────────────────┐
|
|
58
|
-
│ ④ VERIFY (deterministic gate) │
|
|
59
|
-
│ typecheck + tests + lint │
|
|
60
|
-
│ ┌───────────────────────────────────────────────────┐ │
|
|
61
|
-
│ │ Fail? → AI diagnosis → autofix → retry (up to 2) │ │
|
|
62
|
-
│ └───────────────────────────────────────────────────┘ │
|
|
63
|
-
└──────────────────────────┬──────────────────────────────────┘
|
|
64
|
-
│
|
|
65
|
-
┌──────────────────────────▼──────────────────────────────────┐
|
|
66
|
-
│ ⑤ REVIEW Tier: strong │
|
|
67
|
-
│ Code review: PASS/FAIL + Critical/Major/Minor → review.md │
|
|
68
|
-
└──────────────────────────┬──────────────────────────────────┘
|
|
69
|
-
│
|
|
70
|
-
┌──────────────────────────▼──────────────────────────────────┐
|
|
71
|
-
│ ⑥ REVIEW-FIX Tier: mid │
|
|
72
|
-
│ Fix Critical and Major findings → code + commit│
|
|
73
|
-
└──────────────────────────┬──────────────────────────────────┘
|
|
74
|
-
│
|
|
75
|
-
┌──────────────────────────▼──────────────────────────────────┐
|
|
76
|
-
│ ⑦ SHIP (deterministic) │
|
|
77
|
-
│ Push branch + create PR with Closes #N → ship.md + PR│
|
|
78
|
-
└──────────────────────────┬──────────────────────────────────┘
|
|
79
|
-
│
|
|
80
|
-
┌──────────────────────────▼──────────────────────────────────┐
|
|
81
|
-
│ ✅ PR created & ready for review │
|
|
82
|
-
└─────────────────────────────────────────────────────────────┘
|
|
20
|
+
@kody on issue
|
|
21
|
+
│
|
|
22
|
+
▼
|
|
23
|
+
① TASKIFY ─── classify, scope, detect complexity, ask questions
|
|
24
|
+
│
|
|
25
|
+
▼
|
|
26
|
+
② PLAN ────── TDD implementation plan (deep reasoning)
|
|
27
|
+
│ 🛑 HIGH risk? Pause for human approval
|
|
28
|
+
▼
|
|
29
|
+
③ BUILD ───── implement via Claude Code tools
|
|
30
|
+
│
|
|
31
|
+
▼
|
|
32
|
+
④ VERIFY ──── typecheck + tests + lint
|
|
33
|
+
│ ✗ fail → AI diagnosis → autofix → retry
|
|
34
|
+
▼
|
|
35
|
+
⑤ REVIEW ──── AI code review (fresh session, no build bias)
|
|
36
|
+
│
|
|
37
|
+
▼
|
|
38
|
+
⑥ REVIEW-FIX ─ fix Critical and Major findings
|
|
39
|
+
│
|
|
40
|
+
▼
|
|
41
|
+
⑦ SHIP ────── push branch, create PR, close issue
|
|
83
42
|
```
|
|
84
43
|
|
|
85
|
-
**Tiers are configurable** — cheap/mid/strong map to any model via `modelMap` in config. Defaults: haiku/sonnet/opus. Route to MiniMax, GPT, Gemini, or local models via [LiteLLM](docs/LITELLM.md).
|
|
86
|
-
|
|
87
|
-
**Shared sessions** — stages in the same group share a Claude Code session: taskify+plan (explore), build+autofix+review-fix (implementation), review (fresh perspective). No cold-start re-exploration between stages.
|
|
88
|
-
|
|
89
|
-
[Pipeline details →](docs/PIPELINE.md)
|
|
90
|
-
|
|
91
44
|
## Quick Start
|
|
92
45
|
|
|
93
|
-
**Prerequisites:**
|
|
46
|
+
**Prerequisites:** A GitHub repo + an Anthropic API key (or [compatible provider](docs/LITELLM.md) key).
|
|
94
47
|
|
|
95
|
-
|
|
48
|
+
For local CLI usage, you also need: Node.js >= 22, [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code), [GitHub CLI](https://cli.github.com/), git.
|
|
96
49
|
|
|
97
|
-
|
|
98
|
-
npm install -g @kody-ade/kody-engine-lite
|
|
99
|
-
```
|
|
50
|
+
### 1. Set up GitHub
|
|
100
51
|
|
|
101
|
-
|
|
52
|
+
Add your API key as a secret — via [GitHub web UI](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) or CLI:
|
|
102
53
|
|
|
103
54
|
```bash
|
|
104
55
|
gh secret set ANTHROPIC_API_KEY --repo owner/repo
|
|
@@ -106,21 +57,28 @@ gh secret set ANTHROPIC_API_KEY --repo owner/repo
|
|
|
106
57
|
|
|
107
58
|
Then in GitHub: **Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests"**
|
|
108
59
|
|
|
109
|
-
###
|
|
60
|
+
### 2. Initialize
|
|
61
|
+
|
|
62
|
+
Copy the [workflow template](templates/kody.yml) to `.github/workflows/kody.yml` and add a `kody.config.json` to your repo root. Or use the CLI to auto-generate both:
|
|
110
63
|
|
|
111
64
|
```bash
|
|
65
|
+
npm install -g @kody-ade/kody-engine-lite
|
|
112
66
|
cd your-project
|
|
113
67
|
kody-engine-lite init
|
|
114
68
|
```
|
|
115
69
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
70
|
+
### 3. Bootstrap
|
|
71
|
+
|
|
72
|
+
Create a new GitHub issue (e.g., "Setup Kody") and comment:
|
|
73
|
+
|
|
74
|
+
```
|
|
75
|
+
@kody bootstrap
|
|
76
|
+
```
|
|
122
77
|
|
|
123
|
-
|
|
78
|
+
This analyzes your codebase with an LLM and generates:
|
|
79
|
+
- **Project memory** (`.kody/memory/` — architecture and conventions)
|
|
80
|
+
- **Customized step files** (`.kody/steps/` — repo-aware prompts for every stage)
|
|
81
|
+
- **GitHub labels** for lifecycle tracking (14 labels)
|
|
124
82
|
|
|
125
83
|
### 4. Use
|
|
126
84
|
|
|
@@ -130,36 +88,46 @@ Comment on any GitHub issue:
|
|
|
130
88
|
@kody
|
|
131
89
|
```
|
|
132
90
|
|
|
133
|
-
|
|
91
|
+
Kody picks up the issue and works through the pipeline autonomously. You'll see:
|
|
92
|
+
- Labels updating in real-time: `kody:planning` → `kody:building` → `kody:review` → `kody:done`
|
|
93
|
+
- Progress comments on the issue at each stage
|
|
94
|
+
- A PR with a rich description, passing quality checks, and `Closes #N`
|
|
95
|
+
|
|
96
|
+
If the task is HIGH-risk, Kody pauses after planning and asks for approval before writing code.
|
|
134
97
|
|
|
135
|
-
|
|
98
|
+
### Switch to a different model (optional)
|
|
136
99
|
|
|
137
100
|
```json
|
|
138
|
-
// kody.config.json
|
|
101
|
+
// kody.config.json
|
|
139
102
|
{ "agent": { "provider": "minimax" } }
|
|
140
103
|
```
|
|
141
104
|
|
|
142
|
-
Add the provider's API key to `.env`:
|
|
143
105
|
```
|
|
106
|
+
# .env
|
|
144
107
|
ANTHROPIC_COMPATIBLE_API_KEY=your-key-here
|
|
145
108
|
```
|
|
146
109
|
|
|
147
|
-
|
|
110
|
+
Kody auto-starts the LiteLLM proxy. [Full LiteLLM guide →](docs/LITELLM.md)
|
|
148
111
|
|
|
149
112
|
## Commands
|
|
150
113
|
|
|
151
114
|
| Command | What it does |
|
|
152
115
|
|---------|-------------|
|
|
153
116
|
| `@kody` | Run full pipeline on an issue |
|
|
117
|
+
| `@kody review` | Review any PR — structured findings + GitHub approve/request-changes |
|
|
118
|
+
| `@kody fix` | Re-run from build with human PR feedback + Kody's review as context |
|
|
119
|
+
| `@kody fix-ci` | Fix failing CI checks (auto-triggered with loop guard) |
|
|
120
|
+
| `@kody rerun` | Resume from failed or paused stage |
|
|
121
|
+
| `@kody rerun --from <stage>` | Resume from a specific stage |
|
|
154
122
|
| `@kody approve` | Resume after questions or risk gate |
|
|
155
|
-
| `@kody fix` | Re-run from build. Reads PR review comments as context |
|
|
156
|
-
| `@kody fix-ci` | Fix failing CI checks (auto-triggered on Kody PRs) |
|
|
157
|
-
| `@kody rerun` | Resume from the failed or paused stage |
|
|
158
123
|
| `@kody bootstrap` | Regenerate project memory and step files |
|
|
159
124
|
|
|
160
125
|
```bash
|
|
161
|
-
kody-engine-lite init [--force]
|
|
162
|
-
kody-engine-lite
|
|
126
|
+
kody-engine-lite init [--force] # Setup repo: workflow + config
|
|
127
|
+
kody-engine-lite bootstrap [--force] # Generate memory + step files + labels
|
|
128
|
+
kody-engine-lite run --issue-number 42 --local --cwd ./project
|
|
129
|
+
kody-engine-lite run --task "Add retry utility" --local
|
|
130
|
+
kody-engine-lite review --pr-number 42 # Standalone PR review
|
|
163
131
|
kody-engine-lite fix --issue-number 42 --feedback "Use middleware pattern"
|
|
164
132
|
kody-engine-lite fix-ci --pr-number 42
|
|
165
133
|
kody-engine-lite rerun --issue-number 42 --from verify
|
|
@@ -169,30 +137,26 @@ kody-engine-lite rerun --issue-number 42 --from verify
|
|
|
169
137
|
|
|
170
138
|
## Key Features
|
|
171
139
|
|
|
172
|
-
- **
|
|
173
|
-
- **
|
|
174
|
-
- **
|
|
175
|
-
- **
|
|
176
|
-
- **[
|
|
177
|
-
- **
|
|
178
|
-
- **
|
|
179
|
-
- **[
|
|
180
|
-
- **
|
|
181
|
-
- **[
|
|
140
|
+
- **Repo-Aware Step Files** — auto-generated prompts with your repo's patterns, gaps, and acceptance criteria ([details](docs/FEATURES.md#repo-aware-step-files-kodysteps))
|
|
141
|
+
- **Standalone PR Review** — `@kody review` on any PR for structured code review with GitHub approve/request-changes ([details](docs/FEATURES.md#standalone-pr-review))
|
|
142
|
+
- **Shared Sessions** — stages share Claude Code sessions, no cold-start re-exploration ([details](docs/FEATURES.md#shared-sessions))
|
|
143
|
+
- **Risk Gate** — HIGH-risk tasks pause for human approval before building ([details](docs/FEATURES.md#risk-gate))
|
|
144
|
+
- **AI Failure Diagnosis** — classifies errors as fixable/infrastructure/pre-existing/abort before retry ([details](docs/FEATURES.md#ai-powered-failure-diagnosis))
|
|
145
|
+
- **Question Gates** — asks product/architecture questions when the task is unclear ([details](docs/FEATURES.md#question-gates))
|
|
146
|
+
- **Auto Fix-CI** — CI fails on a PR? Kody fetches logs, diagnoses, and pushes a fix ([details](docs/FEATURES.md#auto-fix-ci))
|
|
147
|
+
- **Pattern Discovery** — searches for existing patterns before proposing new ones ([details](docs/FEATURES.md#pattern-discovery))
|
|
148
|
+
- **Decision Memory** — architectural decisions extracted from reviews persist across tasks ([details](docs/FEATURES.md#decision-memory))
|
|
149
|
+
- **Auto-Learning** — extracts coding conventions from each successful run ([details](docs/FEATURES.md#auto-learning-memory))
|
|
150
|
+
- **Retrospective** — analyzes each run, identifies patterns, suggests improvements ([details](docs/FEATURES.md#retrospective-system))
|
|
151
|
+
- **Anthropic-Compatible Models** — route through LiteLLM to use other providers like MiniMax, Gemini, etc. ([setup guide](docs/LITELLM.md))
|
|
182
152
|
|
|
183
153
|
## Documentation
|
|
184
154
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
| [LiteLLM](docs/LITELLM.md) | Non-Anthropic model setup, auto-start, tested providers |
|
|
191
|
-
| [CLI](docs/CLI.md) | Full command reference — all flags, env vars, and examples |
|
|
192
|
-
| [Configuration](docs/CONFIGURATION.md) | Config file reference, env vars, workflow setup |
|
|
193
|
-
| [Comparison](docs/COMPARISON.md) | vs Copilot, Devin, Cursor, Cline, OpenHands, SWE-agent |
|
|
194
|
-
| [Architecture](docs/ARCHITECTURE.md) | Source tree, state machine diagram, development guide |
|
|
195
|
-
| [FAQ](docs/FAQ.md) | Common questions about usage, models, security, cost |
|
|
155
|
+
**Understand Kody:** [About](docs/ABOUT.md) · [Features](docs/FEATURES.md) · [Pipeline](docs/PIPELINE.md) · [Comparison](docs/COMPARISON.md)
|
|
156
|
+
|
|
157
|
+
**Set up & use:** [CLI](docs/CLI.md) · [Configuration](docs/CONFIGURATION.md) · [Bootstrap](docs/BOOTSTRAP.md) · [LiteLLM](docs/LITELLM.md)
|
|
158
|
+
|
|
159
|
+
**Reference:** [Architecture](docs/ARCHITECTURE.md) · [FAQ](docs/FAQ.md)
|
|
196
160
|
|
|
197
161
|
## License
|
|
198
162
|
|
package/dist/bin/cli.js
CHANGED
|
@@ -3421,8 +3421,10 @@ async function checkModelHealth(baseUrl, apiKey, model = "claude-haiku-4-5") {
|
|
|
3421
3421
|
return { ok: false, error: `HTTP ${res.status}: ${body2.slice(0, 200)}` };
|
|
3422
3422
|
}
|
|
3423
3423
|
const body = await res.json();
|
|
3424
|
-
|
|
3425
|
-
|
|
3424
|
+
const hasAnthropicContent = !!body.content?.[0]?.text;
|
|
3425
|
+
const hasOpenAIContent = !!body.choices?.[0]?.message?.content;
|
|
3426
|
+
if (!hasAnthropicContent && !hasOpenAIContent) {
|
|
3427
|
+
return { ok: false, error: `Unexpected response format: ${JSON.stringify(body).slice(0, 200)}` };
|
|
3426
3428
|
}
|
|
3427
3429
|
return { ok: true };
|
|
3428
3430
|
} catch (err) {
|
|
@@ -3633,7 +3635,7 @@ async function runModelHealthCheck(config) {
|
|
|
3633
3635
|
logger.warn(`Skipping model health check \u2014 ${keyName} not set`);
|
|
3634
3636
|
return;
|
|
3635
3637
|
}
|
|
3636
|
-
const model = config.agent.modelMap.cheap;
|
|
3638
|
+
const model = usesProxy ? "claude-haiku-4-5" : config.agent.modelMap.cheap;
|
|
3637
3639
|
logger.info(`Model health check (${model} via ${usesProxy ? "LiteLLM" : "Anthropic"})...`);
|
|
3638
3640
|
const result = await checkModelHealth(baseUrl, apiKey, model);
|
|
3639
3641
|
if (result.ok) {
|