codecall 1.5.0 → 1.5.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.
package/README.md
CHANGED
|
@@ -1,44 +1,68 @@
|
|
|
1
1
|
# codecall
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Understand the code your AI agent writes.**
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/codecall)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
|
|
8
|
+
codecall is a skill for AI coding agents. After your agent builds something,
|
|
9
|
+
it teaches you the ideas behind the change using your own code, checks that
|
|
10
|
+
you can explain them, and gives you a one-page receipt. It can also walk you
|
|
11
|
+
through a request flow, or plant a bug for you to find.
|
|
12
|
+
|
|
13
|
+
Works in Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Kiro and Copilot.
|
|
14
|
+
No API key, no account, nothing uploaded.
|
|
4
15
|
|
|
5
16
|
|
|
6
17
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
18
|
+
## Features
|
|
19
|
+
|
|
20
|
+
| Mode | Command | What you get |
|
|
21
|
+
| --- | --- | --- |
|
|
22
|
+
| **Learn** | `/codecall` | A 4-minute session on the 2 to 4 ideas behind the change your agent just made, two checks per idea, and a receipt with your score. |
|
|
23
|
+
| **Trace** | `/codecall trace POST /login` | One request followed from entry point to response, `file:line` by `file:line`, then a check on the steps most likely to hide a bug. |
|
|
24
|
+
| **Drill** | `/codecall drill src/orders medium` | A debugging round on your own project: one planted bug, only the symptom, hints on request, and your code restored with Git afterwards. |
|
|
25
|
+
| **Backend concept map** | automatic | About 80 backend concepts that keep server-side lessons consistent and point you to a free video chapter and official docs for anything you missed. |
|
|
26
|
+
|
|
27
|
+
You are always asked **Start Learning / Skip** before a session begins, and
|
|
28
|
+
nothing is taught without your yes.
|
|
12
29
|
|
|
13
30
|
## Install
|
|
14
31
|
|
|
15
|
-
|
|
16
|
-
npx skills add GAURAV-1313/codecall
|
|
17
|
-
```
|
|
32
|
+
Pick one:
|
|
18
33
|
|
|
19
|
-
|
|
20
|
-
|
|
34
|
+
| Method | Command | Best for |
|
|
35
|
+
| --- | --- | --- |
|
|
36
|
+
| Skills CLI | `npx skills add GAURAV-1313/codecall` | Any supported agent |
|
|
37
|
+
| npm | `npm install -g codecall` | Claude Code and Codex together |
|
|
38
|
+
| Claude Code plugin | `/plugin marketplace add https://github.com/GAURAV-1313/codecall`<br>`/plugin install codecall@codecall` | Getting offered a session automatically after meaningful changes |
|
|
21
39
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
40
|
+
The plugin is the only option that offers sessions by itself. It adds a small
|
|
41
|
+
local hook that reminds your agent to check whether a change is worth
|
|
42
|
+
learning from; it never starts a session without your yes.
|
|
25
43
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
```
|
|
44
|
+
For Codex, add the plugin with
|
|
45
|
+
`codex plugin marketplace add https://github.com/GAURAV-1313/codecall`, then
|
|
46
|
+
`codex plugin add codecall@codecall`.
|
|
30
47
|
|
|
31
|
-
|
|
32
|
-
then `codex plugin add codecall@codecall`. The plugin's command is
|
|
33
|
-
`/codecall:codecall` in Claude Code.) `npm install -g codecall` also works and
|
|
34
|
-
installs the skill for both Codex and Claude Code.
|
|
48
|
+
Restart your agent after installing.
|
|
35
49
|
|
|
36
|
-
|
|
50
|
+
### Which command to type
|
|
37
51
|
|
|
38
|
-
|
|
52
|
+
| Installed via | Command |
|
|
53
|
+
| --- | --- |
|
|
54
|
+
| Skills CLI or npm | `/codecall` |
|
|
55
|
+
| Claude Code plugin | `/codecall:codecall` |
|
|
56
|
+
| Codex | `$codecall` |
|
|
57
|
+
|
|
58
|
+
Add `trace <flow>` or `drill [area] [easy|medium|hard]` after any of them.
|
|
59
|
+
|
|
60
|
+
## Learn: quiz on what was just built
|
|
61
|
+
|
|
62
|
+
Say your agent just added login to your app:
|
|
39
63
|
|
|
40
64
|
```text
|
|
41
|
-
You:
|
|
65
|
+
You: /codecall
|
|
42
66
|
|
|
43
67
|
codecall: Implementation completed.
|
|
44
68
|
Learning opportunity: this adds authentication middleware and a
|
|
@@ -47,127 +71,130 @@ codecall: Implementation completed.
|
|
|
47
71
|
|
|
48
72
|
Start Learning / Skip
|
|
49
73
|
|
|
50
|
-
You:
|
|
74
|
+
You: Start Learning
|
|
51
75
|
|
|
52
76
|
codecall: How confident are you with authentication middleware?
|
|
53
77
|
[ Expert / Comfortable / Heard of it / Never learned ]
|
|
54
78
|
|
|
55
|
-
You:
|
|
79
|
+
You: Heard of it
|
|
56
80
|
|
|
57
81
|
codecall: Let's start with why every request now passes through a check
|
|
58
82
|
before reaching your account routes...
|
|
59
|
-
(explains the idea
|
|
83
|
+
(explains the idea using YOUR code)
|
|
60
84
|
|
|
61
85
|
Quick check: if someone sends a request without logging in,
|
|
62
86
|
what should happen?
|
|
63
87
|
|
|
64
|
-
You: (answer)
|
|
65
|
-
|
|
66
|
-
codecall: (tells you if you're right, and why, then moves to the next idea)
|
|
67
|
-
|
|
68
88
|
...
|
|
69
89
|
|
|
70
90
|
codecall: Receipt: ./codecall/0007-auth-middleware.html
|
|
71
|
-
Could explain 3 of 4.
|
|
91
|
+
Could explain 3 of 4.
|
|
72
92
|
```
|
|
73
93
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
94
|
+
It adapts to your answers. Get one right and the next check is harder. Get one
|
|
95
|
+
wrong and it names the gap, explains it again from your code, and asks a fresh
|
|
96
|
+
question. It works for any change with a *why* behind it: retry logic, a
|
|
97
|
+
database index, a cache layer, a webhook handler.
|
|
77
98
|
|
|
78
|
-
|
|
79
|
-
cache layer, a webhook handler: anything with a *why* behind it gets the same
|
|
80
|
-
short format, grounded in what was actually built.
|
|
99
|
+
## Trace: follow one flow
|
|
81
100
|
|
|
82
|
-
|
|
101
|
+
```text
|
|
102
|
+
/codecall trace POST /login
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
codecall walks the request from where it enters your code to where it ends,
|
|
106
|
+
one `file:line` at a time, then shows the whole path as a single chain. It
|
|
107
|
+
finishes by checking you on the 2 or 3 steps where a bug would most likely
|
|
108
|
+
hide. It never edits code.
|
|
83
109
|
|
|
84
|
-
|
|
110
|
+
## Drill: debugging practice
|
|
85
111
|
|
|
86
112
|
```text
|
|
87
113
|
/codecall drill src/orders medium
|
|
88
114
|
```
|
|
89
115
|
|
|
90
|
-
|
|
91
|
-
unhandled empty case, a wrong status code), tells you only the symptom and how
|
|
92
|
-
to reproduce it, and stays out of your way while you debug. Ask for a hint
|
|
93
|
-
when you're stuck: where to look, then what to log, then the function, then
|
|
94
|
-
the line. When you find it or give up, it shows the planted change, explains
|
|
95
|
-
the fastest route to it, and restores the file with Git.
|
|
116
|
+
Built for debugging interview rounds, run on your own project:
|
|
96
117
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
118
|
+
1. codecall plants **one** realistic bug: an off-by-one, a missing `await`, an
|
|
119
|
+
unhandled empty case, a wrong status code.
|
|
120
|
+
2. You get only the symptom and how to reproduce it.
|
|
121
|
+
3. Ask for a hint when stuck. Hints narrow step by step: where to look, what
|
|
122
|
+
to log, which function, which line.
|
|
123
|
+
4. When you find it or give up, codecall shows the planted change, explains
|
|
124
|
+
the fastest route to it, and restores your file with Git.
|
|
100
125
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
126
|
+
| Difficulty | What the bug looks like |
|
|
127
|
+
| --- | --- |
|
|
128
|
+
| `easy` | It crashes near the bug. |
|
|
129
|
+
| `medium` | Wrong output, one layer away from the cause. |
|
|
130
|
+
| `hard` | Only some inputs fail, or it fails silently. |
|
|
104
131
|
|
|
105
|
-
|
|
132
|
+
Drills need Git and a clean working tree. They only start when you ask; the
|
|
133
|
+
automatic offer never proposes one. If your editor asks you to approve the
|
|
134
|
+
planted edit, approve it without reading it.
|
|
106
135
|
|
|
107
|
-
|
|
108
|
-
end, `file:line` by `file:line`, ends with the whole path as one chain, then
|
|
109
|
-
checks you on the 2 or 3 hops where a bug would most likely hide. It never
|
|
110
|
-
edits code, and it writes the usual receipt.
|
|
136
|
+
## Backend concept map
|
|
111
137
|
|
|
112
|
-
|
|
138
|
+
For server-side changes, codecall uses a built-in map of about 80 backend
|
|
139
|
+
concepts across HTTP, auth, databases, caching, queues, webhooks, real-time,
|
|
140
|
+
storage, testing and delivery. It keeps concept names consistent between
|
|
141
|
+
sessions, teaches prerequisites first, and draws on known misconceptions. You
|
|
142
|
+
never see the map, and changes outside its scope work exactly as before.
|
|
113
143
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
144
|
+
When you miss a mapped concept, your receipt adds one **Go deeper** line: the
|
|
145
|
+
matching chapter of Sriniously's free
|
|
146
|
+
[Backend from first principles](https://www.youtube.com/playlist?list=PLui3EUkuMTPgZcV0QhQrOcwMPcBCcd_Q1)
|
|
147
|
+
series, plus an official reference such as MDN, OWASP or the PostgreSQL docs.
|
|
148
|
+
A concept you missed before is more likely to come back in a later session.
|
|
118
149
|
|
|
119
|
-
|
|
150
|
+
The map's wording is codecall's own; it links to the videos and does not copy
|
|
151
|
+
them. codecall is not affiliated with or endorsed by the series' creator.
|
|
120
152
|
|
|
121
|
-
|
|
122
|
-
answer both of its checks correctly without a reteach. The score is `N of M`
|
|
123
|
-
ideas, nothing else: no time-on-task, no mastery claim, no guess at what you
|
|
124
|
-
would have known anyway. Earlier receipts in `./codecall/` add a streak line
|
|
125
|
-
(sessions this week, running explain rate, drills found) and nothing more.
|
|
153
|
+
## Receipts and scoring
|
|
126
154
|
|
|
127
|
-
|
|
155
|
+
Every session ends with a self-contained HTML file in `./codecall/` in your
|
|
156
|
+
project. A Learn receipt shows:
|
|
128
157
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
158
|
+
- the change in one line, and the date
|
|
159
|
+
- each idea marked ✅ could explain or ❌ could not
|
|
160
|
+
- your score, `Could explain N of M`
|
|
161
|
+
- three points to remember and the edge cases to check before reusing the
|
|
162
|
+
pattern
|
|
134
163
|
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
map's wording is codecall's own and links to the videos; it does not copy
|
|
140
|
-
them. codecall is not affiliated with or endorsed by the series' creator.
|
|
164
|
+
An idea counts as *could explain* only when you answer both of its checks
|
|
165
|
+
correctly without a reteach. There is no time-on-task score and no claim of
|
|
166
|
+
mastery. Earlier receipts add a streak line: sessions this week, your running
|
|
167
|
+
explain rate and drills found.
|
|
141
168
|
|
|
142
169
|
## Privacy
|
|
143
170
|
|
|
144
|
-
- No API key,
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
-
|
|
153
|
-
|
|
154
|
-
- On the Claude Code plugin, the read-only planning step runs in an isolated
|
|
155
|
-
helper so it does not fill your main conversation. It can only read files
|
|
156
|
-
and never talks to you.
|
|
171
|
+
- No API key, account, signup or network call. codecall runs inside the agent
|
|
172
|
+
and conversation you already have open.
|
|
173
|
+
- Receipts are the only files it writes, in `./codecall/`. Delete the folder
|
|
174
|
+
to forget every session.
|
|
175
|
+
- A drill is the one exception: it changes one file for the length of the
|
|
176
|
+
drill, then restores it with Git. It never commits, stashes or branches.
|
|
177
|
+
- The plugin's hook runs locally and only adds a text reminder; it cannot edit
|
|
178
|
+
files or run commands.
|
|
179
|
+
- On the Claude Code plugin, planning runs in a read-only helper so it does
|
|
180
|
+
not crowd your main conversation.
|
|
157
181
|
|
|
158
182
|
## Troubleshooting
|
|
159
183
|
|
|
160
|
-
**Nothing happens after installing.** Restart
|
|
161
|
-
session;
|
|
184
|
+
**Nothing happens after installing.** Restart your agent or start a new
|
|
185
|
+
session; open sessions do not pick up new installs.
|
|
162
186
|
|
|
163
|
-
**
|
|
164
|
-
|
|
187
|
+
**The command isn't found.** Check [which command to type](#which-command-to-type)
|
|
188
|
+
for how you installed it.
|
|
165
189
|
|
|
166
190
|
**The plugin asked me to trust something.** That is the one-time review for
|
|
167
|
-
the
|
|
168
|
-
works; you type the command yourself.
|
|
191
|
+
the local hook behind the automatic offer. Decline it and codecall still
|
|
192
|
+
works; you just type the command yourself.
|
|
169
193
|
|
|
170
|
-
|
|
194
|
+
**A drill won't start.** Commit or stash your changes first. Drills need a
|
|
195
|
+
clean Git working tree so they can restore your code exactly.
|
|
196
|
+
|
|
197
|
+
## Contributing
|
|
171
198
|
|
|
172
199
|
```bash
|
|
173
200
|
npm install
|
|
@@ -176,20 +203,17 @@ npm test
|
|
|
176
203
|
claude plugin validate ./plugins/codecall
|
|
177
204
|
```
|
|
178
205
|
|
|
206
|
+
The skill lives in `plugins/codecall/skills/codecall/`. The TypeScript in
|
|
207
|
+
`src/` is an offline test harness for the session state machine, not the
|
|
208
|
+
product; see [ARCHITECTURE.md](ARCHITECTURE.md).
|
|
209
|
+
|
|
179
210
|
The backend concept map lives in
|
|
180
211
|
`plugins/codecall/skills/codecall/references/backend-map/`, one Markdown file
|
|
181
|
-
per
|
|
182
|
-
|
|
183
|
-
|
|
212
|
+
per topic. After editing, run `node scripts/backend-map.mjs` to validate it
|
|
213
|
+
and regenerate `index.md`. `npm test` fails on a stale index, a broken
|
|
214
|
+
prerequisite, a video timestamp that isn't a real chapter start, or a link
|
|
184
215
|
outside the documentation allowlist.
|
|
185
216
|
|
|
186
|
-
The canonical skill lives in `plugins/codecall/skills/codecall/`. The
|
|
187
|
-
TypeScript runtime in `src/` is an offline, deterministic test harness for the
|
|
188
|
-
session state machine, not the product; see [ARCHITECTURE.md](ARCHITECTURE.md).
|
|
189
|
-
|
|
190
|
-
Listings: Claude Code's [plugin directory submission form](https://clau.de/plugin-directory-submission);
|
|
191
|
-
Codex via `platform.openai.com/plugins`.
|
|
192
|
-
|
|
193
217
|
## License
|
|
194
218
|
|
|
195
219
|
[MIT](LICENSE)
|
package/package.json
CHANGED
|
@@ -1,15 +1,23 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "codecall",
|
|
3
|
-
"version": "1.5.
|
|
3
|
+
"version": "1.5.1",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"type": "module",
|
|
6
|
-
"description": "
|
|
6
|
+
"description": "Understand the code your AI agent writes: a 4-minute quiz on each change, step-by-step flow traces, and planted-bug debugging drills. Claude Code, Codex, Cursor and more. No API key.",
|
|
7
7
|
"keywords": [
|
|
8
|
-
"codex",
|
|
9
8
|
"claude-code",
|
|
10
|
-
"
|
|
9
|
+
"codex",
|
|
10
|
+
"cursor",
|
|
11
|
+
"gemini-cli",
|
|
12
|
+
"agent-skills",
|
|
13
|
+
"ai-coding",
|
|
14
|
+
"code-comprehension",
|
|
11
15
|
"learning",
|
|
12
|
-
"
|
|
16
|
+
"quiz",
|
|
17
|
+
"debugging",
|
|
18
|
+
"interview-prep",
|
|
19
|
+
"developer-education",
|
|
20
|
+
"backend"
|
|
13
21
|
],
|
|
14
22
|
"repository": {
|
|
15
23
|
"type": "git",
|