superwiki 0.1.7 → 0.1.8
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/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/README.md +143 -199
- package/bin/superwiki.mjs +46 -4
- package/commands/do.md +5 -0
- package/commands/summarize.md +5 -0
- package/package.json +1 -1
- package/skills/sw-config/assets/implementer.md +29 -17
- package/skills/sw-config/assets/planner.md +5 -5
- package/skills/sw-config/assets/reviewer.md +14 -7
- package/skills/sw-do/SKILL.md +54 -0
- package/skills/sw-implement/SKILL.md +48 -30
- package/skills/sw-init/SKILL.md +8 -2
- package/skills/sw-init/assets/agents-block.md +3 -1
- package/skills/sw-init/assets/sw.mjs +58 -2
- package/skills/sw-init/assets/templates/task.md +8 -1
- package/skills/sw-init/assets/viewer.html +74 -2
- package/skills/sw-init/scripts/init.mjs +96 -12
- package/skills/sw-lint/SKILL.md +1 -0
- package/skills/sw-plan/SKILL.md +29 -9
- package/skills/sw-run/SKILL.md +67 -52
- package/skills/sw-summarize/SKILL.md +103 -0
package/README.md
CHANGED
|
@@ -2,38 +2,22 @@
|
|
|
2
2
|
|
|
3
3
|
Agent skills that turn a project's `docs/` folder into an **LLM-maintained wiki and task tracker**. Your coding agent writes it and keeps it current; you read it as an **Obsidian vault** or in a built-in viewer. Works with **Claude Code, Codex CLI and GitHub Copilot CLI**.
|
|
4
4
|
|
|
5
|
-
**[Live demo](https://mhmtsrfglu.github.io/superwiki/)** · [Install](#install) · [
|
|
5
|
+
**[Live demo](https://mhmtsrfglu.github.io/superwiki/)** · [Install](#install) · [Use](#use) · [Design notes](DESIGN.md)
|
|
6
6
|
|
|
7
7
|
<picture>
|
|
8
8
|
<source media="(prefers-color-scheme: dark)" srcset="assets/viewer-waves-dark.png">
|
|
9
9
|
<img alt="The Superwiki viewer: task counts per area, filters, and the dependency board with one task's chain highlighted" src="assets/viewer-waves-light.png">
|
|
10
10
|
</picture>
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
npx superwiki install claude # or: codex, copilot, global, all
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
Then, in a project: `/sw-init`.
|
|
17
|
-
|
|
18
|
-
## Why
|
|
19
|
-
|
|
20
|
-
Superwiki follows the LLM Wiki pattern described by Andrej Karpathy: raw sources you curate, a wiki the agent owns, and a short schema that tells the agent how to maintain it. On top of that it adds what a software project needs: tasks with dependencies, plans, reviews, and a record of decisions and lessons.
|
|
21
|
-
|
|
22
|
-
It is built to be cheap for the agent:
|
|
12
|
+
## Quick start
|
|
23
13
|
|
|
24
|
-
|
|
25
|
-
- **Work in clean contexts.** Planning, implementing and reviewing run in subagents, each on the model you choose for it. The main session only keeps the task's status true, so it stays small.
|
|
26
|
-
- **Cost you can see.** `sw-stats` shows what a session used, per agent; `sw-doctor` shows what every session carries before it starts, and what can go.
|
|
27
|
-
|
|
28
|
-
Measured on a real project with 165 tasks, converted from a single markdown index:
|
|
14
|
+
Requires Node 18 or newer.
|
|
29
15
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
| Read to start one task | the index, then the task's section | one file, 2 KB at the median |
|
|
34
|
-
| Marking a task done | a status cell, plus a ✅ at every reference to it (median 12 places) | one frontmatter line |
|
|
16
|
+
```bash
|
|
17
|
+
npx superwiki install claude # or: codex, copilot, all
|
|
18
|
+
```
|
|
35
19
|
|
|
36
|
-
|
|
20
|
+
Start a new agent session in your project and run `/sw-init`. It sets up `docs/` and asks whether you want the task tracker. From then on, ask for what you need in plain words, or use a [command](#use).
|
|
37
21
|
|
|
38
22
|
## What you get
|
|
39
23
|
|
|
@@ -45,12 +29,22 @@ docs/
|
|
|
45
29
|
wiki/ pages the agent writes
|
|
46
30
|
tasks/ one file per task (optional)
|
|
47
31
|
plans/ one plan per task
|
|
48
|
-
viewer.html
|
|
32
|
+
viewer.html the task board and the wiki in a browser
|
|
49
33
|
```
|
|
50
34
|
|
|
51
|
-
`
|
|
35
|
+
`sw-init` also adds a short block of rules to `AGENTS.md`, so the agent maintains the vault in every session, with or without a command.
|
|
36
|
+
|
|
37
|
+
Everything is plain markdown. `docs/` keeps working as an Obsidian vault without Superwiki.
|
|
38
|
+
|
|
39
|
+
### The wiki
|
|
52
40
|
|
|
53
|
-
|
|
41
|
+
Superwiki follows the LLM Wiki pattern described by Andrej Karpathy: you curate raw sources, the agent owns the wiki, and a short set of rules tells it how to maintain it. Hand the agent an article, a transcript or your notes, and it files a summary and links it into the catalog.
|
|
42
|
+
|
|
43
|
+
### The tasks
|
|
44
|
+
|
|
45
|
+
A task is one file with a goal, a "Done when" list and its dependencies. The agent will not start a task whose dependencies are open, and a task is `done` only when every "Done when" item has been checked by a command.
|
|
46
|
+
|
|
47
|
+
`index.md` opens with the task list, so you can follow the work without the viewer:
|
|
54
48
|
|
|
55
49
|
```markdown
|
|
56
50
|
## Tasks
|
|
@@ -73,172 +67,124 @@ ready 9 · in progress 1 · blocked 18 · done 20
|
|
|
73
67
|
**Done (20)** [[B-01]] [[B-02]] [[B-03]] ...
|
|
74
68
|
```
|
|
75
69
|
|
|
76
|
-
|
|
70
|
+
The list is generated from the task files. Do not edit it by hand: change the task file, and the agent (or `/sw-board`) rewrites the list.
|
|
77
71
|
|
|
78
|
-
|
|
72
|
+
### Built to be cheap for the agent
|
|
79
73
|
|
|
80
|
-
|
|
74
|
+
- **Little to read.** One small index, one file per task, and a script that answers "what is ready?" or "what blocks this?" without the agent reading the vault.
|
|
75
|
+
- **Work in clean contexts.** Planning, implementing and reviewing run in subagents, each on the model you choose. The main session only tracks the task's status, so it stays small.
|
|
76
|
+
- **Cost you can see.** `sw-stats` shows what a session used, per agent; `sw-doctor` shows what every session carries before it starts.
|
|
81
77
|
|
|
82
|
-
|
|
83
|
-
npx superwiki install claude
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
This copies the skills into the folder your agent reads. Name one or more targets:
|
|
78
|
+
Measured on a real project with 165 tasks, converted from a single markdown index:
|
|
87
79
|
|
|
88
|
-
|
|
|
80
|
+
| | Before | After |
|
|
89
81
|
| --- | --- | --- |
|
|
90
|
-
|
|
|
91
|
-
|
|
|
92
|
-
|
|
|
93
|
-
|
|
94
|
-
|
|
82
|
+
| Read at the start of every session | 197 KB index | 7.7 KB index + 2.7 KB of rules |
|
|
83
|
+
| Read to start one task | the index, then the task's section | one file, 2 KB at the median |
|
|
84
|
+
| Marking a task done | a status cell, plus a ✅ at every reference to it (median 12 places) | one frontmatter line |
|
|
85
|
+
|
|
86
|
+
> Status: early. Not every skill has been run in every agent. [DESIGN.md](DESIGN.md#status) lists what has been proven and what has not.
|
|
87
|
+
|
|
88
|
+
## Install
|
|
95
89
|
|
|
96
90
|
```bash
|
|
97
|
-
npx superwiki install
|
|
98
|
-
npx superwiki install --project ~/code/my-app all # one project only, not your home folder
|
|
99
|
-
npx superwiki uninstall claude # remove
|
|
100
|
-
npx superwiki --help
|
|
91
|
+
npx superwiki install <target>...
|
|
101
92
|
```
|
|
102
93
|
|
|
94
|
+
| Target | Agent | Invoke a skill with |
|
|
95
|
+
| --- | --- | --- |
|
|
96
|
+
| `claude` | Claude Code | `/sw-init` |
|
|
97
|
+
| `codex` | Codex CLI | `$sw-init`, or "use the sw-init skill" |
|
|
98
|
+
| `copilot` | GitHub Copilot CLI | `/sw-init`, or "use the sw-init skill" |
|
|
99
|
+
| `all` | the three above | |
|
|
100
|
+
|
|
103
101
|
Start a new agent session after installing: a running session does not pick up new skills.
|
|
104
102
|
|
|
105
|
-
###
|
|
103
|
+
### Home folder or project
|
|
104
|
+
|
|
105
|
+
The installer asks where the skills should go:
|
|
106
106
|
|
|
107
|
-
|
|
107
|
+
- **Your home folder.** They serve every project on this machine. This is the usual choice.
|
|
108
|
+
- **This project**, the directory you run the command in. They are committed with the repository, so teammates and [cloud agents](#cloud-agents) have them too.
|
|
109
|
+
|
|
110
|
+
A flag answers in advance. Without a terminal (a script, CI) nothing is asked and the home folder is used.
|
|
108
111
|
|
|
109
112
|
```bash
|
|
110
|
-
|
|
111
|
-
|
|
113
|
+
npx superwiki install --global claude # home folder, no question
|
|
114
|
+
npx superwiki install --project . claude codex # this project, no question
|
|
112
115
|
```
|
|
113
116
|
|
|
114
|
-
|
|
117
|
+
| Target | In your home folder | In a project |
|
|
118
|
+
| --- | --- | --- |
|
|
119
|
+
| `claude` | `~/.claude/skills` | `.claude/skills` |
|
|
120
|
+
| `codex` | `~/.agents/skills` | `.agents/skills` |
|
|
121
|
+
| `copilot` | `~/.copilot/skills` | `.agents/skills` |
|
|
115
122
|
|
|
116
|
-
|
|
123
|
+
A skill folder of the same name that Superwiki did not install is kept and reported; `--force` replaces it.
|
|
117
124
|
|
|
118
|
-
|
|
125
|
+
### Cloud agents
|
|
119
126
|
|
|
120
|
-
|
|
127
|
+
A cloud agent (Claude Code on the web, Codex cloud, the GitHub Copilot coding agent) starts from a clone of your repository and never sees your home folder. It has the Superwiki skills only if they are in the repository.
|
|
121
128
|
|
|
122
|
-
|
|
129
|
+
1. Put the skills in the project. Either answer "this project" in the installer (`npx superwiki install --project . claude codex`), or, on a new vault, say yes when `/sw-init` asks whether to keep the skills in the repository.
|
|
130
|
+
2. Commit and push `.claude/skills` and `.agents/skills`.
|
|
123
131
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
132
|
+
| Cloud agent | Target | Reads the skills from |
|
|
133
|
+
| --- | --- | --- |
|
|
134
|
+
| Claude Code on the web | `claude` | `.claude/skills` |
|
|
135
|
+
| Codex cloud | `codex` | `.agents/skills` |
|
|
136
|
+
| GitHub Copilot coding agent | `copilot` | `.agents/skills` |
|
|
127
137
|
|
|
128
|
-
|
|
138
|
+
These folders are the ones each tool's documentation names. Superwiki has not yet been run in a cloud session.
|
|
129
139
|
|
|
130
|
-
|
|
131
|
-
- `sw-plan` enters plan mode when the session offers it.
|
|
132
|
-
- Agent files: `.claude/agents/sw-planner.md`, `sw-implementer.md` and `sw-reviewer.md`. They load when a session starts; in a session that began before they existed, the skills fall back to built-in agents with the same model.
|
|
140
|
+
### Other agents
|
|
133
141
|
|
|
134
|
-
|
|
142
|
+
Agents that load `SKILL.md` folders from `~/.agents/skills` get the skills with the target `global`. For an agent with its own skills folder (Cursor, Gemini CLI, OpenCode and others), copy the `skills/sw-*` folders from a clone into it. Neither has been tested. Expect these limits:
|
|
135
143
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
144
|
+
- planning, implementing and reviewing run in the main session, not in subagents;
|
|
145
|
+
- `sw-config` cannot set a model per role;
|
|
146
|
+
- `sw-stats` and `sw-doctor` do not work.
|
|
147
|
+
|
|
148
|
+
### With other skill sets
|
|
139
149
|
|
|
140
|
-
|
|
150
|
+
Superwiki works next to planning skill sets such as Superpowers.
|
|
141
151
|
|
|
142
|
-
-
|
|
143
|
-
-
|
|
152
|
+
- If another skill set answers a bare `/sw-...` command first, name the skill in a sentence: "use the sw-implement skill for T-02".
|
|
153
|
+
- Folders other tools create under `docs/` are left alone. Superwiki only reads and writes `index.md`, `log.md`, `raw/`, `wiki/`, `tasks/` and `plans/`.
|
|
144
154
|
|
|
145
|
-
|
|
155
|
+
### Update
|
|
146
156
|
|
|
147
157
|
```bash
|
|
148
|
-
npx superwiki install
|
|
158
|
+
npx superwiki@latest install claude # the same command you installed with
|
|
149
159
|
```
|
|
150
160
|
|
|
151
|
-
|
|
161
|
+
Then run `/sw-init` again in each project. It updates the script, the templates and the viewer in `docs/`, and the skills kept in the repository if you chose that, and keeps your content. Commit the result.
|
|
152
162
|
|
|
153
|
-
-
|
|
154
|
-
- A skill cannot switch Copilot into plan mode. Start with `copilot --mode plan` or `/plan` if you want it.
|
|
155
|
-
- Agent files: `.github/agents/sw-planner.agent.md`, `sw-implementer.agent.md` and `sw-reviewer.agent.md`, dispatched with the `task` tool. Whether Copilot honours the `model:` field of those files has not been checked.
|
|
163
|
+
If your session loaded `sw-init` from the project's own copy of the skills, update that copy with the installer instead: `npx superwiki@latest install --project . claude`.
|
|
156
164
|
|
|
157
|
-
|
|
165
|
+
### Uninstall
|
|
158
166
|
|
|
159
167
|
```bash
|
|
160
|
-
npx superwiki
|
|
168
|
+
npx superwiki uninstall all # from your home folder
|
|
169
|
+
npx superwiki uninstall --project . all # from a project
|
|
161
170
|
```
|
|
162
171
|
|
|
163
|
-
|
|
172
|
+
Only the skills are removed. `docs/` stays.
|
|
164
173
|
|
|
165
|
-
|
|
166
|
-
- `sw-config` writes agent files only for `claude`, `codex` and `copilot`, so a per-role model cannot be set;
|
|
167
|
-
- `sw-stats` and `sw-doctor` read the session records of those three tools only.
|
|
168
|
-
|
|
169
|
-
Everything else (the vault, the CLI, the viewer, ingest, lint, explain, triage) depends only on Node and on the agent following the skill text.
|
|
170
|
-
|
|
171
|
-
### With other skill sets
|
|
172
|
-
|
|
173
|
-
Superwiki works next to planning skill sets such as Superpowers. Two things to know:
|
|
174
|
-
|
|
175
|
-
- Their bootstrap may claim a bare `/sw-...` prompt before Superwiki's skill loads. Naming the skill in a sentence ("use the sw-implement skill for T-02") avoids that.
|
|
176
|
-
- Folders they create under `docs/` are left alone: Superwiki only reads and writes `index.md`, `log.md`, `raw/`, `wiki/`, `tasks/` and `plans/`.
|
|
174
|
+
### From a clone
|
|
177
175
|
|
|
178
|
-
|
|
176
|
+
To read the code first, or to change it:
|
|
179
177
|
|
|
180
178
|
```bash
|
|
181
|
-
|
|
182
|
-
npx superwiki
|
|
179
|
+
git clone https://github.com/mhmtsrfglu/superwiki ~/.superwiki
|
|
180
|
+
~/.superwiki/install.sh claude # same targets and options as npx superwiki install
|
|
183
181
|
```
|
|
184
182
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
A project's `docs/` folder is plain markdown and keeps working as an Obsidian vault without Superwiki.
|
|
183
|
+
`install.sh` links the skills instead of copying them, so `git pull` updates every agent. Links only work on your machine: for a project install add `--copy`. `--uninstall` removes.
|
|
188
184
|
|
|
189
185
|
## Use
|
|
190
186
|
|
|
191
|
-
|
|
192
|
-
| --- | --- |
|
|
193
|
-
| `sw-init` | set up `docs/` in the current project, or upgrade it |
|
|
194
|
-
| `sw-migrate` | convert an existing table-based task index, on a git branch of its own |
|
|
195
|
-
| `sw-ingest` | file a source into the wiki |
|
|
196
|
-
| `sw-plan` | plan a task with the planner subagent and get your approval |
|
|
197
|
-
| `sw-implement` | run a task with the implementer subagent, have it reviewed if the task asks for that, and record the result |
|
|
198
|
-
| `sw-run` | work through several tasks in a row, unattended: plan, implement, review and record each, and stop when one needs you |
|
|
199
|
-
| `sw-explain` | explain a task: what, why, dependencies, what it unblocks |
|
|
200
|
-
| `sw-triage` | for a problem: seen before? lessons, likely causes |
|
|
201
|
-
| `sw-board` | refresh the task list in `index.md` from the task files |
|
|
202
|
-
| `sw-lint` | structural checks by script, semantic review on request |
|
|
203
|
-
| `sw-visualize` | open the viewer |
|
|
204
|
-
| `sw-stats` | what the current session has cost: tokens, context, steps and tool calls, per agent |
|
|
205
|
-
| `sw-doctor` | what a session carries before any work, and what to remove to make every step cheaper |
|
|
206
|
-
| `sw-config` | the model each tool uses for planning, implementing and reviewing; task areas |
|
|
207
|
-
|
|
208
|
-
### Examples
|
|
209
|
-
|
|
210
|
-
Shown as typed in Claude Code. In Codex, write `$sw-plan` instead of `/sw-plan`. Task ids are an area prefix and a number, such as `P-15`.
|
|
211
|
-
|
|
212
|
-
```text
|
|
213
|
-
/sw-init set up the vault; asks whether you want tasks
|
|
214
|
-
/sw-migrate convert the task tables this project already has
|
|
215
|
-
|
|
216
|
-
/sw-plan what can start now? pick one and plan it
|
|
217
|
-
/sw-plan P-15 plan task P-15 (a small task is sent straight to sw-implement)
|
|
218
|
-
/sw-plan add CSV export to the sources page
|
|
219
|
-
new work: creates the task, then plans it
|
|
220
|
-
|
|
221
|
-
/sw-implement P-15 run P-15; refuses if a dependency is not done
|
|
222
|
-
/sw-implement continue what is in progress, or pick a ready task
|
|
223
|
-
/sw-run the backend tasks, commit after each
|
|
224
|
-
one task after another without asking at each step;
|
|
225
|
-
stops when a task needs you, and reports what it decided
|
|
226
|
-
|
|
227
|
-
/sw-explain M-06 what M-06 is, why it exists, what it waits on and unblocks
|
|
228
|
-
/sw-triage photo uploads hang at 100% on mobile since yesterday
|
|
229
|
-
has this happened before? lessons and likely causes
|
|
230
|
-
/sw-ingest ~/Downloads/interview-notes.md
|
|
231
|
-
file a source and summarise it into the wiki
|
|
232
|
-
|
|
233
|
-
/sw-config plan with opus, implement with sonnet, review with opus
|
|
234
|
-
/sw-board refresh the task list in index.md after you edited tasks by hand
|
|
235
|
-
/sw-lint check links, frontmatter and task dependencies
|
|
236
|
-
/sw-visualize open the task board and the wiki in the browser
|
|
237
|
-
/sw-stats what this session has cost so far, per agent
|
|
238
|
-
/sw-doctor what fills the context before any work, and what can go
|
|
239
|
-
```
|
|
240
|
-
|
|
241
|
-
You do not have to type a command. The rules `sw-init` adds to `AGENTS.md` tell the agent which skill fits, so a plain request should reach the same skill:
|
|
187
|
+
Type a command, or just ask. The rules in `AGENTS.md` tell the agent which skill fits, so these reach the same skills:
|
|
242
188
|
|
|
243
189
|
```text
|
|
244
190
|
What should I work on next?
|
|
@@ -247,14 +193,52 @@ Why does M-06 exist, and what is it blocked by?
|
|
|
247
193
|
Users get the magic-link email twice. Have we seen this before?
|
|
248
194
|
```
|
|
249
195
|
|
|
250
|
-
|
|
196
|
+
Commands are shown as typed in Claude Code; in Codex write `$sw-plan` instead of `/sw-plan`. Task ids are an area prefix and a number, such as `P-15`.
|
|
251
197
|
|
|
252
|
-
###
|
|
198
|
+
### Set up
|
|
253
199
|
|
|
254
|
-
|
|
200
|
+
| Command | What it does |
|
|
201
|
+
| --- | --- |
|
|
202
|
+
| `/sw-init` | set up `docs/` in the current project, or upgrade it |
|
|
203
|
+
| `/sw-migrate` | convert task tables the project already has, on a git branch of its own |
|
|
204
|
+
| `/sw-config plan with opus, implement with sonnet` | choose the model for planning, implementing and reviewing; add task areas |
|
|
205
|
+
|
|
206
|
+
### Work on tasks
|
|
207
|
+
|
|
208
|
+
| Command | What it does |
|
|
209
|
+
| --- | --- |
|
|
210
|
+
| `/sw-do P-15` | take one task from todo to done. A small task goes straight to work; a large one gets a plan you approve first. Without an id, it offers the tasks that can start |
|
|
211
|
+
| `/sw-run the backend tasks` | work through several tasks in a row without asking at each step. It stops when a task needs you and reports every decision it made in your place |
|
|
212
|
+
| `/sw-explain M-06` | what a task is, why it exists, what it waits on and what it unblocks |
|
|
213
|
+
| `/sw-triage uploads hang at 100% since yesterday` | for a problem: has it happened before, what was learned, likely causes |
|
|
214
|
+
|
|
215
|
+
`sw-do` runs three steps that you can also run one at a time:
|
|
216
|
+
|
|
217
|
+
| Command | What it does |
|
|
218
|
+
| --- | --- |
|
|
219
|
+
| `/sw-plan P-15` | have a plan written and approve it. `/sw-plan add CSV export` creates the task first |
|
|
220
|
+
| `/sw-implement P-15` | build the task, have it reviewed if the task asks for a review, and record the result |
|
|
221
|
+
| `/sw-summarize P-15` | check each "Done when" item with a command and write the evidence into the task file |
|
|
222
|
+
|
|
223
|
+
### Keep the wiki
|
|
224
|
+
|
|
225
|
+
| Command | What it does |
|
|
226
|
+
| --- | --- |
|
|
227
|
+
| `/sw-ingest ~/Downloads/interview-notes.md` | file a source and summarize it into the wiki |
|
|
228
|
+
| `/sw-lint` | check links, frontmatter and task dependencies |
|
|
229
|
+
| `/sw-board` | rewrite the task list in `index.md` after you edited task files by hand |
|
|
230
|
+
| `/sw-visualize` | open the task board and the wiki in the browser |
|
|
231
|
+
|
|
232
|
+
### Watch the cost
|
|
233
|
+
|
|
234
|
+
| Command | What it does |
|
|
235
|
+
| --- | --- |
|
|
236
|
+
| `/sw-stats` | what the current session has used, per agent |
|
|
237
|
+
| `/sw-doctor` | what a session carries before any work, and what can be switched off for this project. It asks before changing anything |
|
|
238
|
+
|
|
239
|
+
`sw-stats` prints one row for the main session and one for each subagent. This is a real task, planned, implemented and reviewed in 37 minutes:
|
|
255
240
|
|
|
256
241
|
```text
|
|
257
|
-
session claude fe4cbd6c-8abf-4db6-9755-469dc7321dc7 2026-10-05 10:27 to 11:04, 37 min
|
|
258
242
|
agent model steps first peak sent cached output tools min
|
|
259
243
|
main claude-opus-5-5 27 79k 126k 2.8M 96% 18k 23 37
|
|
260
244
|
sw-planner claude-opus-5-5 31 59k 154k 3.5M 96% 8k 32 6
|
|
@@ -263,68 +247,28 @@ sw-reviewer claude-opus-5-5 23 60k 137k 2.4M 89% 372
|
|
|
263
247
|
total 149 - - 20.9M 95% 43k 155
|
|
264
248
|
```
|
|
265
249
|
|
|
266
|
-
`first` and `peak` are the tokens sent with one request
|
|
267
|
-
|
|
268
|
-
### What a session starts with
|
|
269
|
-
|
|
270
|
-
Every agent above began at 59k to 79k tokens before it had read anything, and paid for that on each of its steps. `sw-doctor` shows what that start is made of, from the same session record, and proposes what to switch off for this project. The same session:
|
|
271
|
-
|
|
272
|
-
```text
|
|
273
|
-
context at session start claude fe4cbd6c-8abf-4db6-9755-469dc7321dc7
|
|
274
|
-
first request: 79k tokens
|
|
275
|
-
part size holds
|
|
276
|
-
rule and memory files 30 KB memory/MEMORY.md 18 KB, my-app/AGENTS.md 11 KB, ...
|
|
277
|
-
skill list 29 KB 213: marketing-skills 41, (none) 37, claude-seo 25, claude-ads 23, +11 more
|
|
278
|
-
tool names (loaded on demand) 17 KB 381: claude_ai_higgsfield 116, claude_ai_meta_ads 98, +9 more
|
|
279
|
-
agent list 14 KB 46: claude-seo 18, (none) 12, claude-ads 10, +4 more
|
|
280
|
-
MCP server instructions 8.3 KB claude.ai higgsfield 2.0 KB, notebooklm 2.0 KB, ...
|
|
281
|
-
session-start hooks 3.3 KB
|
|
282
|
-
```
|
|
283
|
-
|
|
284
|
-
Here most of the skills, agents and tools came from advertising and SEO plugins that this project never uses. The skill proposes changes and asks before making any; it touches project-local settings only, and never uninstalls a plugin or deletes a memory. Sizes are characters of text: a skill cannot run your agent's own context command (`/context` in Claude Code and Copilot CLI, `/status` in Codex), which shows the same in tokens.
|
|
250
|
+
`first` and `peak` are the tokens sent with one request; `sent` is that, summed over every step. Each step sends the whole context again, which is why Superwiki keeps contexts small.
|
|
285
251
|
|
|
286
252
|
### The CLI
|
|
287
253
|
|
|
288
|
-
The skills call a small script
|
|
254
|
+
The skills call a small script in your project. You can run it yourself, from the project root:
|
|
289
255
|
|
|
290
256
|
```bash
|
|
291
257
|
node docs/.sw/sw.mjs status # counts per area
|
|
292
258
|
node docs/.sw/sw.mjs ready # tasks that can start now
|
|
293
|
-
node docs/.sw/sw.mjs check P-15 # can it start
|
|
294
|
-
node docs/.sw/sw.mjs explain P-15 # dependencies, what it unblocks, plan
|
|
259
|
+
node docs/.sw/sw.mjs check P-15 # can it start, can it finish, what is open
|
|
260
|
+
node docs/.sw/sw.mjs explain P-15 # dependencies, what it unblocks, its plan
|
|
295
261
|
node docs/.sw/sw.mjs search sync timeout # where something is mentioned
|
|
296
|
-
node docs/.sw/sw.mjs
|
|
297
|
-
node docs/.sw/sw.mjs board # rewrite the task list in index.md
|
|
298
|
-
node docs/.sw/sw.mjs
|
|
299
|
-
node docs/.sw/sw.mjs stats # tokens, context and steps of the agent session here
|
|
300
|
-
node docs/.sw/sw.mjs doctor # what that session carried before it read anything
|
|
301
|
-
node docs/.sw/sw.mjs serve --open # the viewer, reading files live
|
|
302
|
-
node docs/.sw/sw.mjs snapshot # or: freeze the vault into docs/viewer.html, no server
|
|
303
|
-
```
|
|
304
|
-
|
|
305
|
-
## Develop
|
|
306
|
-
|
|
307
|
-
```bash
|
|
308
|
-
npm test # builds skills/sw-init/assets/sw.mjs and viewer.html, then runs the tests
|
|
262
|
+
node docs/.sw/sw.mjs lint # broken links, bad frontmatter, dependency errors
|
|
263
|
+
node docs/.sw/sw.mjs board # rewrite the task list in index.md
|
|
264
|
+
node docs/.sw/sw.mjs serve --open # the viewer
|
|
309
265
|
```
|
|
310
266
|
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
| File | What it is |
|
|
314
|
-
| --- | --- |
|
|
315
|
-
| `src/core.js` | the vault model, derived task state, lint and search; shared by the CLI and the viewer |
|
|
316
|
-
| `src/board.js` | the task list in `index.md` |
|
|
317
|
-
| `src/sessions.js` | finds the record an agent keeps of a session |
|
|
318
|
-
| `src/stats.js` | reduces a session record to cost per agent |
|
|
319
|
-
| `src/doctor.js` | reduces a session record to what the session started with |
|
|
320
|
-
| `src/cli.js` | the commands |
|
|
321
|
-
| `src/viewer.html` | the viewer |
|
|
322
|
-
|
|
323
|
-
`scripts/build.mjs` bundles them into `skills/sw-init/assets/sw.mjs` and `viewer.html`. Those two files are generated: do not edit them.
|
|
267
|
+
`node docs/.sw/sw.mjs` without a command lists the rest. A filled-in example vault is in [examples/demo/docs](examples/demo/docs).
|
|
324
268
|
|
|
325
|
-
|
|
269
|
+
## Contributing
|
|
326
270
|
|
|
327
|
-
|
|
271
|
+
How to build, test and release is in [CONTRIBUTING.md](CONTRIBUTING.md). Why Superwiki works the way it does is in [DESIGN.md](DESIGN.md).
|
|
328
272
|
|
|
329
273
|
## License
|
|
330
274
|
|
package/bin/superwiki.mjs
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
// Installs the Superwiki skills into the folder each coding agent reads
|
|
2
|
+
// Installs the Superwiki skills into the folder each coding agent reads: in the home folder, for
|
|
3
|
+
// every project on this machine, or in one project, where they are committed with the repository.
|
|
3
4
|
// Run from npm (`npx superwiki install claude`) it copies them; `--link` links them to this
|
|
4
5
|
// checkout instead, which is what install.sh does for a git clone.
|
|
5
6
|
import { existsSync, lstatSync, readlinkSync, realpathSync, mkdirSync, readdirSync, rmSync, cpSync, symlinkSync, writeFileSync, readFileSync, statSync } from 'node:fs';
|
|
6
|
-
import { dirname, join
|
|
7
|
+
import { dirname, join } from 'node:path';
|
|
7
8
|
import { homedir } from 'node:os';
|
|
9
|
+
import { createInterface } from 'node:readline/promises';
|
|
8
10
|
import { fileURLToPath } from 'node:url';
|
|
9
11
|
|
|
10
12
|
const root = join(dirname(fileURLToPath(import.meta.url)), '..');
|
|
@@ -24,17 +26,23 @@ Targets:
|
|
|
24
26
|
all claude + codex + copilot
|
|
25
27
|
|
|
26
28
|
Options:
|
|
27
|
-
--
|
|
28
|
-
|
|
29
|
+
--global use your home folder: the skills serve every project on this machine
|
|
30
|
+
--project <dir> use that project instead (.claude/skills for claude, .agents/skills for the
|
|
31
|
+
others); committed with the repository, the skills reach cloud agents too
|
|
29
32
|
--link link the skills to this copy of Superwiki instead of copying them
|
|
30
33
|
(for a git clone: updating the clone then updates every agent)
|
|
31
34
|
--force replace or remove a skill folder that Superwiki did not install
|
|
32
35
|
-v, --version print the version
|
|
33
36
|
-h, --help show this help
|
|
34
37
|
|
|
38
|
+
install asks "home folder or this project" when it runs in a terminal and neither --global nor
|
|
39
|
+
--project is given; outside a terminal it uses the home folder. uninstall never asks: it works
|
|
40
|
+
on the home folder unless --project is given.
|
|
41
|
+
|
|
35
42
|
Examples:
|
|
36
43
|
npx superwiki install claude
|
|
37
44
|
npx superwiki install claude codex
|
|
45
|
+
npx superwiki install --global all
|
|
38
46
|
npx superwiki install --project ~/code/my-app all
|
|
39
47
|
npx superwiki uninstall copilot
|
|
40
48
|
|
|
@@ -49,18 +57,21 @@ if (argv.includes('-v') || argv.includes('--version')) { console.log(JSON.parse(
|
|
|
49
57
|
const command = argv[0];
|
|
50
58
|
if (command !== 'install' && command !== 'uninstall') fail(`unknown command: ${command}\n\n${HELP}`);
|
|
51
59
|
let project = '';
|
|
60
|
+
let global = false;
|
|
52
61
|
let link = false;
|
|
53
62
|
let force = false;
|
|
54
63
|
const targets = [];
|
|
55
64
|
for (let i = 1; i < argv.length; i++) {
|
|
56
65
|
const a = argv[i];
|
|
57
66
|
if (a === '--project') { project = argv[++i] || fail('--project needs a folder'); }
|
|
67
|
+
else if (a === '--global') global = true;
|
|
58
68
|
else if (a === '--link') link = true;
|
|
59
69
|
else if (a === '--force') force = true;
|
|
60
70
|
else if (a === 'all') targets.push('claude', 'codex', 'copilot');
|
|
61
71
|
else if (TARGETS.includes(a)) targets.push(a);
|
|
62
72
|
else fail(`unknown argument: ${a}\n\n${HELP}`);
|
|
63
73
|
}
|
|
74
|
+
if (global && project) fail('--global and --project exclude each other: name one place');
|
|
64
75
|
if (!targets.length) fail(`name at least one target: ${TARGETS.join(', ')}, all`);
|
|
65
76
|
if (!existsSync(skillsDir)) fail(`no skills/ folder in ${root}`, 1);
|
|
66
77
|
if (project) {
|
|
@@ -68,6 +79,37 @@ if (project) {
|
|
|
68
79
|
project = realpathSync(project);
|
|
69
80
|
}
|
|
70
81
|
|
|
82
|
+
// The one question of an install. True means the current directory, as a project. Input that
|
|
83
|
+
// ends before a valid answer counts as the default, the home folder.
|
|
84
|
+
async function askForProject(cwd) {
|
|
85
|
+
const rl = createInterface({ input: process.stdin, output: process.stdout });
|
|
86
|
+
// A last line and the end of input can arrive together; the line has to win, so the end waits a turn.
|
|
87
|
+
const ended = new Promise(done => rl.once('close', () => setImmediate(done, null)));
|
|
88
|
+
console.log(`Where should the skills go?
|
|
89
|
+
1) home folder: every project on this machine
|
|
90
|
+
2) this project (${cwd}): committed with the repository, so cloud agents get them`);
|
|
91
|
+
try {
|
|
92
|
+
for (;;) {
|
|
93
|
+
const answer = await Promise.race([rl.question('Choice [1]: ').catch(() => null), ended]);
|
|
94
|
+
if (answer === null) return false;
|
|
95
|
+
const choice = answer.trim();
|
|
96
|
+
if (choice === '' || choice === '1') return false;
|
|
97
|
+
if (choice === '2') return true;
|
|
98
|
+
console.log('Answer 1 or 2.');
|
|
99
|
+
}
|
|
100
|
+
} finally {
|
|
101
|
+
rl.close();
|
|
102
|
+
}
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
if (command === 'install' && !project && !global && process.stdin.isTTY) {
|
|
106
|
+
const cwd = realpathSync(process.cwd());
|
|
107
|
+
if (await askForProject(cwd)) project = cwd;
|
|
108
|
+
}
|
|
109
|
+
if (command === 'install' && link && project) {
|
|
110
|
+
console.error('warning: --link into a project: the links point into this machine and will not work in a clone or a cloud session; leave --link out to copy');
|
|
111
|
+
}
|
|
112
|
+
|
|
71
113
|
const destFor = t => (project
|
|
72
114
|
? join(project, t === 'claude' ? '.claude/skills' : '.agents/skills')
|
|
73
115
|
: join(homedir(), t === 'claude' ? '.claude/skills' : t === 'copilot' ? '.copilot/skills' : '.agents/skills'));
|
package/commands/do.md
ADDED
package/package.json
CHANGED