cognitune 0.2.2 → 0.3.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/CHANGELOG.md +55 -0
- package/README.md +184 -41
- package/SETUP.md +111 -0
- package/dist/cli.js +161 -21
- package/dist/web/assets/Map-xBJDQ_Xn.js +1 -0
- package/dist/web/assets/{Practice-Xw4Aap9n.js → Practice-DNf-tMjl.js} +3 -3
- package/dist/web/assets/{_baseUniq-Sb6_kXmC.js → _baseUniq-7KLmbwxc.js} +1 -1
- package/dist/web/assets/{architectureDiagram-UYN6MBPD-x3eTjV-t.js → architectureDiagram-UYN6MBPD-DFK-K3Yp.js} +1 -1
- package/dist/web/assets/{blockDiagram-ZHA2E4KO-agwz5ZWE.js → blockDiagram-ZHA2E4KO-D9jSBc-F.js} +1 -1
- package/dist/web/assets/{c4Diagram-6F5ED5ID-CJxB9Ung.js → c4Diagram-6F5ED5ID-KAOALvx3.js} +1 -1
- package/dist/web/assets/channel-BW4MllLS.js +1 -0
- package/dist/web/assets/{chunk-5HRBRIJM-f0vN99nH.js → chunk-5HRBRIJM-Btr12S8H.js} +1 -1
- package/dist/web/assets/{chunk-7U56Z5CX-BM--ABPc.js → chunk-7U56Z5CX-NWMyaEQ0.js} +1 -1
- package/dist/web/assets/{chunk-ASOPGD6M-CR8uj1YE.js → chunk-ASOPGD6M-DdvxpUSZ.js} +1 -1
- package/dist/web/assets/{chunk-KFBOBJHC-5IsURXrq.js → chunk-KFBOBJHC-CLK5Qods.js} +1 -1
- package/dist/web/assets/{chunk-T2TOU4HS-Byx0enoR.js → chunk-T2TOU4HS-B-nrzheR.js} +1 -1
- package/dist/web/assets/{chunk-TMUBEWPD-BIF411CX.js → chunk-TMUBEWPD-DCsdC8PC.js} +1 -1
- package/dist/web/assets/classDiagram-LNE6IOMH-D4kEJsvG.js +1 -0
- package/dist/web/assets/classDiagram-v2-MQ7JQ4JX-D4kEJsvG.js +1 -0
- package/dist/web/assets/clone-C8mTbP7R.js +1 -0
- package/dist/web/assets/{dagre-4EVJKHTY-1RD8lskl.js → dagre-4EVJKHTY-D_09gC0H.js} +1 -1
- package/dist/web/assets/{diagram-QW4FP2JN-PO1Q65My.js → diagram-QW4FP2JN-quH5WQny.js} +1 -1
- package/dist/web/assets/{erDiagram-6RL3IURR-Cr2hBiWe.js → erDiagram-6RL3IURR-BmJHLDew.js} +1 -1
- package/dist/web/assets/{flowDiagram-7ASYPVHJ-ClDedrj1.js → flowDiagram-7ASYPVHJ-DNzT7Cua.js} +1 -1
- package/dist/web/assets/{ganttDiagram-NTVNEXSI-D13tzRyI.js → ganttDiagram-NTVNEXSI-6reJ1AIG.js} +1 -1
- package/dist/web/assets/{gitGraph-YCYPL57B-BsavMmM6.js → gitGraph-YCYPL57B-BfipSUJ3.js} +1 -1
- package/dist/web/assets/{gitGraphDiagram-NRZ2UAAF-DIucBoe8.js → gitGraphDiagram-NRZ2UAAF-BRb9bqzI.js} +1 -1
- package/dist/web/assets/{graph-CClVjaHZ.js → graph-BHXuL-RR.js} +1 -1
- package/dist/web/assets/{index-DBSUkj1m.js → index-7JDqNzz1.js} +1 -1
- package/dist/web/assets/{index-B3eGs35g.js → index-B49g1XNF.js} +1 -1
- package/dist/web/assets/{index-D91GOqgw.js → index-B5Tomqy6.js} +1 -1
- package/dist/web/assets/{index-D45gW5O5.js → index-BCM7jSxq.js} +1 -1
- package/dist/web/assets/{index-DRtWlWMo.js → index-BM9KwSU5.js} +1 -1
- package/dist/web/assets/{index-CS1X9Gl5.js → index-BiiiKqbq.js} +1 -1
- package/dist/web/assets/{index-2r9n9DTs.js → index-Bli4383n.js} +1 -1
- package/dist/web/assets/{index-CMZRuo_o.js → index-BsH1Ca5H.js} +1 -1
- package/dist/web/assets/{index-BqYXODG4.js → index-Bsf4UF_h.js} +1 -1
- package/dist/web/assets/{index-DxsK976j.js → index-C5JoMvch.js} +1 -1
- package/dist/web/assets/{index-DkYraAal.js → index-C67RtHfG.js} +1 -1
- package/dist/web/assets/{index-DDrV_F4m.js → index-CNViI9C2.js} +1 -1
- package/dist/web/assets/{index-BOSsA0NJ.js → index-CQjof-kk.js} +1 -1
- package/dist/web/assets/{index-ByIxB7D0.js → index-CyHGDhfc.js} +1 -1
- package/dist/web/assets/index-CyhIx47s.css +1 -0
- package/dist/web/assets/{index-B_vWzZYC.js → index-D-DY42g9.js} +1 -1
- package/dist/web/assets/{index-Cv-pFH6x.js → index-DRri1mnd.js} +1 -1
- package/dist/web/assets/{index-o9r5KATO.js → index-DXji-ikE.js} +1 -1
- package/dist/web/assets/{index-SjGg9_vE.js → index-D_DIS1os.js} +1 -1
- package/dist/web/assets/{index-DUIbUB4M.js → index-Dl6tJxzv.js} +1 -1
- package/dist/web/assets/{index-eIlS8nUF.js → index-TI1LWXRL.js} +1 -1
- package/dist/web/assets/index-dA5Y-R2D.js +514 -0
- package/dist/web/assets/{index-6LcRt5Lv.js → index-wnqHtEcu.js} +1 -1
- package/dist/web/assets/{index-Dls_C4WS.js → index-ysHMZpcw.js} +1 -1
- package/dist/web/assets/{infoDiagram-A4XQUW5V-DAnVWlAh.js → infoDiagram-A4XQUW5V-CE9eDiRA.js} +1 -1
- package/dist/web/assets/{journeyDiagram-G5WM74LC-pfkLfgwO.js → journeyDiagram-G5WM74LC-D_iPCzBK.js} +1 -1
- package/dist/web/assets/{kanban-definition-QRCXZQQD-ntmo18GF.js → kanban-definition-QRCXZQQD-Bxj-EOmZ.js} +1 -1
- package/dist/web/assets/{layout-B4CWy8Hm.js → layout-CQ6J22ew.js} +1 -1
- package/dist/web/assets/layout.worker-Bzrmqu8H.js +1 -0
- package/dist/web/assets/{mermaid.core-lBUDS75V.js → mermaid.core-27sLJoRM.js} +4 -4
- package/dist/web/assets/{min-DbZdLDS_.js → min-h0zR_W4w.js} +1 -1
- package/dist/web/assets/{mindmap-definition-GWI6TPTV-Bl9WyGjM.js → mindmap-definition-GWI6TPTV-DiBTVWc8.js} +28 -28
- package/dist/web/assets/{pieDiagram-YF2LJOPJ-DnH09lh-.js → pieDiagram-YF2LJOPJ-BE2VMHC3.js} +1 -1
- package/dist/web/assets/{quadrantDiagram-OS5C2QUG-BxEAU4LU.js → quadrantDiagram-OS5C2QUG-DkN-8Avj.js} +1 -1
- package/dist/web/assets/{requirementDiagram-MIRIMTAZ-QAvHb6Mc.js → requirementDiagram-MIRIMTAZ-0OCRbKti.js} +1 -1
- package/dist/web/assets/{sankeyDiagram-Y46BX6SQ-eS48EBnq.js → sankeyDiagram-Y46BX6SQ-6v9qBJFv.js} +1 -1
- package/dist/web/assets/{sequenceDiagram-G6AWOVSC-CzMqlsbJ.js → sequenceDiagram-G6AWOVSC-CjH7axp-.js} +1 -1
- package/dist/web/assets/{stateDiagram-MAYHULR4-xkap43Xx.js → stateDiagram-MAYHULR4-Bbbno_Ix.js} +1 -1
- package/dist/web/assets/stateDiagram-v2-4JROLMXI-CvrRdVH2.js +1 -0
- package/dist/web/assets/{timeline-definition-U7ZMHBDA-BAuokBbp.js → timeline-definition-U7ZMHBDA-BSIsFSlr.js} +1 -1
- package/dist/web/assets/{xychartDiagram-6QU3TZC5-Cnc3AQRt.js → xychartDiagram-6QU3TZC5-B12dxFiy.js} +1 -1
- package/dist/web/index.html +2 -2
- package/package.json +2 -1
- package/dist/web/assets/Map-DyU40kFC.js +0 -1
- package/dist/web/assets/channel-BBLQ9UF8.js +0 -1
- package/dist/web/assets/classDiagram-LNE6IOMH-BtyOxYYt.js +0 -1
- package/dist/web/assets/classDiagram-v2-MQ7JQ4JX-BtyOxYYt.js +0 -1
- package/dist/web/assets/clone-qT-pKr2u.js +0 -1
- package/dist/web/assets/index-Biw9rLAa.css +0 -1
- package/dist/web/assets/index-ChTnBaTd.js +0 -493
- package/dist/web/assets/stateDiagram-v2-4JROLMXI-T7PcvgVe.js +0 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,60 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.3.1 (2026-11-18)
|
|
4
|
+
|
|
5
|
+
New:
|
|
6
|
+
|
|
7
|
+
- **Progress rolls up by repo and folder.** At a folder of many repos, each repo is one row with a
|
|
8
|
+
coverage bar; click to go into its folders, then files. A scope bar (breadcrumb with a repo picker)
|
|
9
|
+
narrows the cards, table and heatmap, and search filters the touched files in it. The scope lives
|
|
10
|
+
in the address, so it can be bookmarked. Untouched rows fold into one "show N untouched" line.
|
|
11
|
+
- **Map shows repos and folders, not ~2,000 files.** Nodes are repos, then folders, then files at
|
|
12
|
+
the current scope; a folder of 8 code files or fewer shows its files. Imports between two folders
|
|
13
|
+
are one arrow, thicker for more imports, so a Python package's `__init__.py` no longer looks like a
|
|
14
|
+
hub. Click a folder to go in. The layout runs off the main thread behind a placeholder map, and the
|
|
15
|
+
server keeps the graph until you press Refresh (it used to rebuild every minute).
|
|
16
|
+
- README: a banner, the Read / Prove / Keep loop, and screenshots cropped to be readable.
|
|
17
|
+
|
|
18
|
+
Fixes:
|
|
19
|
+
|
|
20
|
+
- Tutor links dropped the word between two ranges: "lines 41-48 and 58-60" showed as "41-4858-60".
|
|
21
|
+
- The Today page's path card said "Do this stop"; it now names the activity ("Start the lens"),
|
|
22
|
+
like the Paths page.
|
|
23
|
+
- The Library's tab strip stretches to fill its row instead of ending in an empty block.
|
|
24
|
+
|
|
25
|
+
## 0.3.0 (2026-11-18)
|
|
26
|
+
|
|
27
|
+
New:
|
|
28
|
+
|
|
29
|
+
- **Lens follow-ups.** "Ask more about this" at the end of a lens adds the answer to the same
|
|
30
|
+
lens instead of making a new one. Ticked files can come along as extra context; new terms and
|
|
31
|
+
gotchas join the lens's lists, and the markdown export includes the follow-ups.
|
|
32
|
+
- **Weak spots page.** A Weak spots tab in the Library: quiz yourself on one weak spot, or
|
|
33
|
+
dismiss one the grader got wrong. Today links to it.
|
|
34
|
+
- **Walk "Try again".** A block you didn't get right can be answered again; a right answer
|
|
35
|
+
clears its weak spot.
|
|
36
|
+
- **Jobs in the status bar.** Running jobs show at the bottom of the window, and a job that
|
|
37
|
+
finishes after you left its page shows a "ready · open" link.
|
|
38
|
+
- **Tutor chat** is restyled as chat bubbles with timestamps, and "line 42" / "lines 64-71" in a
|
|
39
|
+
hint jump the code pane to those lines.
|
|
40
|
+
- Teach-back and the tutor, started from the Changes page, now see the diff (only lens and quiz
|
|
41
|
+
did before). The tutor sees it on every turn.
|
|
42
|
+
- A review card links back to the lens or quiz it came from.
|
|
43
|
+
- `.claude` folders show in the Explore file tree, so session notes can be ticked as context.
|
|
44
|
+
|
|
45
|
+
Fixes:
|
|
46
|
+
|
|
47
|
+
- The tutor's replies rendered at 17px next to 14px user messages: the serif reading-font rule
|
|
48
|
+
out-ranked the chat styles. Both now match.
|
|
49
|
+
- The lens page flickered while a job ran: every mermaid diagram and code block was remounted
|
|
50
|
+
twice a second. Markdown rendering now keeps them mounted.
|
|
51
|
+
- Syntax highlighting now works in the Changes diff view, in fenced code blocks inside lens and
|
|
52
|
+
quiz prose, and in bug hunt's code copy (each was plain text before, for different reasons).
|
|
53
|
+
- File-chip lists on the quiz, teach-back and tutor pages collapse to 6 + "N more", like the
|
|
54
|
+
lens page.
|
|
55
|
+
- The Library's tabs fit on one row instead of scrolling sideways (a narrow window wraps them),
|
|
56
|
+
and a path stop's button says what it starts ("Start the lens") instead of "Do this stop".
|
|
57
|
+
|
|
3
58
|
## 0.2.2 (2026-11-10)
|
|
4
59
|
|
|
5
60
|
Release workflow fix, no feature changes:
|
package/README.md
CHANGED
|
@@ -1,61 +1,193 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/banner-dark.svg">
|
|
4
|
+
<img alt="cognitune. Understand any codebase, and prove to yourself that you do." src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/banner-light.svg" width="860">
|
|
5
|
+
</picture>
|
|
6
|
+
</p>
|
|
7
|
+
|
|
8
|
+
<p align="center">
|
|
9
|
+
<a href="https://www.npmjs.com/package/cognitune"><img alt="npm" src="https://img.shields.io/npm/v/cognitune?color=268bd2"></a>
|
|
10
|
+
<img alt="node 20 or newer" src="https://img.shields.io/badge/node-%3E%3D20-859900">
|
|
11
|
+
<img alt="MIT license" src="https://img.shields.io/badge/license-MIT-b58900">
|
|
12
|
+
<img alt="runs locally" src="https://img.shields.io/badge/runs-locally-586e75">
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
<p align="center">
|
|
16
|
+
<a href="#try-it-in-a-minute"><b>Try it</b></a> ·
|
|
17
|
+
<a href="#what-you-do-in-it"><b>What you do in it</b></a> ·
|
|
18
|
+
<a href="#why-it-works"><b>Why it works</b></a> ·
|
|
19
|
+
<a href="SETUP.md"><b>Setup</b></a> ·
|
|
20
|
+
<a href="CHANGELOG.md"><b>Changelog</b></a>
|
|
21
|
+
</p>
|
|
22
|
+
|
|
23
|
+
AI makes code faster to write and easier to not understand.
|
|
24
|
+
**cognitune turns the model around: it does not write code for you. It teaches you the code you have, then checks that you got it.**
|
|
25
|
+
|
|
26
|
+
## Try it in a minute
|
|
7
27
|
|
|
8
28
|
```bash
|
|
9
|
-
npx cognitune
|
|
10
|
-
npx cognitune
|
|
29
|
+
npx cognitune --demo # a sample repo with canned answers. No model, no login.
|
|
30
|
+
npx cognitune ./my-repo # your own code, with the coding CLI you already use
|
|
11
31
|
```
|
|
12
32
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|  |  |
|
|
33
|
+
- **No new account, no key.** It runs Claude Code, Codex or Copilot with that CLI's own login.
|
|
34
|
+
- **Read-only.** It works from the files you tick, and cognitune never writes to your folders.
|
|
35
|
+
- **Local.** A web app on `127.0.0.1`. Your notes and scores are plain JSON files in `~/.cognitune`.
|
|
17
36
|
|
|
18
|
-
|
|
37
|
+
<p align="center">
|
|
38
|
+
<picture>
|
|
39
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/lens-dark.png">
|
|
40
|
+
<img alt="A lens about a retry queue: the idea in one sentence, why it matters, then the words you need first" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/lens.png" width="860">
|
|
41
|
+
</picture>
|
|
42
|
+
<br>
|
|
43
|
+
<sub>A lens: one question, answered about the files you picked. The screenshots are real model output on the bundled 100-line demo repo (Map and Progress show cognitune's own source).</sub>
|
|
44
|
+
</p>
|
|
19
45
|
|
|
20
|
-
|
|
21
|
-
producing an answer before you see one beats reading the answer.
|
|
46
|
+
## What you do in it
|
|
22
47
|
|
|
23
|
-
|
|
48
|
+
<p align="center">
|
|
49
|
+
<picture>
|
|
50
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/loop-dark.svg">
|
|
51
|
+
<img alt="The loop: 1. Read with a question (lens, tutor, walkthrough). 2. Prove it (quiz, teach-back, practice, bug hunt). 3. Keep it (review cards, weak spots, today). What you got wrong comes back." src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/loop-light.svg" width="860">
|
|
52
|
+
</picture>
|
|
53
|
+
</p>
|
|
54
|
+
|
|
55
|
+
### 1. Read with a question
|
|
24
56
|
|
|
25
57
|
| | |
|
|
26
58
|
|---|---|
|
|
27
|
-
| **
|
|
28
|
-
| **
|
|
29
|
-
| **
|
|
30
|
-
|
|
31
|
-
|
|
59
|
+
| **Lens** | Pick files, pick a question: *Explain*, *Data flow*, *Failure modes*, *Trace a run*, *History*, or your own. You get a lesson where every step shows its own lines of code. Ask a follow-up and the answer joins the same lens. |
|
|
60
|
+
| **Tutor** | A Socratic chat. It gives a nudge first, then a hint, then more. Say "just tell me" any time. Click "line 50" in a reply and the code pane jumps there. |
|
|
61
|
+
| **Walkthrough** | The file in reading order, one block at a time. Each block ends with a question you answer before you go on. |
|
|
62
|
+
|
|
63
|
+
<p align="center">
|
|
64
|
+
<img alt="The tutor answers with a nudge, then a hint. Line numbers in its replies are links into the code pane on the right." src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/tutor.png" width="860">
|
|
65
|
+
<br>
|
|
66
|
+
<sub><b>Tutor.</b> A nudge, then a hint. The blue line numbers jump the code pane.</sub>
|
|
67
|
+
</p>
|
|
68
|
+
|
|
69
|
+
<table>
|
|
70
|
+
<tr>
|
|
71
|
+
<td width="50%"><img alt="A follow-up question answered inside the same lens, with file and line references" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/followup.png"></td>
|
|
72
|
+
<td width="50%"><img alt="A walkthrough block: worked example, a check question, the answer typed and the feedback" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/walk.png"></td>
|
|
73
|
+
</tr>
|
|
74
|
+
<tr>
|
|
75
|
+
<td align="center"><sub><b>Follow-up.</b> Ask more; the answer is added to the lens.</sub></td>
|
|
76
|
+
<td align="center"><sub><b>Walkthrough.</b> Answer the check, then the next block.</sub></td>
|
|
77
|
+
</tr>
|
|
78
|
+
</table>
|
|
79
|
+
|
|
80
|
+
### 2. Prove it
|
|
32
81
|
|
|
33
|
-
|
|
82
|
+
| | |
|
|
83
|
+
|---|---|
|
|
84
|
+
| **Quiz** | Free-text questions about behaviour and reasons, not names. Mark each answer *sure* or *guess*. The feedback names the line you got wrong. A wrong answer you were sure of is flagged first. |
|
|
85
|
+
| **Teach-back** | Explain the code in your own words. Graded 1-5: what is right, what is missing, what is wrong. |
|
|
86
|
+
| **Practice** | The key logic is cut out of a copy of your file. Write it back, with hints. |
|
|
87
|
+
| **Bug hunt** | Bugs are planted in a copy of the file. Find them and say why. |
|
|
88
|
+
| **Changes** | A split diff of two git refs, or of your uncommitted work. Every activity above can run on the diff. Good before you merge code you did not write. |
|
|
89
|
+
|
|
90
|
+
<p align="center">
|
|
91
|
+
<img alt="A graded quiz: score, the question, the answer marked sure, feedback that corrects two line numbers, and a good answer to compare with" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/quiz.png" width="860">
|
|
92
|
+
<br>
|
|
93
|
+
<sub><b>Quiz.</b> The answer was right, the line numbers were off, and the feedback says so.</sub>
|
|
94
|
+
</p>
|
|
95
|
+
|
|
96
|
+
<table>
|
|
97
|
+
<tr>
|
|
98
|
+
<td width="50%"><img alt="Practice: two holes cut out of fail() in queue.ts, the hole's intent on the right, and Check my work" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/practice.png"></td>
|
|
99
|
+
<td width="50%"><img alt="A graded bug hunt: one planted bug found with the reason, one missed, the buggy and real lines side by side" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/hunt.png"></td>
|
|
100
|
+
</tr>
|
|
101
|
+
<tr>
|
|
102
|
+
<td align="center"><sub><b>Practice.</b> Write the missing logic back, then check your work.</sub></td>
|
|
103
|
+
<td align="center"><sub><b>Bug hunt.</b> Found, missed and false alarms, each explained.</sub></td>
|
|
104
|
+
</tr>
|
|
105
|
+
</table>
|
|
106
|
+
|
|
107
|
+
<p align="center">
|
|
108
|
+
<img alt="The Changes page: file list, a split diff of an uncommitted change, and the activities that can run on it" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/changes.png" width="860">
|
|
109
|
+
<br>
|
|
110
|
+
<sub><b>Changes.</b> Read the diff, then lens it, quiz yourself on it or ask the tutor about it.</sub>
|
|
111
|
+
</p>
|
|
112
|
+
|
|
113
|
+
### 3. Keep it
|
|
34
114
|
|
|
35
115
|
| | |
|
|
36
116
|
|---|---|
|
|
37
|
-
| **
|
|
38
|
-
| **
|
|
39
|
-
| **
|
|
40
|
-
| **
|
|
41
|
-
|
|
117
|
+
| **Weak spots** | A wrong answer is saved as the belief behind it: "you think X, but Y". The next quiz aims at exactly those. A right answer clears one. |
|
|
118
|
+
| **Review cards** | Quiz misses become spaced-repetition cards (FSRS). Each card links back to the quiz or lens it came from. |
|
|
119
|
+
| **Today** | Each project opens on what to do now: cards due, weak spots, files that changed, the next stop on your path. |
|
|
120
|
+
| **Map, Paths, Progress** | See how the repo hangs together, take an ordered tour of it, and see what you have proved and what is fading. |
|
|
121
|
+
|
|
122
|
+
<table>
|
|
123
|
+
<tr>
|
|
124
|
+
<td width="50%"><img alt="Today: a suggested next step, 2 review cards due, two weak spots written as beliefs, and the next learning path stop" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/today.png"></td>
|
|
125
|
+
<td width="50%"><img alt="A review card made from a quiz miss: the question, what you wrote, the answer, and the Again, Hard, Good, Easy buttons" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/review.png"></td>
|
|
126
|
+
</tr>
|
|
127
|
+
<tr>
|
|
128
|
+
<td align="center"><sub><b>Today.</b> What to do now, in about 10 minutes.</sub></td>
|
|
129
|
+
<td align="center"><sub><b>Review.</b> Recall first, then reveal and rate.</sub></td>
|
|
130
|
+
</tr>
|
|
131
|
+
<tr>
|
|
132
|
+
<td width="50%"><img alt="The map: folders sized by their files, thicker arrows for more imports between them" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/map.png"></td>
|
|
133
|
+
<td width="50%"><img alt="Progress: folders rolled up with coverage bars, and cards for understood, fading, stale and seen" src="https://raw.githubusercontent.com/k-pulkit/cognitune/main/assets/screenshots/progress.png"></td>
|
|
134
|
+
</tr>
|
|
135
|
+
<tr>
|
|
136
|
+
<td align="center"><sub><b>Map.</b> Repos and folders, then files. Click a folder to go in.</sub></td>
|
|
137
|
+
<td align="center"><sub><b>Progress.</b> Per repo, folder and file: proved, fading or stale.</sub></td>
|
|
138
|
+
</tr>
|
|
139
|
+
</table>
|
|
140
|
+
|
|
141
|
+
## Use it when
|
|
142
|
+
|
|
143
|
+
- You joined a team and must find your way in a repo you did not write.
|
|
144
|
+
- An agent wrote the code and you must own it. Open **Changes** and quiz yourself on the diff.
|
|
145
|
+
- You come back to your own code after six months.
|
|
146
|
+
- You review a pull request and want to know what it does, not only that it looks fine.
|
|
147
|
+
|
|
148
|
+
## Why it works
|
|
149
|
+
|
|
150
|
+
Three findings from learning research decide how every page behaves.
|
|
151
|
+
|
|
152
|
+
| The finding | What cognitune does about it |
|
|
153
|
+
|---|---|
|
|
154
|
+
| **Recall beats re-reading** | Quizzes and teach-back are free text. You write the answer; you do not pick it from a list. |
|
|
155
|
+
| **Spacing beats cramming** | Misses come back as review cards on a schedule. Progress marks a file *fading* when you stop recalling it. |
|
|
156
|
+
| **Answer first, then read** | The tutor hints before it tells. A lens can ask for your own take first. A missed check asks you to try again. |
|
|
157
|
+
|
|
158
|
+
## Reference
|
|
42
159
|
|
|
43
|
-
|
|
160
|
+
<details>
|
|
161
|
+
<summary><b>All features</b></summary>
|
|
162
|
+
<br>
|
|
44
163
|
|
|
45
164
|
| | |
|
|
46
165
|
|---|---|
|
|
166
|
+
| **Lenses** | See code through one question: *Explain*, *Data flow*, *State over time*, *Failure modes*, *Contracts*, *Concepts*, *The change*, *Trace a run* (a debugger without running: line by line with the variables), *History* (why it is like this, from git), or your own. Tick **My take first** to write your own guess before the lens; it opens with where you differ. On a diff, that becomes **Predict first**. Ask follow-ups at the end; the answers are added to the same lens. A lens shows a banner when its code changes, with one-click refresh. |
|
|
167
|
+
| **Walkthrough** | The file in reading order (not file order), one block at a time, with a check question on each block before the next. Retry a block you missed. |
|
|
168
|
+
| **Tutor** | A Socratic chat over the files. It answers with a question or a hint first and gives a bit more each turn; ask it to just tell you any time. Line references jump the code pane. |
|
|
169
|
+
| **Map** | The import graph (TS/JS with tsconfig aliases, Python) at one scope: repos, then folders, then files. Thicker arrows carry more imports; click a folder to go in. A folder of 8 code files or fewer shows its files. |
|
|
170
|
+
| **Paths** | An ordered tour of the repo, 6-12 stops, each with the activity that fits. Stops tick off as you do them. |
|
|
171
|
+
| **Quizzes** | Free-text questions about behaviour and reasons, not names. Mark each answer *sure* or *guess*. Graded with feedback that names the line and a good answer to compare with. |
|
|
172
|
+
| **Teach-back** | Explain the code in your own words. Graded 1-5: what you got right, what you missed, what is wrong. |
|
|
173
|
+
| **Practice** | The key logic is cut out of a copy of your file (4 levels). Write it back, with hints, then "check my work". |
|
|
174
|
+
| **Bug hunt** | Realistic bugs are planted in a copy of the file. Click the lines you suspect and say why; see found, missed and false alarms. |
|
|
175
|
+
| **Changes** | Two git refs, or HEAD vs your working tree. Read the diff, then predict, lens, quiz, teach back or ask the tutor about the change itself. |
|
|
47
176
|
| **Review cards** | Spaced repetition (FSRS). Quiz misses become cards on their own; lens concepts and code lines can become cards in one click. |
|
|
48
|
-
| **Weak spots** | Wrong answers are saved as the belief behind them
|
|
49
|
-
| **Today** |
|
|
50
|
-
| **Progress** |
|
|
51
|
-
| **Library** | Everything made, searchable, plus a glossary
|
|
52
|
-
|
|
53
|
-
`Ctrl/Cmd+K` jumps to any page, file or project, or starts an activity. `?` lists all shortcuts.
|
|
177
|
+
| **Weak spots** | Wrong answers are saved as the belief behind them. Quiz one weak spot or all of them; a right answer clears one; dismiss one the grader got wrong. |
|
|
178
|
+
| **Today** | Due cards, weak spots, files that need a refresh, the next stop on your path, and one suggested 10-minute activity. |
|
|
179
|
+
| **Progress** | Rolled up per repo and folder, then per file: *seen*, *understood* (a check passed on the code as it is now), *fading* (no recall for a few weeks), *stale* (the code changed since). Pick a repo, drill into folders, search; table or heatmap. |
|
|
180
|
+
| **Library** | Everything made, searchable, plus a glossary and your margin notes. Export a lens or quiz as markdown, or a whole project as JSON. |
|
|
54
181
|
|
|
55
182
|
Context is what you pick: tick files in the tree, or add extra folders (docs, notes, design files) to a
|
|
56
|
-
project as context. The model
|
|
183
|
+
project as context. The model works from what you give it. Long jobs keep running if you leave the page;
|
|
184
|
+
the status bar says when they are ready. <kbd>Ctrl</kbd>/<kbd>Cmd</kbd>+<kbd>K</kbd> jumps anywhere; <kbd>?</kbd> lists shortcuts.
|
|
185
|
+
|
|
186
|
+
</details>
|
|
57
187
|
|
|
58
|
-
|
|
188
|
+
<details>
|
|
189
|
+
<summary><b>Model access</b>: Claude Code, Codex, Copilot or the Anthropic API</summary>
|
|
190
|
+
<br>
|
|
59
191
|
|
|
60
192
|
cognitune makes one model call per lens, quiz, grade, practice, tutor turn and so on (about 15 s to 2 min).
|
|
61
193
|
Replies are checked against a schema (one retry with the problems listed), and lens, walkthrough and path
|
|
@@ -73,9 +205,16 @@ stores a key**. Pick one in Settings; *Auto* takes the first one it finds, in th
|
|
|
73
205
|
Each CLI runs with the project folder as its working directory. Model per provider is optional
|
|
74
206
|
(empty = the CLI's default). `COGNITUNE_AGENT=fake` gives canned answers, to try the UI without a model.
|
|
75
207
|
|
|
76
|
-
|
|
208
|
+
Step-by-step setup: [SETUP.md](SETUP.md).
|
|
209
|
+
|
|
210
|
+
</details>
|
|
211
|
+
|
|
212
|
+
<details>
|
|
213
|
+
<summary><b>Your files are safe</b>: local only, read-only, bounded storage</summary>
|
|
214
|
+
<br>
|
|
77
215
|
|
|
78
216
|
- cognitune never writes to your folders. Practice works on a copy.
|
|
217
|
+
- The server binds to `127.0.0.1` only. There is no login: it is a local, one-person tool.
|
|
79
218
|
- Everything it makes lives in `~/.cognitune` (change with `COGNITUNE_HOME`), as plain JSON files, one
|
|
80
219
|
per item. Files, not SQLite: the data is small, you can read and back it up, and there is no native
|
|
81
220
|
module to build.
|
|
@@ -102,16 +241,16 @@ sizes and has *Clean up now*):
|
|
|
102
241
|
|
|
103
242
|
Cleanup runs at start-up and every 6 hours, and only ever inside the cognitune folder.
|
|
104
243
|
|
|
105
|
-
|
|
244
|
+
</details>
|
|
106
245
|
|
|
107
|
-
|
|
246
|
+
<details>
|
|
247
|
+
<summary><b>CLI and development</b></summary>
|
|
248
|
+
<br>
|
|
108
249
|
|
|
109
250
|
```
|
|
110
251
|
cognitune [folder] [--port 4711] [--host 127.0.0.1] [--no-open] [--demo]
|
|
111
252
|
```
|
|
112
253
|
|
|
113
|
-
## Develop
|
|
114
|
-
|
|
115
254
|
```bash
|
|
116
255
|
npm install
|
|
117
256
|
npm run dev # API on :4711 (tsx watch) + Vite on :5173 with hot reload
|
|
@@ -138,6 +277,10 @@ web/src/ React + Vite + Tailwind: pages/, components/, lib/
|
|
|
138
277
|
Stack: TypeScript everywhere. Hono on Node 20+, zod, ts-fsrs. React 18, React Router, TanStack Query,
|
|
139
278
|
Tailwind, Shiki (code), CodeMirror (practice editor), Mermaid (diagrams), d3-force (map).
|
|
140
279
|
|
|
280
|
+
</details>
|
|
281
|
+
|
|
141
282
|
## License
|
|
142
283
|
|
|
143
284
|
MIT
|
|
285
|
+
|
|
286
|
+
<p align="center"><sub>If cognitune helped you understand something, <a href="https://github.com/k-pulkit/cognitune/issues">tell me what you would change</a>.</sub></p>
|
package/SETUP.md
ADDED
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# Setup
|
|
2
|
+
|
|
3
|
+
## 1. Install
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
# No install — always runs the latest published version
|
|
7
|
+
npx cognitune ./my-repo
|
|
8
|
+
|
|
9
|
+
# Or install once, then just run `cognitune` from anywhere
|
|
10
|
+
npm install -g cognitune
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Needs Node >= 20 (`node -v` to check).
|
|
14
|
+
|
|
15
|
+
## 2. Pick a model backend
|
|
16
|
+
|
|
17
|
+
cognitune drives a coding CLI you already use — it never asks for or stores a key itself. It
|
|
18
|
+
picks the first one it finds, in this order, or you can pin one in Settings:
|
|
19
|
+
|
|
20
|
+
| Backend | One-time setup | Used as |
|
|
21
|
+
|---|---|---|
|
|
22
|
+
| Claude Code (default) | already logged into `claude` | `claude -p`, read-only tools |
|
|
23
|
+
| OpenAI Codex | `codex login` | `codex exec -`, sandboxed read-only |
|
|
24
|
+
| GitHub Copilot | Copilot login, or `export COPILOT_GITHUB_TOKEN=...` | `copilot -p -s`, read-only |
|
|
25
|
+
| Anthropic API directly | `export ANTHROPIC_API_KEY=...` | Messages API |
|
|
26
|
+
|
|
27
|
+
No model set up yet? Run with `--demo` first — canned answers, no login needed, good for a
|
|
28
|
+
first look at every page.
|
|
29
|
+
|
|
30
|
+
## 3. Run it on a project
|
|
31
|
+
|
|
32
|
+
Say your code lives under a workspace folder, like:
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
~/repos/
|
|
36
|
+
├── awesome-app/
|
|
37
|
+
│ ├── src/
|
|
38
|
+
│ └── package.json
|
|
39
|
+
└── another-project/
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Point cognitune at the one you want to understand:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
cd ~/repos/awesome-app
|
|
46
|
+
cognitune . # opens the browser automatically at http://127.0.0.1:4711
|
|
47
|
+
|
|
48
|
+
# or from anywhere, without cd'ing in first:
|
|
49
|
+
cognitune ~/repos/awesome-app
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
Your source files are only ever read, never written — practice and bug-hunt exercises work on
|
|
53
|
+
a throwaway copy.
|
|
54
|
+
|
|
55
|
+
### CLI flags
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
cognitune [folder] [--port 4711] [--host 127.0.0.1] [--no-open] [--demo]
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## 4. Shell shortcut
|
|
62
|
+
|
|
63
|
+
The CLI is already just `cognitune`, so the shortcut worth having is "run it on wherever I
|
|
64
|
+
currently am":
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
# ~/.bashrc (or ~/.zshrc)
|
|
68
|
+
alias cg='cognitune .'
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
cd ~/repos/awesome-app && cg
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## 5. Where your data lives
|
|
76
|
+
|
|
77
|
+
Everything cognitune makes is plain JSON files under one home folder — nothing is written
|
|
78
|
+
anywhere else on disk:
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
~/.cognitune/ (change with COGNITUNE_HOME)
|
|
82
|
+
├── settings.json model backend, storage limits
|
|
83
|
+
├── projects.json known projects (path, id, last opened)
|
|
84
|
+
├── cache/ model replies, reused on an unchanged file
|
|
85
|
+
├── archive/ forgotten projects (kept storage.archiveDays, default 30)
|
|
86
|
+
└── projects/
|
|
87
|
+
└── <project-id>/
|
|
88
|
+
├── lenses/ one file per lens you've made
|
|
89
|
+
├── quizzes/
|
|
90
|
+
├── practice/
|
|
91
|
+
├── teachbacks/
|
|
92
|
+
├── hunts/ bug-hunt exercises
|
|
93
|
+
├── walks/ walkthrough progress
|
|
94
|
+
├── threads/ tutor chat history
|
|
95
|
+
├── cards/ spaced-repetition review cards
|
|
96
|
+
├── misconceptions/ weak-spot beliefs behind wrong answers
|
|
97
|
+
├── notes/ margin notes pinned to lines
|
|
98
|
+
├── paths/ learning-path progress
|
|
99
|
+
├── contexts/ extra folders added to this project
|
|
100
|
+
└── archive/ this project's own deleted items
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Settings > Storage shows the size of each folder and has a one-click cleanup; nothing grows
|
|
104
|
+
without a cap (see the README's "Your files are safe" section for the exact limits).
|
|
105
|
+
|
|
106
|
+
## Troubleshooting
|
|
107
|
+
|
|
108
|
+
- **Port already in use** — `cognitune --port 4799` (or whatever's free).
|
|
109
|
+
- **"No model found"** — none of the four backends above are set up; use `--demo` to confirm
|
|
110
|
+
the UI itself works, then set one up.
|
|
111
|
+
- **Try it with no real project yet** — `cognitune --demo` opens a small bundled sample repo.
|