keycode-ai 0.0.0-stage → 0.1.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 (366) hide show
  1. package/CHANGELOG.md +101 -0
  2. package/LICENSE +201 -0
  3. package/README.md +547 -2
  4. package/dist/app/agent.d.ts +126 -0
  5. package/dist/app/agent.js +613 -0
  6. package/dist/app/agent.js.map +1 -0
  7. package/dist/app/commands.d.ts +15 -0
  8. package/dist/app/commands.js +281 -0
  9. package/dist/app/commands.js.map +1 -0
  10. package/dist/app/compact.d.ts +23 -0
  11. package/dist/app/compact.js +75 -0
  12. package/dist/app/compact.js.map +1 -0
  13. package/dist/app/export.d.ts +6 -0
  14. package/dist/app/export.js +56 -0
  15. package/dist/app/export.js.map +1 -0
  16. package/dist/app/factory.d.ts +106 -0
  17. package/dist/app/factory.js +687 -0
  18. package/dist/app/factory.js.map +1 -0
  19. package/dist/app/onboarding.d.ts +6 -0
  20. package/dist/app/onboarding.js +33 -0
  21. package/dist/app/onboarding.js.map +1 -0
  22. package/dist/app/subagent.d.ts +16 -0
  23. package/dist/app/subagent.js +14 -0
  24. package/dist/app/subagent.js.map +1 -0
  25. package/dist/app/trust.d.ts +6 -0
  26. package/dist/app/trust.js +74 -0
  27. package/dist/app/trust.js.map +1 -0
  28. package/dist/app/trustManifest.d.ts +18 -0
  29. package/dist/app/trustManifest.js +171 -0
  30. package/dist/app/trustManifest.js.map +1 -0
  31. package/dist/artifacts/store.d.ts +43 -0
  32. package/dist/artifacts/store.js +159 -0
  33. package/dist/artifacts/store.js.map +1 -0
  34. package/dist/cli/auth.d.ts +7 -0
  35. package/dist/cli/auth.js +68 -0
  36. package/dist/cli/auth.js.map +1 -0
  37. package/dist/cli/doctor.d.ts +19 -0
  38. package/dist/cli/doctor.js +205 -0
  39. package/dist/cli/doctor.js.map +1 -0
  40. package/dist/cli/extra.d.ts +2 -0
  41. package/dist/cli/extra.js +990 -0
  42. package/dist/cli/extra.js.map +1 -0
  43. package/dist/cli/headless.d.ts +20 -0
  44. package/dist/cli/headless.js +224 -0
  45. package/dist/cli/headless.js.map +1 -0
  46. package/dist/cli/index.d.ts +4 -0
  47. package/dist/cli/index.js +284 -0
  48. package/dist/cli/index.js.map +1 -0
  49. package/dist/contracts/message.d.ts +34 -0
  50. package/dist/contracts/message.js +10 -0
  51. package/dist/contracts/message.js.map +1 -0
  52. package/dist/contracts/permissions.d.ts +16 -0
  53. package/dist/contracts/permissions.js +9 -0
  54. package/dist/contracts/permissions.js.map +1 -0
  55. package/dist/contracts/provider.d.ts +65 -0
  56. package/dist/contracts/provider.js +2 -0
  57. package/dist/contracts/provider.js.map +1 -0
  58. package/dist/contracts/session.d.ts +101 -0
  59. package/dist/contracts/session.js +11 -0
  60. package/dist/contracts/session.js.map +1 -0
  61. package/dist/contracts/tool.d.ts +81 -0
  62. package/dist/contracts/tool.js +15 -0
  63. package/dist/contracts/tool.js.map +1 -0
  64. package/dist/core/budget.d.ts +11 -0
  65. package/dist/core/budget.js +22 -0
  66. package/dist/core/budget.js.map +1 -0
  67. package/dist/core/context.d.ts +27 -0
  68. package/dist/core/context.js +92 -0
  69. package/dist/core/context.js.map +1 -0
  70. package/dist/extensions/commands.d.ts +23 -0
  71. package/dist/extensions/commands.js +103 -0
  72. package/dist/extensions/commands.js.map +1 -0
  73. package/dist/extensions/customAgents.d.ts +19 -0
  74. package/dist/extensions/customAgents.js +85 -0
  75. package/dist/extensions/customAgents.js.map +1 -0
  76. package/dist/extensions/frontmatter.d.ts +6 -0
  77. package/dist/extensions/frontmatter.js +73 -0
  78. package/dist/extensions/frontmatter.js.map +1 -0
  79. package/dist/extensions/hooks.d.ts +63 -0
  80. package/dist/extensions/hooks.js +145 -0
  81. package/dist/extensions/hooks.js.map +1 -0
  82. package/dist/extensions/loops.d.ts +27 -0
  83. package/dist/extensions/loops.js +119 -0
  84. package/dist/extensions/loops.js.map +1 -0
  85. package/dist/extensions/plugins.d.ts +29 -0
  86. package/dist/extensions/plugins.js +119 -0
  87. package/dist/extensions/plugins.js.map +1 -0
  88. package/dist/extensions/skills.d.ts +21 -0
  89. package/dist/extensions/skills.js +89 -0
  90. package/dist/extensions/skills.js.map +1 -0
  91. package/dist/extensions/statusline.d.ts +13 -0
  92. package/dist/extensions/statusline.js +30 -0
  93. package/dist/extensions/statusline.js.map +1 -0
  94. package/dist/extensions/styles.d.ts +14 -0
  95. package/dist/extensions/styles.js +79 -0
  96. package/dist/extensions/styles.js.map +1 -0
  97. package/dist/extensions/teams.d.ts +44 -0
  98. package/dist/extensions/teams.js +79 -0
  99. package/dist/extensions/teams.js.map +1 -0
  100. package/dist/extensions/themes.d.ts +25 -0
  101. package/dist/extensions/themes.js +109 -0
  102. package/dist/extensions/themes.js.map +1 -0
  103. package/dist/extensions/workflows.d.ts +28 -0
  104. package/dist/extensions/workflows.js +65 -0
  105. package/dist/extensions/workflows.js.map +1 -0
  106. package/dist/gateway/index.d.ts +25 -0
  107. package/dist/gateway/index.js +125 -0
  108. package/dist/gateway/index.js.map +1 -0
  109. package/dist/integrations/background.d.ts +35 -0
  110. package/dist/integrations/background.js +167 -0
  111. package/dist/integrations/background.js.map +1 -0
  112. package/dist/integrations/browser.d.ts +36 -0
  113. package/dist/integrations/browser.js +80 -0
  114. package/dist/integrations/browser.js.map +1 -0
  115. package/dist/integrations/github.d.ts +44 -0
  116. package/dist/integrations/github.js +72 -0
  117. package/dist/integrations/github.js.map +1 -0
  118. package/dist/integrations/ide.d.ts +29 -0
  119. package/dist/integrations/ide.js +69 -0
  120. package/dist/integrations/ide.js.map +1 -0
  121. package/dist/integrations/import.d.ts +14 -0
  122. package/dist/integrations/import.js +76 -0
  123. package/dist/integrations/import.js.map +1 -0
  124. package/dist/integrations/playwrightDriver.d.ts +8 -0
  125. package/dist/integrations/playwrightDriver.js +70 -0
  126. package/dist/integrations/playwrightDriver.js.map +1 -0
  127. package/dist/integrations/pr.d.ts +23 -0
  128. package/dist/integrations/pr.js +81 -0
  129. package/dist/integrations/pr.js.map +1 -0
  130. package/dist/integrations/remote.d.ts +107 -0
  131. package/dist/integrations/remote.js +636 -0
  132. package/dist/integrations/remote.js.map +1 -0
  133. package/dist/integrations/runner.d.ts +30 -0
  134. package/dist/integrations/runner.js +56 -0
  135. package/dist/integrations/runner.js.map +1 -0
  136. package/dist/integrations/worktrees.d.ts +17 -0
  137. package/dist/integrations/worktrees.js +40 -0
  138. package/dist/integrations/worktrees.js.map +1 -0
  139. package/dist/integrations/ws.d.ts +9 -0
  140. package/dist/integrations/ws.js +102 -0
  141. package/dist/integrations/ws.js.map +1 -0
  142. package/dist/lsp/client.d.ts +51 -0
  143. package/dist/lsp/client.js +251 -0
  144. package/dist/lsp/client.js.map +1 -0
  145. package/dist/mcp/client.d.ts +56 -0
  146. package/dist/mcp/client.js +153 -0
  147. package/dist/mcp/client.js.map +1 -0
  148. package/dist/mcp/management.d.ts +20 -0
  149. package/dist/mcp/management.js +97 -0
  150. package/dist/mcp/management.js.map +1 -0
  151. package/dist/mcp/tools.d.ts +3 -0
  152. package/dist/mcp/tools.js +26 -0
  153. package/dist/mcp/tools.js.map +1 -0
  154. package/dist/notifications/index.d.ts +25 -0
  155. package/dist/notifications/index.js +63 -0
  156. package/dist/notifications/index.js.map +1 -0
  157. package/dist/permissions/audit.d.ts +25 -0
  158. package/dist/permissions/audit.js +58 -0
  159. package/dist/permissions/audit.js.map +1 -0
  160. package/dist/permissions/broker.d.ts +20 -0
  161. package/dist/permissions/broker.js +51 -0
  162. package/dist/permissions/broker.js.map +1 -0
  163. package/dist/permissions/dangerous.d.ts +7 -0
  164. package/dist/permissions/dangerous.js +42 -0
  165. package/dist/permissions/dangerous.js.map +1 -0
  166. package/dist/permissions/pipeline.d.ts +34 -0
  167. package/dist/permissions/pipeline.js +217 -0
  168. package/dist/permissions/pipeline.js.map +1 -0
  169. package/dist/permissions/prompt.d.ts +2 -0
  170. package/dist/permissions/prompt.js +33 -0
  171. package/dist/permissions/prompt.js.map +1 -0
  172. package/dist/permissions/rules.d.ts +7 -0
  173. package/dist/permissions/rules.js +176 -0
  174. package/dist/permissions/rules.js.map +1 -0
  175. package/dist/platform/index.d.ts +16 -0
  176. package/dist/platform/index.js +55 -0
  177. package/dist/platform/index.js.map +1 -0
  178. package/dist/privacy/index.d.ts +27 -0
  179. package/dist/privacy/index.js +98 -0
  180. package/dist/privacy/index.js.map +1 -0
  181. package/dist/providers/anthropic.d.ts +25 -0
  182. package/dist/providers/anthropic.js +225 -0
  183. package/dist/providers/anthropic.js.map +1 -0
  184. package/dist/providers/budget.d.ts +24 -0
  185. package/dist/providers/budget.js +47 -0
  186. package/dist/providers/budget.js.map +1 -0
  187. package/dist/providers/capabilities.d.ts +9 -0
  188. package/dist/providers/capabilities.js +39 -0
  189. package/dist/providers/capabilities.js.map +1 -0
  190. package/dist/providers/credentials.d.ts +21 -0
  191. package/dist/providers/credentials.js +86 -0
  192. package/dist/providers/credentials.js.map +1 -0
  193. package/dist/providers/fake.d.ts +32 -0
  194. package/dist/providers/fake.js +95 -0
  195. package/dist/providers/fake.js.map +1 -0
  196. package/dist/providers/openai.d.ts +27 -0
  197. package/dist/providers/openai.js +243 -0
  198. package/dist/providers/openai.js.map +1 -0
  199. package/dist/providers/presets.d.ts +20 -0
  200. package/dist/providers/presets.js +166 -0
  201. package/dist/providers/presets.js.map +1 -0
  202. package/dist/providers/registry.d.ts +27 -0
  203. package/dist/providers/registry.js +127 -0
  204. package/dist/providers/registry.js.map +1 -0
  205. package/dist/providers/retry.d.ts +22 -0
  206. package/dist/providers/retry.js +69 -0
  207. package/dist/providers/retry.js.map +1 -0
  208. package/dist/providers/sse.d.ts +5 -0
  209. package/dist/providers/sse.js +74 -0
  210. package/dist/providers/sse.js.map +1 -0
  211. package/dist/providers/textProtocol.d.ts +10 -0
  212. package/dist/providers/textProtocol.js +45 -0
  213. package/dist/providers/textProtocol.js.map +1 -0
  214. package/dist/questions/broker.d.ts +16 -0
  215. package/dist/questions/broker.js +40 -0
  216. package/dist/questions/broker.js.map +1 -0
  217. package/dist/sandbox/command.d.ts +20 -0
  218. package/dist/sandbox/command.js +307 -0
  219. package/dist/sandbox/command.js.map +1 -0
  220. package/dist/sandbox/index.d.ts +21 -0
  221. package/dist/sandbox/index.js +32 -0
  222. package/dist/sandbox/index.js.map +1 -0
  223. package/dist/sdk/index.d.ts +14 -0
  224. package/dist/sdk/index.js +57 -0
  225. package/dist/sdk/index.js.map +1 -0
  226. package/dist/sdk/structured.d.ts +7 -0
  227. package/dist/sdk/structured.js +66 -0
  228. package/dist/sdk/structured.js.map +1 -0
  229. package/dist/storage/autoMemory.d.ts +22 -0
  230. package/dist/storage/autoMemory.js +93 -0
  231. package/dist/storage/autoMemory.js.map +1 -0
  232. package/dist/storage/checkpoints.d.ts +15 -0
  233. package/dist/storage/checkpoints.js +86 -0
  234. package/dist/storage/checkpoints.js.map +1 -0
  235. package/dist/storage/memory.d.ts +21 -0
  236. package/dist/storage/memory.js +137 -0
  237. package/dist/storage/memory.js.map +1 -0
  238. package/dist/storage/schema.d.ts +177 -0
  239. package/dist/storage/schema.js +120 -0
  240. package/dist/storage/schema.js.map +1 -0
  241. package/dist/storage/session.d.ts +56 -0
  242. package/dist/storage/session.js +305 -0
  243. package/dist/storage/session.js.map +1 -0
  244. package/dist/storage/settings.d.ts +17 -0
  245. package/dist/storage/settings.js +146 -0
  246. package/dist/storage/settings.js.map +1 -0
  247. package/dist/telemetry/otel.d.ts +21 -0
  248. package/dist/telemetry/otel.js +71 -0
  249. package/dist/telemetry/otel.js.map +1 -0
  250. package/dist/tools/agent.d.ts +13 -0
  251. package/dist/tools/agent.js +45 -0
  252. package/dist/tools/agent.js.map +1 -0
  253. package/dist/tools/artifact.d.ts +31 -0
  254. package/dist/tools/artifact.js +137 -0
  255. package/dist/tools/artifact.js.map +1 -0
  256. package/dist/tools/bash.d.ts +29 -0
  257. package/dist/tools/bash.js +191 -0
  258. package/dist/tools/bash.js.map +1 -0
  259. package/dist/tools/codemode.d.ts +13 -0
  260. package/dist/tools/codemode.js +77 -0
  261. package/dist/tools/codemode.js.map +1 -0
  262. package/dist/tools/edit.d.ts +11 -0
  263. package/dist/tools/edit.js +128 -0
  264. package/dist/tools/edit.js.map +1 -0
  265. package/dist/tools/glob.d.ts +10 -0
  266. package/dist/tools/glob.js +33 -0
  267. package/dist/tools/glob.js.map +1 -0
  268. package/dist/tools/grep.d.ts +20 -0
  269. package/dist/tools/grep.js +143 -0
  270. package/dist/tools/grep.js.map +1 -0
  271. package/dist/tools/index.d.ts +11 -0
  272. package/dist/tools/index.js +47 -0
  273. package/dist/tools/index.js.map +1 -0
  274. package/dist/tools/lsp.d.ts +30 -0
  275. package/dist/tools/lsp.js +206 -0
  276. package/dist/tools/lsp.js.map +1 -0
  277. package/dist/tools/notebook.d.ts +19 -0
  278. package/dist/tools/notebook.js +83 -0
  279. package/dist/tools/notebook.js.map +1 -0
  280. package/dist/tools/powershell.d.ts +10 -0
  281. package/dist/tools/powershell.js +83 -0
  282. package/dist/tools/powershell.js.map +1 -0
  283. package/dist/tools/question.d.ts +15 -0
  284. package/dist/tools/question.js +50 -0
  285. package/dist/tools/question.js.map +1 -0
  286. package/dist/tools/read.d.ts +10 -0
  287. package/dist/tools/read.js +188 -0
  288. package/dist/tools/read.js.map +1 -0
  289. package/dist/tools/shared.d.ts +8 -0
  290. package/dist/tools/shared.js +35 -0
  291. package/dist/tools/shared.js.map +1 -0
  292. package/dist/tools/skill.d.ts +9 -0
  293. package/dist/tools/skill.js +38 -0
  294. package/dist/tools/skill.js.map +1 -0
  295. package/dist/tools/tasks.d.ts +35 -0
  296. package/dist/tools/tasks.js +139 -0
  297. package/dist/tools/tasks.js.map +1 -0
  298. package/dist/tools/todo.d.ts +27 -0
  299. package/dist/tools/todo.js +40 -0
  300. package/dist/tools/todo.js.map +1 -0
  301. package/dist/tools/walk.d.ts +15 -0
  302. package/dist/tools/walk.js +144 -0
  303. package/dist/tools/walk.js.map +1 -0
  304. package/dist/tools/webfetch.d.ts +22 -0
  305. package/dist/tools/webfetch.js +201 -0
  306. package/dist/tools/webfetch.js.map +1 -0
  307. package/dist/tools/websearch.d.ts +33 -0
  308. package/dist/tools/websearch.js +129 -0
  309. package/dist/tools/websearch.js.map +1 -0
  310. package/dist/tools/write.d.ts +8 -0
  311. package/dist/tools/write.js +51 -0
  312. package/dist/tools/write.js.map +1 -0
  313. package/dist/tui/accessibility.d.ts +4 -0
  314. package/dist/tui/accessibility.js +24 -0
  315. package/dist/tui/accessibility.js.map +1 -0
  316. package/dist/tui/app.d.ts +21 -0
  317. package/dist/tui/app.js +280 -0
  318. package/dist/tui/app.js.map +1 -0
  319. package/dist/tui/format.d.ts +22 -0
  320. package/dist/tui/format.js +91 -0
  321. package/dist/tui/format.js.map +1 -0
  322. package/dist/tui/input.d.ts +9 -0
  323. package/dist/tui/input.js +71 -0
  324. package/dist/tui/input.js.map +1 -0
  325. package/dist/tui/permission.d.ts +2 -0
  326. package/dist/tui/permission.js +2 -0
  327. package/dist/tui/permission.js.map +1 -0
  328. package/dist/updates/index.d.ts +33 -0
  329. package/dist/updates/index.js +60 -0
  330. package/dist/updates/index.js.map +1 -0
  331. package/dist/util/clipboard.d.ts +1 -0
  332. package/dist/util/clipboard.js +30 -0
  333. package/dist/util/clipboard.js.map +1 -0
  334. package/dist/util/clock.d.ts +7 -0
  335. package/dist/util/clock.js +6 -0
  336. package/dist/util/clock.js.map +1 -0
  337. package/dist/util/errors.d.ts +19 -0
  338. package/dist/util/errors.js +64 -0
  339. package/dist/util/errors.js.map +1 -0
  340. package/dist/util/fsx.d.ts +4 -0
  341. package/dist/util/fsx.js +35 -0
  342. package/dist/util/fsx.js.map +1 -0
  343. package/dist/util/ids.d.ts +5 -0
  344. package/dist/util/ids.js +17 -0
  345. package/dist/util/ids.js.map +1 -0
  346. package/dist/util/logger.d.ts +13 -0
  347. package/dist/util/logger.js +23 -0
  348. package/dist/util/logger.js.map +1 -0
  349. package/dist/util/paths.d.ts +14 -0
  350. package/dist/util/paths.js +77 -0
  351. package/dist/util/paths.js.map +1 -0
  352. package/dist/util/redact.d.ts +6 -0
  353. package/dist/util/redact.js +44 -0
  354. package/dist/util/redact.js.map +1 -0
  355. package/dist/util/text.d.ts +4 -0
  356. package/dist/util/text.js +23 -0
  357. package/dist/util/text.js.map +1 -0
  358. package/dist/version.d.ts +1 -0
  359. package/dist/version.js +2 -0
  360. package/dist/version.js.map +1 -0
  361. package/dist/web/public/app.js +917 -0
  362. package/dist/web/public/favicon.svg +5 -0
  363. package/dist/web/public/index.html +197 -0
  364. package/dist/web/public/markdown.js +176 -0
  365. package/dist/web/public/styles.css +1245 -0
  366. package/package.json +55 -4
package/README.md CHANGED
@@ -1,3 +1,548 @@
1
- # Temporary Holding Version
1
+ # KeyCode
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A free, local-first, bring-your-own-key coding agent for the terminal.
4
+
5
+ `KeyCode` is a clean-room reimplementation of the observable workflow of Claude
6
+ Code v2.1.322. It is not affiliated with Anthropic and does not require an
7
+ Anthropic account.
8
+
9
+ **Status:** working alpha. All 90 features have passing acceptance tests. Install
10
+ from a local tarball or run from `dist/`; no registry package yet.
11
+
12
+ ---
13
+
14
+ ## Why
15
+
16
+ Coding agents should not require a subscription to be useful. `KeyCode` is built
17
+ around three rules:
18
+
19
+ 1. **Free by default.** Every feature works with a free-tier API key or a local
20
+ model.
21
+ 2. **Bring your own key.** No shared keys, no proxy, no account required.
22
+ 3. **Local-first.** Your code, prompts, and sessions stay on your machine
23
+ unless you choose a hosted provider.
24
+
25
+ See `FEATURES.md` for the full free-key matrix.
26
+
27
+ ---
28
+
29
+ ## Install
30
+
31
+ The npm package name is `keycode-ai`, but it is not published to the registry
32
+ yet. Build a tarball and install it globally:
33
+
34
+ ```bash
35
+ npm install
36
+ npm run pack:smoke # verifies the tarball in a clean consumer project
37
+ npm pack
38
+ npm install -g ./keycode-ai-0.1.1.tgz
39
+ keycode --version
40
+ ```
41
+
42
+ Or link the working tree while developing:
43
+
44
+ ```bash
45
+ npm install
46
+ npm run build
47
+ npm link
48
+ keycode --version
49
+ ```
50
+
51
+ Run without installing:
52
+
53
+ ```bash
54
+ npm install
55
+ npm run build
56
+ node dist/cli/index.js --provider ollama
57
+ ```
58
+
59
+ ### Upgrade and remove
60
+
61
+ ```bash
62
+ npm install -g ./keycode-ai-<new-version>.tgz
63
+ npm uninstall -g keycode-ai
64
+ ```
65
+
66
+ The package ships `dist/`, `README.md`, `LICENSE`, and `CHANGELOG.md` only.
67
+ Tests, sources, and `node_modules` are excluded. `scripts/validate-package.mjs`
68
+ checks the bin mapping, version, shebang, and license. CI runs `npm run verify`
69
+ on Windows, macOS, and Linux with Node 22 and 24, plus a tarball install test.
70
+
71
+ ---
72
+
73
+ ## Quickstart
74
+
75
+ ```bash
76
+ # Option A: a free hosted key (macOS/Linux)
77
+ export GEMINI_API_KEY="your-key"
78
+ keycode --provider gemini --model gemini-2.5-flash
79
+
80
+ # Option A on Windows PowerShell
81
+ $env:GEMINI_API_KEY="your-key"
82
+ keycode --provider gemini --model gemini-2.5-flash
83
+
84
+ # Option B: a local model, no key
85
+ ollama serve
86
+ ollama pull gemma4:e2b
87
+ keycode --provider ollama --model gemma4:e2b
88
+ ```
89
+
90
+ Then, inside the TUI:
91
+
92
+ ```
93
+ > explain this repository and run the tests
94
+ ```
95
+
96
+ If you run from source instead, replace `keycode` with
97
+ `node dist/cli/index.js`.
98
+
99
+ ---
100
+
101
+ ## Model guidance
102
+
103
+ Native tool calling produces the most reliable results. Free and local options:
104
+
105
+ | Provider | Recommended | Notes |
106
+ |---|---|---|
107
+ | Ollama | `qwen3-coder`, `llama3.1` | Best local tool use. `gemma4:e2b` is the smallest default; it can stop early or repeat work. |
108
+ | LM Studio / llama.cpp | Qwen3-Coder, Devstral | Pick a model whose template supports tools. |
109
+ | Gemini | `gemini-2.5-flash` | Large context, strong tool use. |
110
+ | Groq | `llama-3.3-70b-versatile`, `openai/gpt-oss-120b` | Fast; no vision. |
111
+ | OpenRouter | `qwen/qwen3-coder:free` | Free tier rates vary. |
112
+ | Cerebras | `qwen-3-32b` | Fast; no vision. |
113
+ | Mistral | `mistral-small-latest`, `codestral-latest` | |
114
+ | GitHub Models | `openai/gpt-4o-mini`, `openai/gpt-4.1` | |
115
+
116
+ The agent protects against common small-model failures:
117
+
118
+ - **Repeated calls:** three consecutive identical tool calls are blocked with
119
+ `REPEATED_TOOL_CALL` so the model must verify or finish.
120
+ - **Already-applied edits:** `Edit` returns a successful no-op instead of
121
+ failing and provoking a retry loop.
122
+ - **No native tools:** when a model declares `tools: false`, KeyCode appends a
123
+ documented text protocol to the prompt and parses this fenced block:
124
+
125
+ ````text
126
+ ```keycode-tool
127
+ {"name":"Read","input":{"file_path":"src/index.ts"}}
128
+ ```
129
+ ````
130
+
131
+ Native tool calls are always preferred; the text protocol is a fallback and
132
+ still goes through the permission pipeline.
133
+
134
+ If a model claims work is done without calling tools, ask it to verify with a
135
+ tool, or switch to a tool-capable model.
136
+
137
+ ---
138
+
139
+ ## Release
140
+
141
+ Tag a commit with `v<version>` and push the tag. The release workflow reruns
142
+ `npm run verify` and `npm run pack:smoke`, packs the tarball, writes
143
+ `SHA256SUMS`, and attaches both to a GitHub release.
144
+
145
+ The npm package is `keycode-ai`; the executable is `keycode`. Publishing uses
146
+ the **Publish npm** workflow with an `NPM_TOKEN` secret, or a local
147
+ `npm publish --provenance --access public`. See `docs/releasing.md` and
148
+ `docs/install.md`.
149
+
150
+ ---
151
+
152
+ ## Web UI
153
+
154
+ `keycode remote` serves a local browser interface:
155
+
156
+ ```powershell
157
+ keycode remote --provider ollama
158
+ # Remote Control: http://127.0.0.1:<port>/#token=...
159
+ ```
160
+
161
+ Add `--open` to launch the default browser automatically. If the pairing dialog
162
+ appears, paste either the token or the full printed URL.
163
+
164
+ Open the printed URL. The interface supports:
165
+
166
+ - streamed replies and tool rows,
167
+ - neon glass theme with a grid background, SVG tool icons, and reduced-motion support,
168
+ - Markdown rendering, fenced code blocks, and copy buttons,
169
+ - edit and write diffs in the approval dialog,
170
+ - multiple-choice `AskUserQuestion` dialogs with radio/checkbox options and free-form answers,
171
+ - allow once / always / session / deny / cancel,
172
+ - session list, new session, resume with history, rename, fork, and delete,
173
+ - artifact panel with versioned HTML previews rendered inside the UI,
174
+ - provider/model switching that keeps the current session,
175
+ - editor context from the VS Code extension: active file and selection shown
176
+ above the composer and attached to prompts; **Detach** clears it,
177
+ - stop and reconnect,
178
+ - pairing by token, with the server bound to loopback only.
179
+
180
+ Static assets are public, but every conversation action and the WebSocket
181
+ require the token. The page reads it from the URL fragment, so it is not sent
182
+ with static file requests or written to logs; the WebSocket handshake sends it
183
+ once as a query parameter. `--permission-mode` defaults to `manual`, since
184
+ approvals happen in the browser.
185
+
186
+ If the token is lost, stop the server and run the command again; a new token is
187
+ generated. Pass `--token <value>` to reuse one on a trusted loopback setup.
188
+
189
+ ---
190
+
191
+ ## VS Code
192
+
193
+ `editors/vscode` contains an extension that starts `keycode remote` and opens the
194
+ same web UI in a VS Code editor tab.
195
+
196
+ ```powershell
197
+ cd editors/vscode
198
+ npx @vscode/vsce package
199
+ code --install-extension keycode-vscode-0.1.1.vsix
200
+ ```
201
+
202
+ Then run **KeyCode: Open Chat** from the Command Palette. The extension has
203
+ settings for executable, provider, model, permission mode, working directory,
204
+ and whether to open in an editor tab or the external browser. The server is
205
+ stopped when the extension deactivates.
206
+
207
+ The extension is plain CommonJS, so there is no build step. It requires the
208
+ KeyCode CLI on `PATH` or an absolute `keycode.executable`. `npm run
209
+ extension:smoke` loads the extension with a mocked VS Code API and verifies the
210
+ real server launch in a temp workspace.
211
+
212
+ ---
213
+
214
+ ## Language servers
215
+
216
+ When language servers are configured, the agent gets an `LSP` tool for
217
+ diagnostics, hover, definition, and references:
218
+
219
+ ```json
220
+ {
221
+ "lsp": {
222
+ "typescript": { "command": "typescript-language-server", "args": ["--stdio"] },
223
+ "python": { "command": "pyright-langserver", "args": ["--stdio"] }
224
+ }
225
+ }
226
+ ```
227
+
228
+ Servers are started on first use and keyed by language id. The tool resolves
229
+ `.ts`, `.tsx`, `.js`, `.py`, `.rs`, `.go`, `.java`, `.c`, `.cpp`, `.json`,
230
+ `.md`, `.css`, `.html`, `.sh`, and `.ps1`, and accepts a `"*"` fallback. Line
231
+ and character inputs are 1-based. Requests time out; a failing server returns an
232
+ error result instead of breaking the turn.
233
+
234
+ KeyCode does not bundle language servers. Install them separately or point at
235
+ an absolute path. For TypeScript projects without a local `typescript`
236
+ installation, point the server at a `tsserver.js`:
237
+
238
+ ```json
239
+ {
240
+ "lsp": {
241
+ "typescript": {
242
+ "command": "typescript-language-server",
243
+ "args": ["--stdio"],
244
+ "initializationOptions": {
245
+ "tsserver": { "path": "C:/Users/me/AppData/Roaming/npm/node_modules/typescript/lib/tsserver.js" }
246
+ }
247
+ }
248
+ }
249
+ }
250
+ ```
251
+
252
+ `--bare` and `--safe-mode` skip LSP; `--restricted` removes the `LSP` tool.
253
+ LSP settings are ignored in untrusted workspaces.
254
+
255
+ ---
256
+
257
+ ## Artifacts, browser, and Code Mode
258
+
259
+ These are agent tools, not CLI-only features.
260
+
261
+ **Artifacts** are enabled by default. The `Artifact` tool can create, update,
262
+ list, inspect, comment on, set data for, and preview versioned local HTML files.
263
+ Previews bind to loopback and require a token. Disable them with:
264
+
265
+ ```json
266
+ { "artifacts": { "enabled": false } }
267
+ ```
268
+
269
+ **Code Mode** is opt-in. Enable it with:
270
+
271
+ ```json
272
+ { "codeMode": true }
273
+ ```
274
+
275
+ It runs JavaScript in a `node:vm` context with a persistent `state` object, a
276
+ `console.log` bridge, and `tools.call(name, input)`. It is permission-gated and
277
+ is not a security boundary.
278
+
279
+ **Browser** automation works out of the box through `playwright-core` and an
280
+ installed Chrome:
281
+
282
+ ```json
283
+ {
284
+ "browser": {
285
+ "enabled": true,
286
+ "allowedDomains": ["example.com", "docs.example.com"],
287
+ "headless": true
288
+ }
289
+ }
290
+ ```
291
+
292
+ Set `channel` (default `chrome`), `executablePath`, `headless`, and `timeoutMs`
293
+ as needed. The driver launches lazily on the first navigation and closes with
294
+ the session.
295
+
296
+ A custom driver module is still supported:
297
+
298
+ ```json
299
+ {
300
+ "browser": {
301
+ "driver": "./browser-driver.mjs",
302
+ "allowedDomains": ["example.com"]
303
+ }
304
+ }
305
+ ```
306
+
307
+ The module must export `createBrowserDriver(options)` or a default driver with
308
+ `navigate`, `click`, `type`, `readDom`, `screenshot`, and optional `close`.
309
+ Origins outside the allowlist are denied before the driver is called. Browser
310
+ settings are ignored in untrusted workspaces. `--restricted` removes the tool.
311
+
312
+ ---
313
+
314
+ ## Workspace trust
315
+
316
+ Project settings can run hooks, MCP servers, language servers, browser drivers,
317
+ and commands, and can add permission rules. Before any of that applies, KeyCode
318
+ shows a review:
319
+
320
+ - TUI: a terminal prompt lists each item and asks for approval.
321
+ - Web UI and VS Code: a project-trust banner opens a review dialog with
322
+ **Keep restricted** and **Trust workspace**.
323
+
324
+ The review lists:
325
+
326
+ - permission `allow`/`ask` rules,
327
+ - hook commands by event,
328
+ - MCP servers with their command or URL,
329
+ - LSP commands,
330
+ - browser driver modules,
331
+ - environment keys,
332
+ - project commands, skills, agents, and output styles with content hashes.
333
+
334
+ Approval is stored in `~/.keycode/trust.json` with a fingerprint. If any
335
+ project-controlled item changes, KeyCode asks again instead of silently applying
336
+ the new configuration.
337
+
338
+ Headless runs cannot prompt, so they stay restricted unless you pass `--trust`.
339
+ Untrusted project settings are ignored.
340
+
341
+ ---
342
+
343
+ ## Runtime operations
344
+
345
+ **Auto-memory** extraction is scheduled after every fifth completed turn by
346
+ default. Change it with `autoMemoryEvery`, or disable it with
347
+ `"autoMemory": false`. A fact is stored only when the model returns a durable
348
+ sentence; paused memory skips extraction and recall.
349
+
350
+ **Notifications** support a webhook and optional terminal OSC/bell:
351
+
352
+ ```json
353
+ {
354
+ "notifications": {
355
+ "webhook": "http://127.0.0.1:9999/notify",
356
+ "terminal": false,
357
+ "dedupeMs": 5000
358
+ }
359
+ }
360
+ ```
361
+
362
+ Events include `permission_required`, `input_needed`, and `task_complete`.
363
+ Webhook payloads contain `{ event, text, timestamp }`.
364
+
365
+ **OpenTelemetry** requires explicit privacy consent:
366
+
367
+ ```json
368
+ {
369
+ "otel": {
370
+ "endpoint": "http://127.0.0.1:4318/v1/metrics",
371
+ "serviceName": "keycode",
372
+ "sampleRate": 1
373
+ }
374
+ }
375
+ ```
376
+
377
+ Metrics are emitted for turns, input/output tokens, cost, and tool-call counts.
378
+ `telemetryEnabled()` still honors `privacy.json`, `KEYCODE_TELEMETRY=0`, and
379
+ `DO_NOT_TRACK=1`; without consent, no metrics are recorded.
380
+
381
+ ---
382
+
383
+ ## Security checks
384
+
385
+ - **WebFetch** resolves each hostname before requesting it and blocks results in
386
+ loopback, private, link-local, CGNAT, documentation, benchmark, multicast, and
387
+ metadata ranges. Redirects are re-validated with a fresh DNS lookup. An
388
+ explicitly allowlisted host bypasses these checks.
389
+ - **Write** and **Edit** scan content for common credentials before touching
390
+ disk. A new AWS, GitHub, Slack, Anthropic, OpenAI, Google, Groq, bearer, or
391
+ generic `api_key`/`token`/`secret`/`password` value is refused with
392
+ `SECRET_DETECTED`. Editing a file that already contains a credential is
393
+ allowed as long as the edit does not add another.
394
+ - **Audit logs** and transcripts continue to redact known secret formats.
395
+
396
+ DNS checks reduce SSRF risk but do not eliminate DNS rebinding between the check
397
+ and the connection; a pinned-IP transport is still future work.
398
+
399
+ ---
400
+
401
+ ## Permissions
402
+
403
+ Every tool call goes through one permission pipeline, including MCP tools.
404
+
405
+ - **Modes:** `manual` (default), `acceptEdits`, `plan`, `auto`, `dontAsk`,
406
+ `bypassPermissions`.
407
+ - **TUI:** when a tool needs approval, a dialog shows the request with a
408
+ command preview or an edit diff. Choose allow once / allow always / allow for
409
+ session / deny / cancel.
410
+ - **Headless:** there is no prompt, so an unapproved call is denied and the
411
+ result names the exact rule to add, for example:
412
+ `Add --allow "Bash(npm test)" or run interactively.`
413
+ - **Rules:** repeatable and evaluated deny → ask → allow:
414
+
415
+ ```bash
416
+ node dist/cli/index.js --provider ollama \
417
+ --deny "Read(./.env)" \
418
+ --allow "Bash(npm test:*)" \
419
+ --allow "Edit(src/**)" \
420
+ -p "run the tests and fix failures"
421
+ ```
422
+
423
+ A command rule without `:*` matches exactly, so `Bash(npm test)` does not
424
+ allow `npm test; curl ...`. Use `Bash(npm test:*)` to allow that command with
425
+ any arguments, or a glob such as `Bash(git *)` to opt into a family of
426
+ commands. Allow rules never extend to compound shell commands unless the rule
427
+ itself contains the operator.
428
+
429
+ `allow always` in the TUI persists a specific rule (command or path), not a
430
+ whole-tool grant.
431
+
432
+ ---
433
+
434
+ ## Sandbox
435
+
436
+ `--sandbox` confines commands to the workspace roots (plus `--add-dir` roots)
437
+ and blocks network egress by default.
438
+
439
+ ```bash
440
+ node dist/cli/index.js --provider ollama --sandbox -p "run the tests"
441
+ node dist/cli/index.js --sandbox --sandbox-network --sandbox-allow-host api.example.com ...
442
+ ```
443
+
444
+ Or in `settings.json`:
445
+
446
+ ```json
447
+ {
448
+ "sandbox": { "enabled": true, "allowNetwork": false, "allowedHosts": ["api.example.com"] }
449
+ }
450
+ ```
451
+
452
+ The JSON above belongs in a settings file, not in a PowerShell prompt:
453
+ `~/.keycode/settings.json` (all projects), `.keycode/settings.json` (project),
454
+ or `.keycode/settings.local.json` (local). Project layers only apply when the
455
+ workspace is trusted.
456
+
457
+ Enforcement:
458
+
459
+ - **macOS:** wraps commands with `/usr/bin/sandbox-exec` and a Seatbelt profile
460
+ that denies writes outside the roots and denies network unless allowed.
461
+ - **Linux:** wraps commands with `bwrap` (`--unshare-net`, read-only root,
462
+ writable workspace roots) when installed.
463
+ - **Windows (fallback):** no kernel sandbox. A static guard blocks redirection,
464
+ common write commands, and known network commands that target paths outside
465
+ the roots or hosts outside the allowlist, and startup prints the documented
466
+ fallback warning. Commands that perform I/O indirectly (for example a script
467
+ launched by an interpreter) are not contained by this fallback.
468
+
469
+ The guard also runs before every command on all platforms, so an approved
470
+ `bypassPermissions` command still cannot redirect output outside the roots.
471
+
472
+ Process-count and memory limits are not enforced yet.
473
+
474
+ ---
475
+
476
+ ## MCP servers
477
+
478
+ Enabled entries in `settings.json` under `mcpServers` (stdio or HTTP/SSE) are
479
+ connected on startup and exposed as `mcp__<server>__<tool>` tools. A failing
480
+ server produces a warning and does not abort the session.
481
+
482
+ ```json
483
+ {
484
+ "mcpServers": {
485
+ "docs": { "type": "stdio", "command": "node", "args": ["server.mjs"] }
486
+ }
487
+ }
488
+ ```
489
+
490
+ ---
491
+
492
+ ## Documents
493
+
494
+ | File | Purpose |
495
+ |---|---|
496
+ | `AGENTS.md` | Rules for coding agents: clean-room, safety, tests, git, definition of done. |
497
+ | `FEATURES.md` | Scope, free-key policy, provider matrix, parity decisions, non-goals. |
498
+ | `SPEC.md` | Architecture, contracts, all 90 features, one acceptance test each, three-part build plan. |
499
+ | `EVIDENCE.md` | Provenance: target hash, extraction method, observations, limitations. |
500
+
501
+ ---
502
+
503
+ ## The 90 features
504
+
505
+ | Domain | Count |
506
+ |---|---:|
507
+ | Core runtime | 10 |
508
+ | Providers and free keys | 9 |
509
+ | Tools | 19 |
510
+ | Safety | 9 |
511
+ | Memory and context | 7 |
512
+ | Extensibility | 12 |
513
+ | Integrations | 10 |
514
+ | User experience | 8 |
515
+ | Platform and operations | 6 |
516
+ | **Total** | **90** |
517
+
518
+ Each feature has exactly one acceptance test, named `T-<feature ID>`.
519
+
520
+ ---
521
+
522
+ ## Build plan
523
+
524
+ 1. **Part 1 — Free key, real work (weeks 1-4).** REPL, sessions, streaming,
525
+ free providers, core tools, permissions, memory, basic TUI.
526
+ 2. **Part 2 — Extensible and safe (weeks 5-8).** Web, MCP, LSP, subagents,
527
+ sandbox, hooks, skills, agents, plugins, teams, workflows, telemetry.
528
+ 3. **Part 3 — Scale and integrate (weeks 9-12).** SDK, GitHub, IDE, browser,
529
+ Remote Control, self-hosted runner, background sessions, worktrees, release.
530
+
531
+ Details and exit gates are in `SPEC.md` section 12.
532
+
533
+ ---
534
+
535
+ ## Validate the spec
536
+
537
+ ```bash
538
+ npm run validate:spec
539
+ ```
540
+
541
+ This checks that all 90 features have unique IDs, exactly one matching test,
542
+ and a valid build part.
543
+
544
+ ---
545
+
546
+ ## License
547
+
548
+ Apache-2.0. See `LICENSE`.
@@ -0,0 +1,126 @@
1
+ import type { Usage } from "../contracts/message.js";
2
+ import type { ModelCapabilities, Provider, StopReason } from "../contracts/provider.js";
3
+ import type { Question, QuestionResult, Tool, ToolState } from "../contracts/tool.js";
4
+ import type { SessionStore } from "../storage/session.js";
5
+ import type { CheckpointStore, RewindMode } from "../storage/checkpoints.js";
6
+ import type { PermissionService } from "../permissions/pipeline.js";
7
+ import type { SandboxPolicy } from "../sandbox/index.js";
8
+ import type { BudgetGuard, Pricing } from "../providers/budget.js";
9
+ import { type Clock } from "../util/clock.js";
10
+ import { type Logger } from "../util/logger.js";
11
+ import { type CompactResult } from "./compact.js";
12
+ import type { HookDispatcher } from "../extensions/hooks.js";
13
+ export type AgentEvent = {
14
+ type: "text";
15
+ delta: string;
16
+ } | {
17
+ type: "thinking";
18
+ delta: string;
19
+ } | {
20
+ type: "tool_start";
21
+ id: string;
22
+ name: string;
23
+ input: unknown;
24
+ } | {
25
+ type: "tool_result";
26
+ id: string;
27
+ name: string;
28
+ ok: boolean;
29
+ text: string;
30
+ } | {
31
+ type: "usage";
32
+ inputTokens: number;
33
+ outputTokens: number;
34
+ cachedTokens?: number | undefined;
35
+ } | {
36
+ type: "done";
37
+ stopReason: StopReason;
38
+ } | {
39
+ type: "error";
40
+ error: unknown;
41
+ };
42
+ export interface AgentOptions {
43
+ sessionId: string;
44
+ store: SessionStore;
45
+ provider: Provider;
46
+ providerId: string;
47
+ model: string;
48
+ tools: Tool[];
49
+ permissions: PermissionService;
50
+ home: string;
51
+ cwd: string;
52
+ workspaceRoots: string[];
53
+ sandbox?: SandboxPolicy | undefined;
54
+ systemPrompt: string;
55
+ buildPrompt?: (() => string) | undefined;
56
+ clock?: Clock | undefined;
57
+ logger?: Logger | undefined;
58
+ budget?: BudgetGuard | undefined;
59
+ pricing?: Pricing | undefined;
60
+ capabilities?: ModelCapabilities | undefined;
61
+ autoCompactThreshold?: number | undefined;
62
+ effort?: "low" | "medium" | "high" | "xhigh" | "max" | undefined;
63
+ maxToolCalls?: number | undefined;
64
+ fallback?: {
65
+ provider: Provider;
66
+ model: string;
67
+ } | undefined;
68
+ checkpointStore?: CheckpointStore | undefined;
69
+ askQuestions?: ((questions: Question[]) => Promise<QuestionResult>) | undefined;
70
+ onEvent?: ((event: AgentEvent) => void) | undefined;
71
+ hooks?: HookDispatcher | undefined;
72
+ onTurnComplete?: ((result: TurnResult, signal: AbortSignal) => Promise<void> | void) | undefined;
73
+ }
74
+ export interface TurnResult {
75
+ text: string;
76
+ usage: Usage;
77
+ costUsd: number;
78
+ toolCalls: number;
79
+ stopReason: StopReason;
80
+ interrupted: boolean;
81
+ }
82
+ export declare class Agent {
83
+ private readonly options;
84
+ private readonly toolState;
85
+ private readonly subscribers;
86
+ private systemPrompt;
87
+ private turn;
88
+ private sessionUsage;
89
+ private sessionCost;
90
+ constructor(options: AgentOptions);
91
+ get sessionId(): string;
92
+ get providerId(): string;
93
+ get model(): string;
94
+ get effort(): AgentOptions["effort"];
95
+ get cwd(): string;
96
+ get usage(): Usage;
97
+ get costUsd(): number;
98
+ get state(): ToolState;
99
+ get workspaceRoots(): string[];
100
+ get prompt(): string;
101
+ setModel(model: string): void;
102
+ setEffort(effort: NonNullable<AgentOptions["effort"]>): void;
103
+ setWorkspace(cwd: string, workspaceRoots?: string[] | undefined): void;
104
+ private capabilities;
105
+ subscribe(handler: (event: AgentEvent) => void): () => void;
106
+ private emit;
107
+ private streamWithFallback;
108
+ private streamTurn;
109
+ private costFor;
110
+ private toolContext;
111
+ private repeatedCallResult;
112
+ private executeToolCall;
113
+ runTurn(input: string, signal: AbortSignal): Promise<TurnResult>;
114
+ sideQuestion(question: string, signal: AbortSignal): Promise<string>;
115
+ branch(name?: string): string;
116
+ rewind(checkpointId: string, mode: RewindMode): {
117
+ files: number;
118
+ messages: number;
119
+ };
120
+ compact(instructions?: string, signal?: AbortSignal): Promise<CompactResult>;
121
+ private maybeAutoCompact;
122
+ contextEstimate(): {
123
+ tokens: number;
124
+ messages: number;
125
+ };
126
+ }