1  # Contributing to SwarmClaw
 2  
 3  Thanks for considering a contribution. SwarmClaw is an open-source autonomous-agent runtime, and the project moves faster when issues and PRs come with concrete repro steps and small focused changes. This guide lays out what we look for.
 4  
 5  ## Filing an issue
 6  
 7  Bugs are easiest to land when the report contains:
 8  
 9  - The SwarmClaw version (visible in the sidebar footer or `npm ls @swarmclawai/swarmclaw`).
10  - How you are running it (npm install, Docker image, packaged desktop app, hosted on Render / Fly / Railway).
11  - The provider, model, and any relevant connector / extension involved.
12  - The exact error text, stack trace, or log line.
13  - A minimal sequence of steps to reproduce.
14  - Any file paths or function names you suspect, especially if you have already opened the source.
15  
16  [Issue #39](https://github.com/swarmclawai/swarmclaw/issues/39) is the gold-standard bug report we have received: it identified three concrete root causes by file path and line number, explained how each one combined to produce the symptom, and proposed a minimal fix. The PR was almost mechanical to land. If your report can look like that, please make it look like that.
17  
18  ## Filing a feature request
19  
20  Good feature requests are easy to scope and easy to say yes (or no) to. We look for:
21  
22  - A short motivation: what real workflow is blocked today?
23  - One or more user stories ("As a SwarmClaw user, I want to ...").
24  - A list of functional requirements with stable IDs (`FR-1`, `FR-2`, ...). Distinguish must-have, should-have, nice-to-have.
25  - Open design questions called out explicitly. The implementer will need decisions on those before writing code; flagging them up front saves a round trip.
26  - Any relevant external documentation links (provider API docs, RFCs, etc.).
27  
28  [Issue #40](https://github.com/swarmclawai/swarmclaw/issues/40) is the gold-standard feature request: a clear motivation, eight numbered requirements split by priority, and three explicit design questions for the implementer. That made it possible to commit to a concrete plan in a single planning round.
29  
30  ## Sending a pull request
31  
32  Before you push:
33  
34  1. **Keep the PR focused.** One bug fix or one feature per PR. Refactors and unrelated cleanup should land separately.
35  2. **Add a regression test where it makes sense.** A unit test that would have caught the bug, or that pins the new behavior, is the durable artifact.
36  3. **Run `npm run lint:baseline`.** It must report `No net-new lint issues detected`. If you fix existing lint violations along the way, run `npm run lint:baseline:update` to lock the new (lower) baseline in.
37  4. **Do not suppress lint rules.** If a rule is genuinely wrong for the project, change the rule in the lint config with a clear justification rather than disabling it inline.
38  5. **Avoid `any`.** Use `unknown`, a `Record<string, unknown>`, or define a real interface. The type system is the safety net.
39  6. **Prefer editing existing files** over adding new abstractions. Three similar lines beats a premature helper.
40  
41  ## Commit messages
42  
43  - Short imperative summary on the first line, body explains the *why* below.
44  - Reference the issue number ("Reported as issue #39") in the body when relevant.
45  - No references to AI tooling. Write commit messages as if a human authored the code.
46  - No em dashes. Use a colon, parentheses, or two sentences instead.
47  
48  ## Local development
49  
50  ```sh
51  git clone https://github.com/swarmclawai/swarmclaw.git
52  cd swarmclaw
53  npm install
54  npm run dev      # starts the dev server on port 3456
55  ```
56  
57  Useful npm scripts while iterating:
58  
59  ```sh
60  npm run lint:baseline           # release gate; must pass before merging
61  npx tsx --test path/to/file.test.ts   # run a single Node-test file
62  npm run test:cli                # CLI test suite
63  npm run test:openclaw           # OpenClaw integration suite
64  npm run test:setup              # setup wizard suite
65  NODE_ENV=production npm run build:ci   # production build sanity check
66  ```
67  
68  If you are running multiple agents against the same checkout, please do not kill the dev server without checking with the other agent first; another agent may be actively testing against it.
69  
70  ## Where to look first
71  
72  - **`CLAUDE.md`** is the canonical project conventions reference. It covers storage patterns (`saveCollection`, `setIfChanged`), Zustand store rules, the chat-execution pipeline, terminal-tool boundaries, the extensions migration, the desktop-app architecture, and the release checklist. Read this first before any non-trivial change.
73  - **`src/lib/providers/`** for new provider integrations. Most new providers are OpenAI-compatible and can be added as a thin wrapper that delegates to `streamOpenAiChat`. See `claude.ts` and `anthropic.ts` for the raw HTTP / SSE pattern when a provider is not OpenAI-compatible.
74  - **`src/lib/server/session-tools/`** for new agent tools. Native tool builders go through the assembler in `session-tools/index.ts`; native tool names are deduplicated across all assembly phases.
75  - **`src/lib/server/chat-execution/`** for the chat loop, continuation evaluator, classifier, and tool-event tracker.
76  - **`src/lib/setup-defaults.ts`** is the single source of truth for provider display names, default models, `keyUrl` / `keyLabel` pairs, and starter agent kits. New providers must add an entry here.
77  
78  ## Releases
79  
80  Maintainers cut releases. Contributors do not need to bump versions or write release notes; PRs get bundled into the next `vX.Y.Z` tag and the maintainer publishes notes on the SwarmClaw site.
81  
82  ## Code of conduct
83  
84  Be kind. Critique the code, not the person. Assume good faith. Issues that are dismissive or hostile to other contributors will be closed.