@kelceyp/caw 1.0.39 → 1.0.41

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 (3) hide show
  1. package/README.md +123 -22
  2. package/dist/caw.js +34 -35
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -2,6 +2,17 @@
2
2
 
3
3
  CAW helps users build software **sustainably** using AI by providing agents with **C**ontext and **A**gentic **W**orkflows (CAW). CAW is free to download and runs locally as a unified web and MCP server. It provides document management, templates, stories, search and acts as the orchestration layer for your AI development tools.
4
4
 
5
+ ![CAW overview](https://athenadesign.com.au/caw/animation.svg)
6
+
7
+ ## Platform support
8
+
9
+ | Platform | Status |
10
+ |---|-----------------|
11
+ | macOS — Apple Silicon | ✅ Supported |
12
+ | macOS — Intel | ✅ Supported |
13
+ | Linux | 🛠️ Coming soon |
14
+ | Windows | 🛠️ Planned |
15
+
5
16
  ## Quick Start
6
17
 
7
18
  ```bash
@@ -10,8 +21,6 @@ caw start
10
21
  ```
11
22
  Then open [http://localhost:2229](http://localhost:2229) in your browser.
12
23
 
13
- ![CAW overview](https://athenadesign.com.au/caw/animation.svg)
14
-
15
24
  ## Unlock sustainable development
16
25
  Agents are capable coders but struggle to build software sustainably as the codebase and its complexity grow. Code reveals only so much and agents do not inherently know which parts of it to read or what the underlying intent was. Technical debt, technical mess, architectural mismatch and a host of problems creep in over time to grind progress to a halt.
17
26
 
@@ -33,12 +42,6 @@ CAW combines independently useful capabilities that integrate with each other se
33
42
 
34
43
  CAW was used to build CAW recursively, with version N building version N+1. In doing so, CAW was continuously dogfooded, proving the approach on a substantial software system.
35
44
 
36
- ## Content is king
37
-
38
- Why start with a blank slate?
39
-
40
- The prompts, templates and knowledge cartridges used to build CAW are also available as a free download from [Athena Design](https://athenadesign.com.au/). The CAW user manual can be downloaded separately and imported into the shared store, making it available to users and agents across every project. Use the 'Import Bundle' feature in project settings and shared store settings.
41
-
42
45
  # Capabilities
43
46
  ## Documents
44
47
 
@@ -224,6 +227,7 @@ caw stop # Stop the server
224
227
  caw status # Check if the server is running
225
228
  caw logs # Tail the server logs
226
229
  caw upgrade # Upgrade to the latest version
230
+ caw caddy setup # Sets up Caddy for use with CAW
227
231
  ```
228
232
 
229
233
  ## Prerequisites
@@ -232,33 +236,29 @@ caw upgrade # Upgrade to the latest version
232
236
 
233
237
  ## Optional Integrations
234
238
 
235
- All optional integrations are configured via Preferences > Infrastructure in the web UI. These integrations rely on 3rd party tools that require their own installation and setup outside of CAW. For detailed instructions visit [Athena Design](https://athenadesign.com.au/) or simply download and import the user manual and have agents perform the setup for you following the instructions provided.
239
+ All optional integrations are configured via Preferences > Infrastructure in the web UI. These integrations rely on 3rd party tools that require their own installation and setup outside of CAW. For detailed instructions visit [Athena Design](https://athenadesign.com.au/caw/) or read the fine manual (RTFM) that ships with CAW. Or even better, have agents RTFM for you and follow the instructions provided.
236
240
 
237
241
  ### Caddy
238
242
 
239
- Caddy is a browser-only integration. It relieves the ~6 concurrent HTTP/1.1
240
- connections per origin cap that otherwise silently starves the CAW UI and its
241
- EventSource streams (evidence: [Ad30347](https://athenadesign.com.au/caw/)).
242
- MCP clients and the CLI reach CAW over the direct loopback URL and do not
243
- need Caddy.
243
+ Caddy is a browser-only integration. It relieves the ~6 concurrent HTTP/1.1 connections per origin cap that otherwise silently starves the CAW UI and its EventSource streams. MCP clients and the CLI reach CAW over the direct loopback URL and do not need Caddy.
244
244
 
245
- Two commands provision it:
245
+ Provisioning is a three-command ordering — `caw start` must run first so that `~/.caw/config.json` exists (that is what `caw start` bootstraps), then Caddy is installed, then `caw caddy setup` reads the live `port` and `caddy.domain` from that config:
246
246
 
247
247
  ```bash
248
+ caw start
248
249
  brew install caddy
249
250
  caw caddy setup
250
251
  ```
251
252
 
252
- `caw caddy setup` generates `~/.caw/Caddyfile` from the live `port` and
253
- `caddy.domain`, provisions the `com.caw.caddy` launchd user agent, adds
254
- Caddy's local root to the System keychain (sudo prompt once, on a machine
255
- that has never trusted Caddy), and cuts the server over so the browser
256
- reaches `https://<caddy.domain>` with no certificate interstitial. Enables
257
- HTTPS and HTTP/2 and gives you `caw.localhost` in place of `localhost:2229`.
253
+ Run them in that order. On a machine where `caw start` has never run, `caw caddy setup` short-circuits in Phase 1 with the `envdir-uninitialised` outcome (exit 1) and prints a one-line diagnostic naming the resolved missing `config.json` path — no mutation, no `sudo` prompt, no TTY probe.
254
+
255
+ `caw caddy setup` generates `~/.caw/Caddyfile` from the live `port` and `caddy.domain`, provisions the `com.caw.caddy` launchd user agent, adds Caddy's local root to the System keychain (sudo prompt once, on a machine that has never trusted Caddy), and cuts the server over so the browser reaches `https://<caddy.domain>` with no certificate interstitial. Enables HTTPS and HTTP/2 and gives you `caw.localhost` in place of `localhost:2229`.
258
256
 
259
257
  ### PM2
260
258
 
261
- - Enable automatic launch on machine start
259
+ - Run CAW under a process manager so it restarts by itself after a crash
260
+ - Set `"process_manager": "pm2"` in `~/.caw/config.json`, or use Preferences > Infrastructure
261
+ - Starting on boot is PM2's own feature rather than something CAW configures. Run `pm2 startup` once, follow the command it prints, then `pm2 save` while CAW is running
262
262
 
263
263
  ### Docker
264
264
 
@@ -272,6 +272,107 @@ HTTPS and HTTP/2 and gives you `caw.localhost` in place of `localhost:2229`.
272
272
 
273
273
  - Enable PR and other GitHub capabilities
274
274
 
275
+ ## Getting started / tutorial
276
+
277
+ The quick start described at the top of this page will install CAW and allow you to see the user interface. Then what? CAW provides a lot of capability, but it is content driven. After first installing it, you start with an empty slate (aside from the user manual) and may struggle to see the point.
278
+
279
+ This section aims to get you started with a project and with the following:
280
+ - A CAW project (for an existing project or for a new project)
281
+ - A skeleton knowledge base structure (suitable for website or application development) comprising:
282
+ - Product section
283
+ - Architecture and design
284
+ - Developer guide
285
+ - Story tracks, prompt templates, document templates and saved searches hooked up to the skeleton knowledge base above
286
+
287
+ Think of the skeleton knowledge base as the 'context' that agents build and maintain in parallel to the codebase and the tracks and templates as the 'agentic workflows' that enable you to have an automated and repeatable process specific to your project. Note that the tracks, prompts and other templates are based off the same prompts and templates used to build CAW itself.
288
+
289
+ ### Step 1 - Get CAW installed and running
290
+
291
+ As per quick start (and Caddy is highly recommended as well) the following gets you started. These instructions assume MacOS and you have homebrew installed.
292
+
293
+ ```bash
294
+ npm install -g @kelceyp/caw
295
+ caw start
296
+ brew install caddy
297
+ caw caddy setup
298
+ ```
299
+
300
+ Point your browser at https://caw.localhost (http://localhost:2229 if you don't install caddy) and you should see the CAW landing page.
301
+
302
+ ### Step 2 - Enable agents
303
+
304
+ In the left sidebar you should see 'Preferences' above 'About'. Click preferences and then the agents tab and you should see the following.
305
+
306
+ ![Enable agents](https://athenadesign.com.au/caw/enable-agents.svg)
307
+
308
+ Expand the enable the agents you'd like to use with CAW.
309
+
310
+ Enabling Claude Code, Codex and/or Cursor enables CAW to launch those programs (using either their headless CLI commands or terminal emulation). This enables you to run your locally installed agents via the CAW UI (Jobs tab and also a Story's Jobs tab) and also enables agents to launch other agents this way as well. They need to be logged in and have their permissions configured accordingly.
311
+
312
+ The prompt templates provided leverage this capability (e.g. have codex supervise claude doing a design etc.).
313
+
314
+ ### Step 3 - Create a project
315
+
316
+ A project points CAW at one codebase. In the left sidebar under **PROJECTS**, click **+**.
317
+
318
+ ![Create project](https://athenadesign.com.au/caw/create-project.svg)
319
+
320
+ | Field | What it is |
321
+ |---|---|
322
+ | **Project Path** | The directory on disk. It has to exist already — there's a Browse button. |
323
+ | **Slug** | The project's address. It shows up in the web URL, the REST path and the MCP endpoint you'll need in the next step. |
324
+ | **Project Name** | What you'll see in the sidebar. |
325
+
326
+ Name and slug fill themselves in from the path. If the directory is a git repo with an `origin` remote, the slug takes the last segment of that remote — so a repo cloned to `~/work/frontend` from `acme/acme-web` gives you the name `frontend` and the slug `acme-web`. Change either before you submit; the slug can't be changed afterwards.
327
+
328
+ Each project gets its own store for project-specific content, and is also wired to the one shared store that every project on the installation can read.
329
+
330
+ *For more details see **Getting Started → Your First Project** in the CAW user manual.*
331
+
332
+ ### Step 4 - Configure MCP for this project
333
+
334
+ CAW writes this for you. Go to the project's **Settings → MCP**.
335
+
336
+ ![Configure MCP](https://athenadesign.com.au/caw/configure-mcp.svg)
337
+
338
+ At the top is the endpoint — a single URL ending `/mcp/p/<your-slug>`. Below it, a section each for **Claude Code**, **Codex** and **Cursor**. Each one builds the exact snippet that client expects around that URL, with a Copy button. For Claude Code, choose a scope first — Local, Project or User — and the command changes to match.
339
+
340
+ One thing worth knowing now rather than later: **this is per project**. The endpoint contains one slug, so a second project needs a second entry. Your agent will carry on working perfectly against the first project and give you no sign that it can't see the second.
341
+
342
+ *For more details see **Getting Started → Connecting Your Agents** in the CAW user manual.*
343
+
344
+ ### Step 5 - Import a bundle
345
+
346
+ A bundle is a zip of content — documents, templates, story tracks — that you import into a store.
347
+
348
+ ![Import a bundle](https://athenadesign.com.au/caw/import-a-bundle.svg)
349
+
350
+ The user manual arrives on its own. CAW downloads and installs it into the shared store the first time it starts, which is why the Documents tree isn't completely empty.
351
+
352
+ For everything else, download from [Athena Design](https://athenadesign.com.au/) and use **Import Bundle** — in project settings for the project store, or in application preferences for the shared store.
353
+
354
+ Start with the **CAW bundle**. It carries the skeleton knowledge base described above, along with the story tracks, prompt templates, document templates and saved searches already wired to it. They're the same ones used to build CAW.
355
+
356
+ Importing is additive: nothing already in the store is overwritten.
357
+
358
+ *For more details see **Getting Started → Finding and Installing Bundles** in the CAW user manual.*
359
+
360
+ ### Step 6 - Run the bootstrap prompt
361
+
362
+ The CAW bundle ships a bootstrap prompt for each agent — **bootstrap using claude**, **bootstrap using codex**, **bootstrap using cursor**. Render the one matching an agent you enabled in Step 2.
363
+
364
+ It offers two ways to work:
365
+
366
+ - **Interview** — it asks you about the project and writes the first draft of the knowledge base from your answers.
367
+ - **Walkthrough** — it reads the codebase and proposes what it found, for you to correct.
368
+
369
+ Either way you come out with the product, architecture and developer-guide sections filled in well enough that agents stop guessing, and a north star to aim at. This is the step that turns an empty CAW into your CAW.
370
+
371
+ *For more details see **Getting Started → Setting Up Your Knowledge Base** in the CAW user manual.*
372
+
373
+ The prompts, templates and knowledge cartridges used to build CAW are also available as a free download from [Athena Design](https://athenadesign.com.au/). Use the 'Import Bundle' feature in project settings and shared store settings.
374
+
375
+
275
376
  ## Links
276
377
 
277
378
  - [Report an issue or request a feature](https://github.com/kelceyp-mcp-servers/caw-feedback/issues)
package/dist/caw.js CHANGED
@@ -10928,6 +10928,9 @@ function readConfigWithDefaults(envDir) {
10928
10928
  function writeConfig(envDir, data) {
10929
10929
  atomicWrite(configPath(envDir), data);
10930
10930
  }
10931
+ function configExists(envDir) {
10932
+ return fs4.existsSync(configPath(envDir));
10933
+ }
10931
10934
  function mergeConfig(envDir) {
10932
10935
  const active = readConfig(envDir);
10933
10936
  const pending = readPendingConfig(envDir);
@@ -11727,9 +11730,6 @@ function resolveEnvDir(rawEnvDir) {
11727
11730
  }
11728
11731
  return path8.resolve(rawEnvDir);
11729
11732
  }
11730
- function configExists(envDir) {
11731
- return fs8.existsSync(path8.join(envDir, "config.json"));
11732
- }
11733
11733
  function validateEnvFile(envDir) {
11734
11734
  const envFilePath = path8.join(envDir, ".env");
11735
11735
  if (!fs8.existsSync(envFilePath)) {
@@ -12060,9 +12060,6 @@ function resolveEnvDir2(rawEnvDir) {
12060
12060
  }
12061
12061
  return path9.resolve(rawEnvDir);
12062
12062
  }
12063
- function configExists2(envDir) {
12064
- return fs9.existsSync(path9.join(envDir, "config.json"));
12065
- }
12066
12063
  async function checkHealth2(port) {
12067
12064
  try {
12068
12065
  const response = await fetch(`http://localhost:${port}/health`);
@@ -12131,7 +12128,7 @@ var create3 = () => {
12131
12128
  return createCommand("stop").summary("Stop the caw server").param((p) => p.name("env-dir").type("string").flag("env-dir").default("~/.caw/")).param((p) => p.name("force").type("boolean").flag("force").default(false)).run(async (ctx) => {
12132
12129
  const envDir = resolveEnvDir2(ctx.params["env-dir"]);
12133
12130
  const force = ctx.params.force;
12134
- if (!fs9.existsSync(envDir) || !configExists2(envDir)) {
12131
+ if (!fs9.existsSync(envDir) || !configExists(envDir)) {
12135
12132
  console.log("Server is not running (no environment directory or config found).");
12136
12133
  process.exit(0);
12137
12134
  }
@@ -12206,9 +12203,6 @@ function resolveEnvDir3(rawEnvDir) {
12206
12203
  }
12207
12204
  return path11.resolve(rawEnvDir);
12208
12205
  }
12209
- function configExists3(envDir) {
12210
- return fs11.existsSync(path11.join(envDir, "config.json"));
12211
- }
12212
12206
  async function fetchHealth(port) {
12213
12207
  try {
12214
12208
  const response = await fetch(`http://localhost:${port}/health`);
@@ -12265,7 +12259,7 @@ function getUptimeFromPm2(runState) {
12265
12259
  var create4 = () => {
12266
12260
  return createCommand("status").summary("Show caw server status").param((p) => p.name("env-dir").type("string").flag("env-dir").default("~/.caw/")).run(async (ctx) => {
12267
12261
  const envDir = resolveEnvDir3(ctx.params["env-dir"]);
12268
- if (!fs11.existsSync(envDir) || !configExists3(envDir)) {
12262
+ if (!fs11.existsSync(envDir) || !configExists(envDir)) {
12269
12263
  console.log("Server: not configured");
12270
12264
  console.log(` No environment found at ${envDir}`);
12271
12265
  process.exit(0);
@@ -12377,9 +12371,6 @@ function resolveEnvDir5(rawEnvDir) {
12377
12371
  }
12378
12372
  return path13.resolve(rawEnvDir);
12379
12373
  }
12380
- function configExists4(envDir) {
12381
- return fs13.existsSync(path13.join(envDir, "config.json"));
12382
- }
12383
12374
  async function checkHealth3(port) {
12384
12375
  try {
12385
12376
  const response = await fetch(`http://localhost:${port}/health`);
@@ -12460,7 +12451,7 @@ var create6 = () => {
12460
12451
  let skipInstall = false;
12461
12452
  if (import_semver2.default.gte(installedVersion, latestServerVersion)) {
12462
12453
  let needsRestart = false;
12463
- if (fs13.existsSync(envDir) && configExists4(envDir)) {
12454
+ if (fs13.existsSync(envDir) && configExists(envDir)) {
12464
12455
  const config = readConfigWithDefaults(envDir);
12465
12456
  const pm = createProcessManager(config, envDir);
12466
12457
  if (pm.isRunning().running) {
@@ -12508,7 +12499,7 @@ var create6 = () => {
12508
12499
  process.exit(0);
12509
12500
  }
12510
12501
  let serverWasStopped = false;
12511
- if (fs13.existsSync(envDir) && configExists4(envDir)) {
12502
+ if (fs13.existsSync(envDir) && configExists(envDir)) {
12512
12503
  const config = readConfigWithDefaults(envDir);
12513
12504
  const pm = createProcessManager(config, envDir);
12514
12505
  const runState = pm.isRunning();
@@ -12559,7 +12550,7 @@ var create6 = () => {
12559
12550
  process.exit(1);
12560
12551
  }
12561
12552
  }
12562
- if (serverWasStopped || fs13.existsSync(envDir) && configExists4(envDir)) {
12553
+ if (serverWasStopped || fs13.existsSync(envDir) && configExists(envDir)) {
12563
12554
  const config = readConfigWithDefaults(envDir);
12564
12555
  const pm = createProcessManager(config, envDir);
12565
12556
  const newServerInfo = resolve();
@@ -12599,9 +12590,6 @@ function resolveEnvDir6(rawEnvDir) {
12599
12590
  }
12600
12591
  return path14.resolve(rawEnvDir);
12601
12592
  }
12602
- function configExists5(envDir) {
12603
- return fs14.existsSync(path14.join(envDir, "config.json"));
12604
- }
12605
12593
  function buildChangeSummary2(active, pending) {
12606
12594
  const changes = [];
12607
12595
  for (const key of Object.keys(pending)) {
@@ -12639,7 +12627,7 @@ var create7 = () => {
12639
12627
  }
12640
12628
  const envDir = resolveEnvDir6(ctx.params["env-dir"]);
12641
12629
  const force = ctx.params.force;
12642
- if (fs14.existsSync(envDir) && configExists5(envDir)) {
12630
+ if (fs14.existsSync(envDir) && configExists(envDir)) {
12643
12631
  const config2 = readConfigWithDefaults(envDir);
12644
12632
  const pm3 = createProcessManager(config2, envDir);
12645
12633
  const result = await executeStop(pm3, config2, force, ctx.prompt, envDir);
@@ -12671,7 +12659,7 @@ How would you like to proceed?`,
12671
12659
  process.exit(0);
12672
12660
  }
12673
12661
  }
12674
- if (!configExists5(envDir)) {
12662
+ if (!configExists(envDir)) {
12675
12663
  console.log(`Creating environment directory: ${envDir}`);
12676
12664
  bootstrap(envDir);
12677
12665
  console.log("Wrote default config.json");
@@ -13089,7 +13077,7 @@ async function classifyPhase1({ options, deps }) {
13089
13077
  hasTty,
13090
13078
  uid,
13091
13079
  homeDir,
13092
- readConfig: readConfig2 = readConfigWithDefaults,
13080
+ readConfig: readConfigDep = readConfig,
13093
13081
  generators,
13094
13082
  paths = {}
13095
13083
  } = deps;
@@ -13100,6 +13088,28 @@ async function classifyPhase1({ options, deps }) {
13100
13088
  const plistPath = paths.plist ?? path15.join(homeDir, "Library", "LaunchAgents", `${options.label}.plist`);
13101
13089
  const stdoutLogPath = paths.stdoutLog ?? path15.join(homeDir, ".caw", "caddy.out.log");
13102
13090
  const stderrLogPath = paths.stderrLog ?? path15.join(homeDir, ".caw", "caddy.err.log");
13091
+ let activeConfig;
13092
+ try {
13093
+ activeConfig = readConfigDep(options.envDir);
13094
+ } catch (e) {
13095
+ if (e.code === "ENOENT") {
13096
+ return {
13097
+ tag: "envdir-uninitialised",
13098
+ exitCode: 1,
13099
+ message: `CAW is not configured on this machine ` + `(no config at ${path15.join(options.envDir, "config.json")}). ` + `Run \`caw start\` first, then \`brew install caddy\`, ` + `then re-run \`caw caddy setup\`.`
13100
+ };
13101
+ }
13102
+ return { tag: "envdir-malformed", exitCode: 1, message: e.message };
13103
+ }
13104
+ const domain = activeConfig?.caddy?.domain;
13105
+ const upstreamPort = activeConfig?.port;
13106
+ if (!domain || upstreamPort === undefined || upstreamPort === null) {
13107
+ return {
13108
+ tag: "envdir-malformed",
13109
+ exitCode: 1,
13110
+ message: `envDir ${options.envDir} config is missing caddy.domain or port`
13111
+ };
13112
+ }
13103
13113
  let whichStdout = "";
13104
13114
  try {
13105
13115
  whichStdout = (await execFileAsync(_execFile, "which", ["caddy"])).trim();
@@ -13138,17 +13148,6 @@ async function classifyPhase1({ options, deps }) {
13138
13148
  } else {
13139
13149
  return { tag: "no-tty-trust-needed", exitCode: 1, message: "Trust needed but no TTY; re-run in a terminal or pass --skip-trust (which does not succeed)" };
13140
13150
  }
13141
- let activeConfig;
13142
- try {
13143
- activeConfig = readConfig2(options.envDir);
13144
- } catch (e) {
13145
- return { tag: "envdir-malformed", exitCode: 1, message: e.message };
13146
- }
13147
- const domain = activeConfig?.caddy?.domain;
13148
- const upstreamPort = activeConfig?.port;
13149
- if (!domain || upstreamPort === undefined || upstreamPort === null) {
13150
- return { tag: "envdir-malformed", exitCode: 1, message: `envDir ${options.envDir} config is missing caddy.domain or port` };
13151
- }
13152
13151
  let printOut = null;
13153
13152
  try {
13154
13153
  printOut = await execFileAsync(_execFile, "launchctl", ["print", `gui/${uid}/${options.label}`]);
@@ -14197,7 +14196,7 @@ function createSetupHandler(deps = {}) {
14197
14196
  hasTty: deps.hasTty ?? Boolean(process.stdin?.isTTY),
14198
14197
  uid: deps.uid ?? (process.getuid ? process.getuid() : 0),
14199
14198
  homeDir,
14200
- readConfig: deps.readConfig ?? readConfigWithDefaults,
14199
+ readConfig: deps.readConfig ?? readConfig,
14201
14200
  generators,
14202
14201
  paths: deps.paths ?? {}
14203
14202
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kelceyp/caw",
3
- "version": "1.0.39",
3
+ "version": "1.0.41",
4
4
  "type": "module",
5
5
  "description": "Unified Web/MCP server with React web app. MD document management, handlebars templating, agent orchestration (aka browser based reskinning of claude code, codex and cursor that allows any of these agents to use any other as subagents) and user stories",
6
6
  "keywords": [