Skip to content

Commit e73b6a2

Browse files
committed
docs: USAGE.md sections for claw init (ultraworkers#142) and claw state (ultraworkers#139)
Add two missing sections documenting the recently-fixed commands: - **Initialize a repository**: Shows both text and JSON output modes for `claw init`. Explains that structured JSON fields (created[], updated[], skipped[], artifacts[]) allow claws to detect per-artifact state without substring-matching prose. Documents idempotency. - **Inspect worker state**: Documents `claw state` and the prerequisite that a worker must have executed at least once. Includes the helpful error message and remediation hints (claw or claw prompt <text>) so users discovering the command for the first time see actionable guidance. These sections complement the product fixes in ultraworkers#142 (init JSON structure) and ultraworkers#139 (state error actionability) by documenting the contract from a user perspective. Related: ROADMAP ultraworkers#142 (structured init output), ultraworkers#139 (worker-state discoverability).
1 parent 541c5bb commit e73b6a2

1 file changed

Lines changed: 45 additions & 0 deletions

File tree

USAGE.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,26 @@ cd rust
5252

5353
**Note:** Diagnostic verbs (`doctor`, `status`, `sandbox`, `version`) support `--output-format json` for machine-readable output. Invalid suffix arguments (e.g., `--json`) are now rejected at parse time rather than falling through to prompt dispatch.
5454

55+
### Initialize a repository
56+
57+
Set up a new repository with `.claw` config, `.claw.json`, `.gitignore` entries, and a `CLAUDE.md` guidance file:
58+
59+
```bash
60+
cd /path/to/your/repo
61+
./target/debug/claw init
62+
```
63+
64+
Text mode (human-readable) shows artifact creation summary with project path and next steps. Idempotent — running multiple times in the same repo marks already-created files as "skipped".
65+
66+
JSON mode for scripting:
67+
```bash
68+
./target/debug/claw init --output-format json
69+
```
70+
71+
Returns structured output with `project_path`, `created[]`, `updated[]`, `skipped[]` arrays (one per artifact), and `artifacts[]` carrying each file's `name` and machine-stable `status` tag. The legacy `message` field preserves backward compatibility.
72+
73+
**Why structured fields matter:** Claws can detect per-artifact state (`created` vs `updated` vs `skipped`) without substring-matching human prose. Use the `created[]`, `updated[]`, and `skipped[]` arrays for conditional follow-up logic (e.g., only commit if files were actually created, not just updated).
74+
5575
### Interactive REPL
5676

5777
```bash
@@ -80,6 +100,31 @@ cd rust
80100
./target/debug/claw --output-format json prompt "status"
81101
```
82102

103+
### Inspect worker state
104+
105+
The `claw state` command reads `.claw/worker-state.json`, which is written by the interactive REPL or a one-shot prompt when a worker executes a task. This file contains the worker ID, session reference, model, and permission mode.
106+
107+
Prerequisite: You must run `claw` (interactive REPL) or `claw prompt <text>` at least once in the repository to produce the worker state file.
108+
109+
```bash
110+
cd rust
111+
./target/debug/claw state
112+
```
113+
114+
JSON mode:
115+
```bash
116+
./target/debug/claw state --output-format json
117+
```
118+
119+
If you run `claw state` before any worker has executed, you will see a helpful error:
120+
```
121+
error: no worker state file found at .claw/worker-state.json
122+
Hint: worker state is written by the interactive REPL or a non-interactive prompt.
123+
Run: claw # start the REPL (writes state on first turn)
124+
Or: claw prompt <text> # run one non-interactive turn
125+
Then rerun: claw state [--output-format json]
126+
```
127+
83128
## Model and permission controls
84129

85130
```bash

0 commit comments

Comments
 (0)