codewalk 0.1.8 → 0.1.10
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 +136 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
> Note: this package is in an early alpha. Any bugs can be submitted as GitHub issues
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
A toolkit for tracking and visualizing AI-assisted code changes with structured reasoning, known as **_logical changes_**.
|
|
6
|
+
|
|
7
|
+
## What is a "Logical Change"?
|
|
8
|
+
|
|
9
|
+
A logical change is a group of code modifications that serve a single purpose. A single commit often contains multiple logical changes - for example, adding a feature might involve:
|
|
10
|
+
|
|
11
|
+
- Adding a new component (logical change #1)
|
|
12
|
+
- Updating the router to include it (logical change #2)
|
|
13
|
+
- Adding styles (logical change #3)
|
|
14
|
+
|
|
15
|
+
Traditional diffs show these as a flat list of file changes, making it hard to understand which parts go together. Codewalk groups related hunks across files by their shared reasoning, so reviewers see changes organized by *intent* rather than by file path.
|
|
16
|
+
|
|
17
|
+
## Visualizer
|
|
18
|
+
|
|
19
|
+
Interactive TUI for viewing logical changes on the current branch:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npx codewalk visualize # or viz
|
|
23
|
+
```
|
|
24
|
+
or
|
|
25
|
+
```bash
|
|
26
|
+
bunx codewalk visualize # or viz
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
Groups all changes by their reasoning text across commits, sorted chronologically (oldest first). Shows the current branch, tracking directory, and actual diff hunks.
|
|
32
|
+
|
|
33
|
+
## Claude Code Plugin
|
|
34
|
+
|
|
35
|
+
### Installation
|
|
36
|
+
|
|
37
|
+
```
|
|
38
|
+
/plugin marketplace add lukecrum/codewalk
|
|
39
|
+
```
|
|
40
|
+
```
|
|
41
|
+
/plugin install codewalk
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Once installed, Claude will automatically create tracking files for every commit via a stop hook that enforces tracking before session exit.
|
|
45
|
+
|
|
46
|
+
### Configuration
|
|
47
|
+
|
|
48
|
+
Run the interactive configuration wizard:
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
/codewalk-config
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Or manually create `.claude/codewalk.local.md`:
|
|
55
|
+
|
|
56
|
+
```yaml
|
|
57
|
+
---
|
|
58
|
+
storage: global
|
|
59
|
+
globalDir: ~/.codewalk
|
|
60
|
+
---
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Settings
|
|
64
|
+
|
|
65
|
+
| Setting | Values | Default | Description |
|
|
66
|
+
|---------|--------|---------|-------------|
|
|
67
|
+
| `storage` | `local`, `global` | `global` | Where to store tracking files |
|
|
68
|
+
| `globalDir` | path | `~/.codewalk` | Directory for global storage (supports `~`) |
|
|
69
|
+
|
|
70
|
+
### Storage Modes
|
|
71
|
+
|
|
72
|
+
**Global storage** (`storage: global`) - Default:
|
|
73
|
+
- Tracking files stored in `<~ or path>/.codewalk/<repo-name>/<hash>.json`
|
|
74
|
+
- Best for: Personal tracking without adding files to the repo
|
|
75
|
+
|
|
76
|
+
**Local storage** (`storage: local`):
|
|
77
|
+
- Tracking files stored in `.codewalk/<hash>.json` in the project
|
|
78
|
+
- Best for: Projects where team visibility of tracking data is important
|
|
79
|
+
|
|
80
|
+
## Appendix A - Tracking files
|
|
81
|
+
|
|
82
|
+
### Schema
|
|
83
|
+
|
|
84
|
+
```typescript
|
|
85
|
+
type Changeset = {
|
|
86
|
+
// Git commit SHA this changeset describes
|
|
87
|
+
commit: string;
|
|
88
|
+
|
|
89
|
+
// List of logical changes, each with its own reasoning
|
|
90
|
+
changes: Change[];
|
|
91
|
+
};
|
|
92
|
+
|
|
93
|
+
type Change = {
|
|
94
|
+
// Human-readable explanation of why this change was made.
|
|
95
|
+
// Should explain the intent, not just describe what changed.
|
|
96
|
+
reasoning: string;
|
|
97
|
+
|
|
98
|
+
// Files affected by this logical change
|
|
99
|
+
files: FileChange[];
|
|
100
|
+
};
|
|
101
|
+
|
|
102
|
+
type FileChange = {
|
|
103
|
+
// Path to the file, relative to repo root
|
|
104
|
+
path: string;
|
|
105
|
+
|
|
106
|
+
// Which hunks from `git show <commit>` belong to this change.
|
|
107
|
+
// 1-indexed, in order of appearance in the diff.
|
|
108
|
+
hunks: number[];
|
|
109
|
+
};
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### Example
|
|
113
|
+
```json
|
|
114
|
+
{
|
|
115
|
+
"commit": "a1b2c3d",
|
|
116
|
+
"changes": [
|
|
117
|
+
{
|
|
118
|
+
"reasoning": "Add dark mode toggle that persists to localStorage",
|
|
119
|
+
"files": [
|
|
120
|
+
{ "path": "src/App.tsx", "hunks": [1, 2] },
|
|
121
|
+
{ "path": "src/styles.css", "hunks": [1] }
|
|
122
|
+
]
|
|
123
|
+
}
|
|
124
|
+
]
|
|
125
|
+
}
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## Appendix B - Visualizer controls
|
|
129
|
+
|
|
130
|
+
| Key | Action |
|
|
131
|
+
|-----|--------|
|
|
132
|
+
| `↑`/`↓` or `j`/`k` | Navigate |
|
|
133
|
+
| `Enter` or `Space` | Expand/collapse |
|
|
134
|
+
| `g`/`G` | Jump to top/bottom |
|
|
135
|
+
| `q` | Quit |
|
|
136
|
+
| Mouse scroll/click | Supported |
|