@@ -0,0 +1,67 @@
1+# Some notes from reading the code.
2+
3+> Context: I'm mostly a web engineer, with some backend experience with python, node and go.
4+
5+Some of my notes might be because of lack of Zig experience.
6+
7+## Notes
8+
9+`src/session.zig` - I was surprised to see such an awkward syntax format to creating/encoding json. Is this normal for zig? It's hard to read. Is there no `toJSON` type of thing? So we could then write that?
10+
11+`src/json.zig` - Similar to the session comment, I'm surprised at how cumbersome it is to deal with JSON.
12+
13+`src/main.zig` - has some headless concerns mixed into the entry point of the app. Worth considering extracting headless into `src/headless.zig`. Single concern files are easier to make a mental model around.
14+
15+`src/diff.zig` - We are rendering a whole header with index and divider, just to strip it in the TUI. Seems counter productive.
16+
17+`src/config.zig` - When we fixed the issue with the model specific api being at provider level for opencode in a recent commit, apparently we didn't do it for custom providers. Again, the models need to carry the metadata, the provider is just a label grouping.
18+
19+```jsonc
20+// Example custom provider **correct**
21+{
22+ "id": "local",
23+ "name": "Local",
24+ "models": [{
25+ "id": "qwen3-coder",
26+ "api": "openai-completions",
27+ "baseUrl": "http://127.0.0.1:11434/v1"
28+ }],
29+ "envKeys": ["LOCAL_API_KEY"],
30+ "headers": { "x-tenant": "mini" }
31+}
32+```
33+
34+I suggest the above structure, so we match the work we did for opencode. Basically the mistake here is assuming all providers use the same api for all models, which is not true. Not even for local envs.
35+Another note here is that again, I'm shocked at how cumbersome it is to read and validate JSON.
36+
37+
38+*Issues with pausing and canceling being delayed* - When the user presses either pause or cancel in the TUI, there is no immediate feedback, the visible result only happens at the next step. This is correct for pause, but incorrect for cancel. Cancel means stop right now, pause means pause at the next turn boundary. At some point the two got merged into both waiting for a turn boundary to act. And neither is properly displayed in the TUI status (no `pausing` state, canceling shouldn't exist, it …
39+**Comment on line 142 of `src/agent.zig`** - Completely wrong about cancellation and shouldn't be there. Pausing and steering land at turn boundaries, canceling is immediate!
40+`src/agent.zig` - cancel needs to be checked more often, between each phase. once and before tool calls is not responsive enough.
41+
42+`src/api.zig` and `src/config.zig` (possibly more) - I keep seeing the same helpers everywhere, `numField`, `stringField/strField`, `objField`. These exist in multiple files, it's ridiculous, it's an affront to the golden rule of less code. Just grepping the pattern shows the abuse of copy paste like approach.
43+
44+```bash
45+❯ rg "fn .+Field"
46+src/api.zig
47+308:pub fn optNumField(obj: std.json.ObjectMap, key: []const u8) ?u64 {
48+317:pub fn numField(obj: std.json.ObjectMap, key: []const u8) u64 {
49+322:pub fn stringField(obj: std.json.ObjectMap, key: []const u8) ?[]const u8 {
50+331:pub fn objField(obj: std.json.ObjectMap, key: []const u8) ?std.json.ObjectMap {
51+340:pub fn firstObjField(obj: std.json.ObjectMap, key: []const u8) ?std.json.ObjectMap {
52+365:pub fn boolField(obj: std.json.ObjectMap, key: []const u8, default: bool) bool {
53+
54+src/config.zig
55+77:fn strField(a: std.mem.Allocator, obj: std.json.ObjectMap, key: []const u8, path: []const u8) !?[]const u8 {
56+85:fn boolField(obj: std.json.ObjectMap, key: []const u8) ?bool {
57+```
58+
59+**Comments** - Being used randomly without thought, most of them re-state the code they near and add absolutely no value. As we saw above with canceling, they are introducing bugs and having a negative impact. We have a rule about comments, it's time to enforce it repo-wide, before these low quality comments cause more damage.
60+
61+`src/snapshot.zig` - the list of ignored paths is meant to come from the config, not this incomplete hardcoded list.
62+
63+`src/tui/editor.zig` - `pub fn render2` seriously? Where is render1? Naming is important and this is unacceptable.
64+
65+`src/tui/tui.zig` - This file has a lot of responsibilities, making it very big. Token estimation and commands at least, could be extracted.
66+
67+`src/tui/theme.zig` - will eventually grow too much, each theme we add will make that file worse. A refactor for later, since it's ok right now.